Added doxygen comments
authorjwang36 <jwang36@7335b38e-4728-0410-8992-fb3ffe349368>
Wed, 23 Apr 2008 06:44:40 +0000 (06:44 +0000)
committerjwang36 <jwang36@7335b38e-4728-0410-8992-fb3ffe349368>
Wed, 23 Apr 2008 06:44:40 +0000 (06:44 +0000)
git-svn-id: https://buildtools.tianocore.org/svn/buildtools/trunk/BaseTools@1172 7335b38e-4728-0410-8992-fb3ffe349368

Source/Python/Workspace/WorkspaceDatabase.py

index 5bf8752..2ecbc17 100644 (file)
@@ -51,6 +51,7 @@ class DscBuildData(PlatformBuildClassObject):
         MODEL_PCD_DYNAMIC_EX_VPD        :   "DynamicExVpd",\r
     }\r
 \r
+    # dict used to convert part of [Defines] to members of DscBuildData directly\r
     _PROPERTY_ = {\r
         #\r
         # Required Fields\r
@@ -73,6 +74,17 @@ class DscBuildData(PlatformBuildClassObject):
     # used to compose dummy library class name for those forced library instances\r
     _NullLibraryNumber = 0\r
 \r
+    ## Constructor of DscBuildData\r
+    #\r
+    #  Initialize object of DscBuildData\r
+    #\r
+    #   @param      FilePath        The path of platform description file\r
+    #   @param      RawData         The raw data of DSC file\r
+    #   @param      BuildDataBase   Database used to retrieve module/package information\r
+    #   @param      Arch            The target architecture\r
+    #   @param      Platform        (not used for DscBuildData)\r
+    #   @param      Macros          Macros used for replacement in DSC file\r
+    #\r
     def __init__(self, FilePath, RawData, BuildDataBase, Arch='COMMON', Platform='DUMMY', Macros={}):\r
         self.DescFilePath = FilePath\r
         self._RawData = RawData\r
@@ -81,65 +93,19 @@ class DscBuildData(PlatformBuildClassObject):
         self._Macros = Macros\r
         self._Clear()\r
 \r
-    def __repr__(self):\r
-        S = '[Platform.%s]\n' % self.Arch\r
-        S += "\tName = %s\n" % self.PlatformName\r
-        S += "\tGuid = %s\n" % self.Guid\r
-        S += "\tVer = %s\n" % self.Version\r
-        S += "\n"\r
-        S += "\tSpecification = %s\n" % self.DscSpecification\r
-        S += "\tOutputDirectory = %s\n" % self.OutputDirectory \r
-        S += "\tSupArchList = %s\n" % self.SupArchList     \r
-        S += "\tBuildTargets = %s\n" % self.BuildTargets    \r
-        S += "\tSkuName = %s\n" % self.SkuName           \r
-        S += "\tFlashDefinition = %s\n" % self.FlashDefinition \r
-        S += "\tBuildNumber = %s\n" % self.BuildNumber     \r
-        S += "\tMakefileName = %s\n" % self.MakefileName    \r
-        S += "\tBsBaseAddress = %s\n" % self.BsBaseAddress   \r
-        S += "\tRtBaseAddress = %s\n" % self.RtBaseAddress   \r
-\r
-        S += '  <SkuId>\n'\r
-        for SkuName in self.SkuIds:\r
-            S += "\t%s = %s\n" % (SkuName, self.SkuIds[SkuName])\r
-\r
-        #S += '  <LibraryClass>\n'\r
-        #ModuleTypeList = set()\r
-        #LibraryClassList = set()\r
-        #for LibraryClass,ModuleType in self.LibraryClasses:\r
-        #    LibraryClassList.add(LibraryClass)\r
-        #    ModuleTypeList.add(ModuleType)\r
-        #LibraryClassList = list(LibraryClassList)\r
-        #ModuleTypeList = list(ModuleTypeList)\r
-        #LibraryClassList.sort()\r
-        #ModuleTypeList.sort()\r
-        #for LibraryClass in LibraryClassList:\r
-        #    for ModuleType in ModuleTypeList:\r
-        #        if not (LibraryClass,ModuleType) in self.LibraryClasses:\r
-        #            continue \r
-        #        S += "\t%32s, %-24s = %s\n" % (LibraryClass, ModuleType, self.LibraryClasses[LibraryClass,ModuleType])\r
-        \r
-        S += '  <PCD>\n'\r
-        for Name, Guid in self.Pcds:\r
-            S += "\t%s.%s\n\t\t%s\n" % (Guid, Name, str(self.Pcds[Name, Guid]))\r
-        \r
-        S += '  <BuildOption>\n'\r
-        for ToolChainFamily,ToolChain in self.BuildOptions:\r
-            S += "\t%s:%s = %s\n" % (ToolChainFamily, ToolChain, self.BuildOptions[ToolChainFamily, ToolChain])\r
-\r
-        S += '  <Module>\n'\r
-        S += "\t" + "\n\t".join([str(M) for M in self.Modules]) + '\n'\r
-        return S\r
-\r
     ## XXX[key] = value\r
     def __setitem__(self, key, value):\r
         self.__dict__[self._PROPERTY_[key]] = value\r
+\r
     ## value = XXX[key]\r
     def __getitem__(self, key):\r
         return self.__dict__[self._PROPERTY_[key]]\r
+\r
     ## "in" test support\r
     def __contains__(self, key):\r
         return key in self._PROPERTY_\r
 \r
+    ## Set all internal used members of DscBuildData to None\r
     def _Clear(self):\r
         self._Header            = None\r
         self._PlatformName      = None\r
@@ -162,21 +128,37 @@ class DscBuildData(PlatformBuildClassObject):
         self._Pcds              = None\r
         self._BuildOptions      = None\r
 \r
+    ## Get architecture\r
     def _GetArch(self):\r
         return self._Arch\r
 \r
+    ## Set architecture\r
+    #   \r
+    #   Changing the default ARCH to another may affect all other information\r
+    # because all information in a platform may be ARCH-related. That's\r
+    # why we need to clear all internal used members, in order to cause all \r
+    # information to be re-retrieved.\r
+    # \r
+    #   @param  Value   The value of ARCH\r
+    # \r
     def _SetArch(self, Value):\r
         if self._Arch == Value:\r
             return\r
         self._Arch = Value\r
         self._Clear()\r
 \r
+    ## Retrieve all information in [Defines] section\r
+    #\r
+    #   (Retriving all [Defines] information in one-shot is just to save time.)\r
+    # \r
     def _GetHeaderInfo(self):\r
         RecordList = self._RawData[MODEL_META_DATA_HEADER, self._Arch]\r
         for Record in RecordList:\r
             Name = Record[0]\r
+            # items defined _PROPERTY_ don't need additional processing\r
             if Name in self:\r
                 self[Name] = Record[1]\r
+            # some special items in [Defines] section need special treatment\r
             elif Name == TAB_DSC_DEFINES_OUTPUT_DIRECTORY:\r
                 self._OutputDirectory = NormPath(Record[1], self._Macros)\r
             elif Name == TAB_DSC_DEFINES_FLASH_DEFINITION:\r
@@ -188,8 +170,10 @@ class DscBuildData(PlatformBuildClassObject):
             elif Name == TAB_DSC_DEFINES_SKUID_IDENTIFIER:\r
                 if self._SkuName == None:\r
                     self._SkuName = Record[1]\r
+        # set _Header to non-None in order to avoid database re-querying\r
         self._Header = 'DUMMY'\r
 \r
+    ## Retrieve platform name\r
     def _GetPlatformName(self):\r
         if self._PlatformName == None:\r
             if self._Header == None:\r
@@ -198,6 +182,7 @@ class DscBuildData(PlatformBuildClassObject):
                 EdkLogger.error('build', ATTRIBUTE_NOT_AVAILABLE, "No PLATFORM_NAME", File=self.DescFilePath)\r
         return self._PlatformName\r
 \r
+    ## Retrieve file guid\r
     def _GetFileGuid(self):\r
         if self._Guid == None:\r
             if self._Header == None:\r
@@ -206,6 +191,7 @@ class DscBuildData(PlatformBuildClassObject):
                 EdkLogger.error('build', ATTRIBUTE_NOT_AVAILABLE, "No FILE_GUID", File=self.DescFilePath)\r
         return self._Guid\r
 \r
+    ## Retrieve platform version\r
     def _GetVersion(self):\r
         if self._Version == None:\r
             if self._Header == None:\r
@@ -214,6 +200,7 @@ class DscBuildData(PlatformBuildClassObject):
                 self._Version = ''\r
         return self._Version\r
 \r
+    ## Retrieve platform description file version\r
     def _GetDscSpec(self):\r
         if self._DscSpecification == None:\r
             if self._Header == None:\r
@@ -222,6 +209,7 @@ class DscBuildData(PlatformBuildClassObject):
                 self._DscSpecification = ''\r
         return self._DscSpecification\r
 \r
+    ## Retrieve OUTPUT_DIRECTORY\r
     def _GetOutpuDir(self):\r
         if self._OutputDirectory == None:\r
             if self._Header == None:\r
@@ -230,6 +218,7 @@ class DscBuildData(PlatformBuildClassObject):
                 self._OutputDirectory = os.path.join("Build", self._PlatformName)\r
         return self._OutputDirectory\r
 \r
+    ## Retrieve SUPPORTED_ARCHITECTURES\r
     def _GetSupArch(self):\r
         if self._SupArchList == None:\r
             if self._Header == None:\r
@@ -238,6 +227,7 @@ class DscBuildData(PlatformBuildClassObject):
                 self._SupArchList = ARCH_LIST\r
         return self._SupArchList\r
 \r
+    ## Retrieve BUILD_TARGETS\r
     def _GetBuildTarget(self):\r
         if self._BuildTargets == None:\r
             if self._Header == None:\r
@@ -246,6 +236,7 @@ class DscBuildData(PlatformBuildClassObject):
                 self._BuildTargets = ['DEBUG', 'RELEASE']\r
         return self._BuildTargets\r
 \r
+    ## Retrieve SKUID_IDENTIFIER\r
     def _GetSkuName(self):\r
         if self._SkuName == None:\r
             if self._Header == None:\r
@@ -254,6 +245,7 @@ class DscBuildData(PlatformBuildClassObject):
                 self._SkuName = 'DEFAULT'\r
         return self._SkuName\r
 \r
+    ## Override SKUID_IDENTIFIER\r
     def _SetSkuName(self, Value):\r
         if Value in self.SkuIds:\r
             self._SkuName = Value\r
@@ -266,6 +258,7 @@ class DscBuildData(PlatformBuildClassObject):
                 self._FlashDefinition = ''\r
         return self._FlashDefinition\r
 \r
+    ## Retrieve FLASH_DEFINITION\r
     def _GetBuildNumber(self):\r
         if self._BuildNumber == None:\r
             if self._Header == None:\r
@@ -274,6 +267,7 @@ class DscBuildData(PlatformBuildClassObject):
                 self._BuildNumber = ''\r
         return self._BuildNumber\r
 \r
+    ## Retrieve MAKEFILE_NAME\r
     def _GetMakefileName(self):\r
         if self._MakefileName == None:\r
             if self._Header == None:\r
@@ -282,6 +276,7 @@ class DscBuildData(PlatformBuildClassObject):
                 self._MakefileName = ''\r
         return self._MakefileName\r
 \r
+    ## Retrieve BsBaseAddress\r
     def _GetBsBaseAddress(self):\r
         if self._BsBaseAddress == None:\r
             if self._Header == None:\r
@@ -290,6 +285,7 @@ class DscBuildData(PlatformBuildClassObject):
                 self._BsBaseAddress = ''\r
         return self._BsBaseAddress\r
 \r
+    ## Retrieve RtBaseAddress\r
     def _GetRtBaseAddress(self):\r
         if self._RtBaseAddress == None:\r
             if self._Header == None:\r
@@ -298,6 +294,7 @@ class DscBuildData(PlatformBuildClassObject):
                 self._RtBaseAddress = ''\r
         return self._RtBaseAddress\r
 \r
+    ## Retrieve [SkuIds] section information\r
     def _GetSkuIds(self):\r
         if self._SkuIds == None:\r
             self._SkuIds = {}\r
@@ -314,6 +311,7 @@ class DscBuildData(PlatformBuildClassObject):
                 self._SkuIds['DEFAULT'] = 0\r
         return self._SkuIds\r
 \r
+    ## Retrieve [Components] section information\r
     def _GetModules(self):\r
         if self._Modules != None:\r
             return self._Modules\r
@@ -324,6 +322,7 @@ class DscBuildData(PlatformBuildClassObject):
             ModuleFile = NormPath(Record[0], self._Macros)\r
             ModuleId = Record[5]\r
             LineNo = Record[6]\r
+            # check the file existence\r
             if not ValidFile(ModuleFile):\r
                 EdkLogger.error('build', FILE_NOT_FOUND, File=self.DescFilePath, \r
                                 ExtraData=ModuleFile, Line=LineNo)\r
@@ -374,6 +373,7 @@ class DscBuildData(PlatformBuildClassObject):
                             )\r
                     Module.Pcds[PcdCName, TokenSpaceGuid] = Pcd\r
 \r
+            # get module private build options\r
             RecordList = self._RawData[MODEL_META_DATA_BUILD_OPTION, self._Arch, None, ModuleId]\r
             for ToolChainFamily, ToolChain, Option, Dummy1, Dummy2, Dummy3, Dummy4 in RecordList:\r
                 if (ToolChainFamily, ToolChain) not in Module.BuildOptions:\r
@@ -385,15 +385,22 @@ class DscBuildData(PlatformBuildClassObject):
             self._Modules[ModuleFile] = Module\r
         return self._Modules\r
 \r
+    ## Retrieve all possible library instances used in this platform\r
     def _GetLibraryInstances(self):\r
         if self._LibraryInstances == None:\r
             self._GetLibraryClasses()\r
         return self._LibraryInstances\r
 \r
+    ## Retrieve [LibraryClasses] information\r
     def _GetLibraryClasses(self):\r
         if self._LibraryClasses == None:\r
             self._LibraryInstances = []\r
+            # \r
+            # tdict is a special dict kind of type, used for selecting correct \r
+            # library instance for given library class and module type\r
+            # \r
             LibraryClassDict = tdict(True, 3)\r
+            # track all library class names\r
             LibraryClassSet = set()\r
             RecordList = self._RawData[MODEL_EFI_LIBRARY_CLASS, self._Arch]\r
             for LibraryClass, LibraryInstance, Dummy, Arch, ModuleType, Dummy, LineNo in RecordList:\r
@@ -409,13 +416,14 @@ class DscBuildData(PlatformBuildClassObject):
             # resolve the specific library instance for each class and each module type \r
             self._LibraryClasses = tdict(True)\r
             for LibraryClass in LibraryClassSet:\r
+                # try all possible module types\r
                 for ModuleType in SUP_MODULE_LIST:\r
                     LibraryInstance = LibraryClassDict[self._Arch, ModuleType, LibraryClass]\r
                     if LibraryInstance == None:\r
                         continue\r
                     self._LibraryClasses[LibraryClass, ModuleType] = LibraryInstance\r
 \r
-            # for R8 style library instances\r
+            # for R8 style library instances, which are listed in different section\r
             RecordList = self._RawData[MODEL_EFI_LIBRARY_INSTANCE, self._Arch]\r
             for Record in RecordList:\r
                 File = NormPath(Record[0], self._Macros)\r
@@ -427,12 +435,14 @@ class DscBuildData(PlatformBuildClassObject):
                     self._LibraryInstances.append(File)\r
                 # \r
                 # we need the module name as the library class name, so we have\r
-                # to parse it here\r
+                # to parse it here. (self._Bdb[] will trigger a file parse if it\r
+                # hasn't been parsed)\r
                 # \r
                 Library = self._Bdb[File, self._Arch]\r
                 self._LibraryClasses[Library.BaseName, ':dummy:'] = Library\r
         return self._LibraryClasses\r
 \r
+    ## Retrieve all PCD settings in platform\r
     def _GetPcds(self):\r
         if self._Pcds == None:\r
             self._Pcds = {}\r
@@ -447,6 +457,7 @@ class DscBuildData(PlatformBuildClassObject):
             self._Pcds.update(self._GetDynamicVpdPcd(MODEL_PCD_DYNAMIC_EX_VPD))\r
         return self._Pcds\r
 \r
+    ## Retrieve [BuildOptions]\r
     def _GetBuildOptions(self):\r
         if self._BuildOptions == None:\r
             self._BuildOptions = {}\r
@@ -455,8 +466,18 @@ class DscBuildData(PlatformBuildClassObject):
                 self._BuildOptions[ToolChainFamily, ToolChain] = Option\r
         return self._BuildOptions\r
 \r
+    ## Retrieve non-dynamic PCD settings\r
+    #\r
+    #   @param  Type    PCD type\r
+    # \r
+    #   @retval a dict object contains settings of given PCD type\r
+    # \r
     def _GetPcd(self, Type):\r
         Pcds = {}\r
+        # \r
+        # tdict is a special dict kind of type, used for selecting correct \r
+        # PCD settings for certain ARCH\r
+        # \r
         PcdDict = tdict(True, 3)\r
         PcdSet = set()\r
         # Find out all possible PCD candidates for self._Arch\r
@@ -486,15 +507,26 @@ class DscBuildData(PlatformBuildClassObject):
                                                 )\r
         return Pcds\r
 \r
+    ## Retrieve dynamic PCD settings\r
+    #\r
+    #   @param  Type    PCD type\r
+    # \r
+    #   @retval a dict object contains settings of given PCD type\r
+    # \r
     def _GetDynamicPcd(self, Type):\r
         Pcds = {}\r
+        # \r
+        # tdict is a special dict kind of type, used for selecting correct \r
+        # PCD settings for certain ARCH and SKU\r
+        # \r
         PcdDict = tdict(True, 4)\r
         PcdSet = set()\r
+        # Find out all possible PCD candidates for self._Arch\r
         RecordList = self._RawData[Type, self._Arch]\r
         for TokenSpaceGuid, PcdCName, Setting, Arch, SkuName, Dummy3, Dummy4 in RecordList:\r
             PcdSet.add((PcdCName, TokenSpaceGuid))\r
             PcdDict[Arch, SkuName, PcdCName, TokenSpaceGuid] = Setting\r
-\r
+        # Remove redundant PCD candidates, per the ARCH and SKU\r
         for PcdCName, TokenSpaceGuid in PcdSet:\r
             ValueList = ['', '', '']\r
             Setting = PcdDict[self._Arch, self.SkuName, PcdCName, TokenSpaceGuid]\r
@@ -518,15 +550,26 @@ class DscBuildData(PlatformBuildClassObject):
                                                 )\r
         return Pcds\r
 \r
+    ## Retrieve dynamic HII PCD settings\r
+    #\r
+    #   @param  Type    PCD type\r
+    # \r
+    #   @retval a dict object contains settings of given PCD type\r
+    # \r
     def _GetDynamicHiiPcd(self, Type):\r
         Pcds = {}\r
+        # \r
+        # tdict is a special dict kind of type, used for selecting correct \r
+        # PCD settings for certain ARCH and SKU\r
+        # \r
         PcdDict = tdict(True, 4)\r
         PcdSet = set()\r
         RecordList = self._RawData[Type, self._Arch]\r
+        # Find out all possible PCD candidates for self._Arch\r
         for TokenSpaceGuid, PcdCName, Setting, Arch, SkuName, Dummy3, Dummy4 in RecordList:\r
             PcdSet.add((PcdCName, TokenSpaceGuid))\r
             PcdDict[Arch, SkuName, PcdCName, TokenSpaceGuid] = Setting\r
-\r
+        # Remove redundant PCD candidates, per the ARCH and SKU\r
         for PcdCName, TokenSpaceGuid in PcdSet:\r
             ValueList = ['', '', '', '']\r
             Setting = PcdDict[self._Arch, self.SkuName, PcdCName, TokenSpaceGuid]\r
@@ -549,15 +592,26 @@ class DscBuildData(PlatformBuildClassObject):
                                                 )\r
         return Pcds\r
 \r
+    ## Retrieve dynamic VPD PCD settings\r
+    #\r
+    #   @param  Type    PCD type\r
+    # \r
+    #   @retval a dict object contains settings of given PCD type\r
+    # \r
     def _GetDynamicVpdPcd(self, Type):\r
         Pcds = {}\r
+        # \r
+        # tdict is a special dict kind of type, used for selecting correct \r
+        # PCD settings for certain ARCH and SKU\r
+        # \r
         PcdDict = tdict(True, 4)\r
         PcdSet = set()\r
+        # Find out all possible PCD candidates for self._Arch\r
         RecordList = self._RawData[Type, self._Arch]\r
         for TokenSpaceGuid, PcdCName, Setting, Arch, SkuName, Dummy3, Dummy4 in RecordList:\r
             PcdSet.add((PcdCName, TokenSpaceGuid))\r
             PcdDict[Arch, SkuName, PcdCName, TokenSpaceGuid] = Setting\r
-\r
+        # Remove redundant PCD candidates, per the ARCH and SKU\r
         for PcdCName, TokenSpaceGuid in PcdSet:\r
             ValueList = ['', '']\r
             Setting = PcdDict[self._Arch, self.SkuName, PcdCName, TokenSpaceGuid]\r
@@ -581,6 +635,13 @@ class DscBuildData(PlatformBuildClassObject):
                                                 )\r
         return Pcds\r
 \r
+    ## Add external modules\r
+    #\r
+    #   The external modules are mostly those listed in FDF file, which don't \r
+    # need "build".\r
+    # \r
+    #   @param  FilePath    The path of module description file\r
+    # \r
     def AddModule(self, FilePath):\r
         FilePath = NormPath(FilePath)\r
         if FilePath not in self.Modules:\r
@@ -588,6 +649,15 @@ class DscBuildData(PlatformBuildClassObject):
             Module.DescFilePath = FilePath\r
             self.Modules.append(Module)\r
 \r
+    ## Add external PCDs\r
+    #\r
+    #   The external PCDs are mostly those listed in FDF file to specify address\r
+    # or offset information.\r
+    # \r
+    #   @param  Name    Name of the PCD\r
+    #   @param  Guid    Token space guid of the PCD\r
+    #   @param  Value   Value of the PCD\r
+    # \r
     def AddPcd(self, Name, Guid, Value):\r
         if (Name, Guid) not in self.Pcds:\r
             self.Pcds[Name, Guid] = PcdClassObject(\r
@@ -626,7 +696,13 @@ class DscBuildData(PlatformBuildClassObject):
     Pcds                = property(_GetPcds)\r
     BuildOptions        = property(_GetBuildOptions)\r
 \r
+## Platform build information from DSC file\r
+#\r
+#  This class is used to retrieve information stored in database and convert them\r
+# into PackageBuildClassObject form for easier use for AutoGen.\r
+#\r
 class DecBuildData(PackageBuildClassObject):\r
+    # dict used to convert PCD type in database to string used by build tool\r
     _PCD_TYPE_STRING_ = {\r
         MODEL_PCD_FIXED_AT_BUILD        :   "FixedAtBuild",\r
         MODEL_PCD_PATCHABLE_IN_MODULE   :   "PatchableInModule",\r
@@ -641,6 +717,7 @@ class DecBuildData(PackageBuildClassObject):
         MODEL_PCD_DYNAMIC_EX_VPD        :   "DynamicExVpd",\r
     }\r
 \r
+    # dict used to convert part of [Defines] to members of DecBuildData directly\r
     _PROPERTY_ = {\r
         #\r
         # Required Fields\r
@@ -651,56 +728,39 @@ class DecBuildData(PackageBuildClassObject):
     }\r
 \r
 \r
-    def __init__(self, FilePath, RawData, BuildDataBase, Arch='COMMON', Platform='COMMON', Macros={}):\r
+    ## Constructor of DecBuildData\r
+    #\r
+    #  Initialize object of DecBuildData\r
+    #\r
+    #   @param      FilePath        The path of package description file\r
+    #   @param      RawData         The raw data of DEC file\r
+    #   @param      BuildDataBase   Database used to retrieve module information\r
+    #   @param      Arch            The target architecture\r
+    #   @param      Platform        (not used for DecBuildData)\r
+    #   @param      Macros          Macros used for replacement in DSC file\r
+    #\r
+    def __init__(self, FilePath, RawData, BuildDataBase, Arch='COMMON', Platform='DUMMY', Macros={}):\r
         self.DescFilePath = FilePath\r
         self._PackageDir = os.path.dirname(FilePath)\r
         self._RawData = RawData\r
         self._Bdb = BuildDataBase\r
         self._Arch = Arch\r
-        self._Platform = Platform\r
         self._Macros = Macros\r
         self._Clear()\r
 \r
-    def __repr__(self):\r
-        S = "[Package]\n"\r
-        S += "\tNAME = %s\n" % self.PackageName\r
-        S += "\tGUID = %s\n" % self.Guid\r
-        S += "\tVER  = %s\n" % self.Version\r
-\r
-        S += '  <Protocol>\n'\r
-        for Name in self.Protocols:\r
-            S += "\t%s = %s\n" % (Name, self.Protocols[Name])\r
-\r
-        S += '  <Ppi>\n'\r
-        for Name in self.Ppis:\r
-            S += "\t%s = %s\n" % (Name, self.Ppis[Name])\r
-\r
-        S += '  <Guid>\n'\r
-        for Name in self.Guids:\r
-            S += "\t%s = %s\n" % (Name, self.Guids[Name])\r
-\r
-        S += '  <Include>\n\t'\r
-        S += "\n\t".join(self.Includes) + '\n'\r
-\r
-        S += '  <LibraryClass>\n'\r
-        for LibraryClass in self.LibraryClasses:\r
-            S += "\t%s = %s\n" % (LibraryClass, self.LibraryClasses[LibraryClass])\r
-\r
-        S += '  <PCD>\n'\r
-        for Name,Guid,Type in self.Pcds:\r
-            S += "\t%s.%s-%s\n\t\t%s\n" % (Guid, Name, Type, str(self.Pcds[Name, Guid, Type]))\r
-        return S\r
-\r
     ## XXX[key] = value\r
     def __setitem__(self, key, value):\r
         self.__dict__[self._PROPERTY_[key]] = value\r
+\r
     ## value = XXX[key]\r
     def __getitem__(self, key):\r
         return self.__dict__[self._PROPERTY_[key]]\r
+\r
     ## "in" test support\r
     def __contains__(self, key):\r
         return key in self._PROPERTY_\r
 \r
+    ## Set all internal used members of DecBuildData to None\r
     def _Clear(self):\r
         self._Header            = None\r
         self._PackageName       = None\r
@@ -713,15 +773,29 @@ class DecBuildData(PackageBuildClassObject):
         self._LibraryClasses    = None\r
         self._Pcds              = None\r
 \r
+    ## Get architecture\r
     def _GetArch(self):\r
         return self._Arch\r
 \r
+    ## Set architecture\r
+    #   \r
+    #   Changing the default ARCH to another may affect all other information\r
+    # because all information in a platform may be ARCH-related. That's\r
+    # why we need to clear all internal used members, in order to cause all \r
+    # information to be re-retrieved.\r
+    # \r
+    #   @param  Value   The value of ARCH\r
+    # \r
     def _SetArch(self, Value):\r
         if self._Arch == Value:\r
             return\r
         self._Arch = Value\r
         self._Clear()\r
 \r
+    ## Retrieve all information in [Defines] section\r
+    #\r
+    #   (Retriving all [Defines] information in one-shot is just to save time.)\r
+    # \r
     def _GetHeaderInfo(self):\r
         RecordList = self._RawData[MODEL_META_DATA_HEADER]\r
         for Record in RecordList:\r
@@ -730,6 +804,7 @@ class DecBuildData(PackageBuildClassObject):
                 self[Name] = Record[1]\r
         self._Header = 'DUMMY'\r
 \r
+    ## Retrieve package name\r
     def _GetPackageName(self):\r
         if self._PackageName == None:\r
             if self._Header == None:\r
@@ -738,6 +813,7 @@ class DecBuildData(PackageBuildClassObject):
                 EdkLogger.error("build", ATTRIBUTE_NOT_AVAILABLE, "No PACKAGE_NAME", File=self.DescFilePath)\r
         return self._PackageName\r
 \r
+    ## Retrieve file guid\r
     def _GetFileGuid(self):\r
         if self._Guid == None:\r
             if self._Header == None:\r
@@ -746,6 +822,7 @@ class DecBuildData(PackageBuildClassObject):
                 EdkLogger.error("build", ATTRIBUTE_NOT_AVAILABLE, "No PACKAGE_GUID", File=self.DescFilePath)\r
         return self._Guid\r
 \r
+    ## Retrieve package version\r
     def _GetVersion(self):\r
         if self._Version == None:\r
             if self._Header == None:\r
@@ -754,48 +831,82 @@ class DecBuildData(PackageBuildClassObject):
                 self._Version = ''\r
         return self._Version\r
 \r
+    ## Retrieve protocol definitions (name/value pairs)\r
     def _GetProtocol(self):\r
         if self._Protocols == None:\r
+            # \r
+            # tdict is a special kind of dict, used for selecting correct \r
+            # protocol defition for given ARCH\r
+            # \r
             ProtocolDict = tdict(True)\r
             NameList = []\r
+            # find out all protocol definitions for specific and 'common' arch\r
             RecordList = self._RawData[MODEL_EFI_PROTOCOL, self._Arch]\r
             for Name, Guid, Dummy, Arch, ID, LineNo in RecordList:\r
                 if Name not in NameList:\r
                     NameList.append(Name)\r
                 ProtocolDict[Arch, Name] = Guid\r
+            # use sdict to keep the order\r
             self._Protocols = sdict()\r
             for Name in NameList:\r
+                # \r
+                # limit the ARCH to self._Arch, if no self._Arch found, tdict\r
+                # will automatically turn to 'common' ARCH for trying\r
+                # \r
                 self._Protocols[Name] = ProtocolDict[self._Arch, Name]\r
         return self._Protocols\r
 \r
+    ## Retrieve PPI definitions (name/value pairs)\r
     def _GetPpi(self):\r
         if self._Ppis == None:\r
+            # \r
+            # tdict is a special kind of dict, used for selecting correct \r
+            # PPI defition for given ARCH\r
+            # \r
             PpiDict = tdict(True)\r
             NameList = []\r
+            # find out all PPI definitions for specific arch and 'common' arch\r
             RecordList = self._RawData[MODEL_EFI_PPI, self._Arch]\r
             for Name, Guid, Dummy, Arch, ID, LineNo in RecordList:\r
                 if Name not in NameList:\r
                     NameList.append(Name)\r
                 PpiDict[Arch, Name] = Guid\r
+            # use sdict to keep the order\r
             self._Ppis = sdict()\r
             for Name in NameList:\r
+                # \r
+                # limit the ARCH to self._Arch, if no self._Arch found, tdict\r
+                # will automatically turn to 'common' ARCH for trying\r
+                # \r
                 self._Ppis[Name] = PpiDict[self._Arch, Name]\r
         return self._Ppis\r
 \r
+    ## Retrieve GUID definitions (name/value pairs)\r
     def _GetGuid(self):\r
         if self._Guids == None:\r
+            # \r
+            # tdict is a special kind of dict, used for selecting correct \r
+            # GUID defition for given ARCH\r
+            # \r
             GuidDict = tdict(True)\r
             NameList = []\r
+            # find out all protocol definitions for specific and 'common' arch\r
             RecordList = self._RawData[MODEL_EFI_GUID, self._Arch]\r
             for Name, Guid, Dummy, Arch, ID, LineNo in RecordList:\r
                 if Name not in NameList:\r
                     NameList.append(Name)\r
                 GuidDict[Arch, Name] = Guid\r
+            # use sdict to keep the order\r
             self._Guids = sdict()\r
             for Name in NameList:\r
+                # \r
+                # limit the ARCH to self._Arch, if no self._Arch found, tdict\r
+                # will automatically turn to 'common' ARCH for trying\r
+                # \r
                 self._Guids[Name] = GuidDict[self._Arch, Name]\r
         return self._Guids\r
 \r
+    ## Retrieve public include paths declared in this package\r
     def _GetInclude(self):\r
         if self._Includes == None:\r
             self._Includes = []\r
@@ -803,15 +914,22 @@ class DecBuildData(PackageBuildClassObject):
             for Record in RecordList:\r
                 File = NormPath(Record[0], self._Macros)\r
                 LineNo = Record[-1]\r
+                # validate the path\r
                 if not ValidFile(File, self._PackageDir):\r
                     EdkLogger.error('build', FILE_NOT_FOUND, ExtraData=File,\r
                                     File=self.DescFilePath, Line=LineNo)\r
+                # avoid duplicate include path\r
                 if File not in self._Includes:\r
                     self._Includes.append(File)\r
         return self._Includes\r
 \r
+    ## Retrieve library class declarations (not used in build at present)\r
     def _GetLibraryClass(self):\r
         if self._LibraryClasses == None:\r
+            # \r
+            # tdict is a special kind of dict, used for selecting correct \r
+            # library class declaration for given ARCH\r
+            # \r
             LibraryClassDict = tdict(True)\r
             LibraryClassSet = set()\r
             RecordList = self._RawData[MODEL_EFI_LIBRARY_CLASS, self._Arch]\r
@@ -827,6 +945,7 @@ class DecBuildData(PackageBuildClassObject):
                 self._LibraryClasses[LibraryClass] = LibraryClassDict[self._Arch, LibraryClass]\r
         return self._LibraryClasses\r
 \r
+    ## Retrieve PCD declarations\r
     def _GetPcds(self):\r
         if self._Pcds == None:\r
             self._Pcds = {}\r
@@ -837,10 +956,17 @@ class DecBuildData(PackageBuildClassObject):
             self._Pcds.update(self._GetPcd(MODEL_PCD_DYNAMIC_EX))\r
         return self._Pcds\r
 \r
+    ## Retrieve PCD declarations for given type\r
     def _GetPcd(self, Type):\r
         Pcds = {}\r
+        # \r
+        # tdict is a special kind of dict, used for selecting correct \r
+        # PCD declaration for given ARCH\r
+        # \r
         PcdDict = tdict(True, 3)\r
+        # for summarizing PCD\r
         PcdSet = set()\r
+        # find out all PCDs of the 'type'\r
         RecordList = self._RawData[Type, self._Arch]\r
         for TokenSpaceGuid, PcdCName, Setting, Arch, Dummy1, Dummy2 in RecordList:\r
             PcdDict[Arch, PcdCName, TokenSpaceGuid] = Setting\r
@@ -848,6 +974,10 @@ class DecBuildData(PackageBuildClassObject):
 \r
         for PcdCName, TokenSpaceGuid in PcdSet:\r
             ValueList = ['', '', '']\r
+            # \r
+            # limit the ARCH to self._Arch, if no self._Arch found, tdict\r
+            # will automatically turn to 'common' ARCH and try again\r
+            # \r
             Setting = PcdDict[self._Arch, PcdCName, TokenSpaceGuid]\r
             if Setting == None:\r
                 continue\r
@@ -880,7 +1010,13 @@ class DecBuildData(PackageBuildClassObject):
     LibraryClasses  = property(_GetLibraryClass)\r
     Pcds            = property(_GetPcds)\r
 \r
+## Module build information from INF file\r
+#\r
+#  This class is used to retrieve information stored in database and convert them\r
+# into ModuleBuildClassObject form for easier use for AutoGen.\r
+#\r
 class InfBuildData(ModuleBuildClassObject):\r
+    # dict used to convert PCD type in database to string used by build tool\r
     _PCD_TYPE_STRING_ = {\r
         MODEL_PCD_FIXED_AT_BUILD        :   "FixedAtBuild",\r
         MODEL_PCD_PATCHABLE_IN_MODULE   :   "PatchableInModule",\r
@@ -895,6 +1031,7 @@ class InfBuildData(ModuleBuildClassObject):
         MODEL_PCD_DYNAMIC_EX_VPD        :   "DynamicExVpd",\r
     }\r
 \r
+    # dict used to convert part of [Defines] to members of InfBuildData directly\r
     _PROPERTY_ = {\r
         #\r
         # Required Fields\r
@@ -916,6 +1053,7 @@ class InfBuildData(ModuleBuildClassObject):
         TAB_INF_DEFINES_SHADOW                      : "_Shadow",\r
     }\r
 \r
+    # dict used to convert Component type to Module type\r
     _MODULE_TYPE_ = {\r
         "LIBRARY"               :   "BASE",\r
         "SECURITY_CORE"         :   "SEC",\r
@@ -932,8 +1070,10 @@ class InfBuildData(ModuleBuildClassObject):
         "APPLICATION"           :   "UEFI_APPLICATION",\r
         "LOGO"                  :   "BASE",\r
     }\r
-    \r
+\r
+    # regular expression for converting XXX_FLAGS in [nmake] section to new type\r
     _NMAKE_FLAG_PATTERN_ = re.compile("(?:EBC_)?([A-Z]+)_(?:STD_|PROJ_|ARCH_)?FLAGS(?:_DLL|_ASL|_EXE)?", re.UNICODE)\r
+    # dict used to convert old tool name used in [nmake] section to new ones\r
     _TOOL_CODE_ = {\r
         "C"         :   "CC",\r
         "LIB"       :   "SLINK",\r
@@ -941,6 +1081,17 @@ class InfBuildData(ModuleBuildClassObject):
     }\r
     \r
 \r
+    ## Constructor of DscBuildData\r
+    #\r
+    #  Initialize object of DscBuildData\r
+    #\r
+    #   @param      FilePath        The path of platform description file\r
+    #   @param      RawData         The raw data of DSC file\r
+    #   @param      BuildDataBase   Database used to retrieve module/package information\r
+    #   @param      Arch            The target architecture\r
+    #   @param      Platform        The name of platform employing this module\r
+    #   @param      Macros          Macros used for replacement in DSC file\r
+    #\r
     def __init__(self, FilePath, RawData, BuildDatabase, Arch='COMMON', Platform='COMMON', Macros={}):\r
         self.DescFilePath = FilePath\r
         self._ModuleDir = os.path.dirname(FilePath)\r
@@ -951,75 +1102,19 @@ class InfBuildData(ModuleBuildClassObject):
         self._Macros = Macros\r
         self._Clear()\r
 \r
-    def Print(self):\r
-        S = '[%s.%s]\n' % (self.DescFilePath, self._Arch)\r
-        S += '\tName = ' + self.BaseName + '\n'\r
-        S += '\tGuid = ' + self.Guid + '\n'\r
-        S += '\tVer  = ' + self.Version + '\n'\r
-        S += '\tInfVersion = ' + self.AutoGenVersion + '\n'\r
-        S += '\tModuleType = ' + self.ModuleType + '\n'\r
-        S += '\tComponentType = ' + self.ComponentType + '\n'\r
-        S += '\tPcdIsDriver = ' + str(self.PcdIsDriver) + '\n'\r
-        S += '\tCustomMakefile = ' + self.CustomMakefile + '\n'\r
-        S += '\tSpecification = ' + str(self.Specification) + '\n'\r
-        S += '\tShadow = ' + str(self.Shadow) + '\n'\r
-        S += '\tPcdIsDriver = ' + str(self.PcdIsDriver) + '\n'\r
-        for Lib in self.LibraryClass:\r
-            S += '\tLibraryClassDefinition = ' + str(Lib.LibraryClass) + ' SupModList = ' + str(Lib.SupModList) + '\n'\r
-        S += '\tModuleEntryPointList = ' + str(self.ModuleEntryPointList) + '\n'\r
-        S += '\tModuleUnloadImageList = ' + str(self.ModuleUnloadImageList) + '\n'\r
-        S += '\tConstructorList = ' + str(self.ConstructorList) + '\n'\r
-        S += '\tDestructorList = ' + str(self.DestructorList) + '\n'\r
-\r
-        S += '  <Binaries>\n'\r
-        for item in self.Binaries:\r
-            S += "\t" + item.BinaryFile + item.FeatureFlag + item.SupArchList + '\n'\r
-\r
-        S += '  <Sources>\n'\r
-        for item in self.Sources:\r
-            S += "\t" + item.SourceFile + '\n'\r
-\r
-        S += '  <LibraryClasses>\n'\r
-        S += '\t' + '\n\t'.join([Key for Key in self.LibraryClasses]) + '\n'\r
-\r
-        S += '  <Protocols>\n'\r
-        S += '\t' + '\n\t'.join(self.Protocols) + '\n'\r
-\r
-        S += '  <Ppis>\n'\r
-        S += '\t' + '\n\t'.join(self.Ppis) + '\n'\r
-\r
-        S += '  <Guids>\n'\r
-        S += '\t' + '\n\t'.join(self.Guids) + '\n'\r
-\r
-        S += '  <Includes>\n'\r
-        S += '\t' + '\n\t'.join(self.Includes) + '\n'\r
-\r
-        S += '  <Packages>\n'\r
-        S += '\t' + '\n\t'.join([str(P) for P in self.Packages]) + '\n'\r
-\r
-        S += '  <Pcds>\n'\r
-        for Name,Guid in self.Pcds.keys():\r
-            S += "\t%s.%s\n\t\t%s\n" % (Guid, Name, str(self.Pcds[Name,Guid]))\r
-\r
-        S += '  <BuildOptions\n'\r
-        S += '\t' + '\n\t'.join(self.BuildOptions.values()) + '\n'\r
-\r
-        S += '  <Depex>\n'\r
-        S += '\t' + str(self.Depex) + '\n'\r
-\r
-        S += '\n'\r
-        return S\r
-\r
     ## XXX[key] = value\r
     def __setitem__(self, key, value):\r
         self.__dict__[self._PROPERTY_[key]] = value\r
+\r
     ## value = XXX[key]\r
     def __getitem__(self, key):\r
         return self.__dict__[self._PROPERTY_[key]]\r
+\r
     ## "in" test support\r
     def __contains__(self, key):\r
         return key in self._PROPERTY_\r
 \r
+    ## Set all internal used members of InfBuildData to None\r
     def _Clear(self):\r
         self._Header_               = None\r
         self._AutoGenVersion        = None\r
@@ -1053,27 +1148,53 @@ class InfBuildData(ModuleBuildClassObject):
         self._BuildOptions          = None\r
         self._Depex                 = None\r
 \r
+    ## Get architecture\r
     def _GetArch(self):\r
         return self._Arch\r
 \r
+    ## Set architecture\r
+    #   \r
+    #   Changing the default ARCH to another may affect all other information\r
+    # because all information in a platform may be ARCH-related. That's\r
+    # why we need to clear all internal used members, in order to cause all \r
+    # information to be re-retrieved.\r
+    # \r
+    #   @param  Value   The value of ARCH\r
+    # \r
     def _SetArch(self, Value):\r
         if self._Arch == Value:\r
             return\r
         self._Arch = Value\r
         self._Clear()\r
 \r
+    ## Return the name of platform employing this module\r
     def _GetPlatform(self):\r
         return self._Platform\r
 \r
+    ## Change the name of platform employing this module\r
+    # \r
+    #   Changing the default name of platform to another may affect some information\r
+    # because they may be PLATFORM-related. That's why we need to clear all internal\r
+    # used members, in order to cause all information to be re-retrieved.\r
+    # \r
     def _SetPlatform(self, Value):\r
+        if self._Platform == Value:\r
+            return\r
         self._Platform = Value\r
+        self._Clear()\r
 \r
+    ## Retrieve all information in [Defines] section\r
+    #\r
+    #   (Retriving all [Defines] information in one-shot is just to save time.)\r
+    # \r
     def _GetHeaderInfo(self):\r
         RecordList = self._RawData[MODEL_META_DATA_HEADER, self._Arch, self._Platform]\r
         for Record in RecordList:\r
             Name = Record[0]\r
+            # items defined _PROPERTY_ don't need additional processing\r
             if Name in self:\r
                 self[Name] = Record[1]\r
+            # some special items in [Defines] section need special treatment\r
             elif Name == 'EFI_SPECIFICATION_VERSION':\r
                 if self._Specification == None:\r
                     self._Specification = sdict()\r
@@ -1129,7 +1250,7 @@ class InfBuildData(ModuleBuildClassObject):
                     self._CustomMakefile[TokenList[0]] = TokenList[1]\r
 \r
         # \r
-        # R8.x modules\r
+        # Retrieve information in sections specific to R8.x modules\r
         # \r
         if self._AutoGenVersion < 0x00010005:   # _AutoGenVersion may be None, which is less than anything\r
             if self._ComponentType in self._MODULE_TYPE_:\r
@@ -1171,8 +1292,10 @@ class InfBuildData(ModuleBuildClassObject):
                         else:\r
                             OptionString = self._BuildOptions[ToolChainFamily, ToolChain]\r
                             self._BuildOptions[ToolChainFamily, ToolChain] = OptionString + " " + Value\r
+        # set _Header to non-None in order to avoid database re-querying\r
         self._Header_ = 'DUMMY'\r
 \r
+    ## Retrieve file version\r
     def _GetInfVersion(self):\r
         if self._AutoGenVersion == None:\r
             if self._Header_ == None:\r
@@ -1181,6 +1304,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._AutoGenVersion = 0x00010000\r
         return self._AutoGenVersion\r
 \r
+    ## Retrieve BASE_NAME\r
     def _GetBaseName(self):\r
         if self._BaseName == None:\r
             if self._Header_ == None:\r
@@ -1189,6 +1313,7 @@ class InfBuildData(ModuleBuildClassObject):
                 EdkLogger.error('build', ATTRIBUTE_NOT_AVAILABLE, "No BASE_NAME name", File=self.DescFilePath)\r
         return self._BaseName\r
 \r
+    ## Retrieve MODULE_TYPE\r
     def _GetModuleType(self):\r
         if self._ModuleType == None:\r
             if self._Header_ == None:\r
@@ -1197,6 +1322,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._ModuleType = 'BASE'\r
         return self._ModuleType\r
 \r
+    ## Retrieve COMPONENT_TYPE\r
     def _GetComponentType(self):\r
         if self._ComponentType == None:\r
             if self._Header_ == None:\r
@@ -1205,6 +1331,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._ComponentType = ''\r
         return self._ComponentType\r
 \r
+    ## Retrieve file guid\r
     def _GetFileGuid(self):\r
         if self._Guid == None:\r
             if self._Header_ == None:\r
@@ -1213,6 +1340,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._Guid = '00000000-0000-0000-000000000000'\r
         return self._Guid\r
 \r
+    ## Retrieve module version\r
     def _GetVersion(self):\r
         if self._Version == None:\r
             if self._Header_ == None:\r
@@ -1221,6 +1349,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._Version = '0.0'\r
         return self._Version\r
 \r
+    ## Retrieve PCD_IS_DRIVER\r
     def _GetPcdIsDriver(self):\r
         if self._PcdIsDriver == None:\r
             if self._Header_ == None:\r
@@ -1229,6 +1358,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._PcdIsDriver = ''\r
         return self._PcdIsDriver\r
 \r
+    ## Retrieve SHADOW\r
     def _GetShadow(self):\r
         if self._Shadow == None:\r
             if self._Header_ == None:\r
@@ -1239,6 +1369,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._Shadow = False\r
         return self._Shadow\r
 \r
+    ## Retrieve CUSTOM_MAKEFILE\r
     def _GetMakefile(self):\r
         if self._CustomMakefile == None:\r
             if self._Header_ == None:\r
@@ -1247,6 +1378,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._CustomMakefile = {}\r
         return self._CustomMakefile\r
 \r
+    ## Retrieve EFI_SPECIFICATION_VERSION\r
     def _GetSpec(self):\r
         if self._Specification == None:\r
             if self._Header_ == None:\r
@@ -1255,6 +1387,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._Specification = {}\r
         return self._Specification\r
 \r
+    ## Retrieve LIBRARY_CLASS\r
     def _GetLibraryClass(self):\r
         if self._LibraryClass == None:\r
             if self._Header_ == None:\r
@@ -1263,6 +1396,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._LibraryClass = []\r
         return self._LibraryClass\r
 \r
+    ## Retrieve ENTRY_POINT\r
     def _GetEntryPoint(self):\r
         if self._ModuleEntryPointList == None:\r
             if self._Header_ == None:\r
@@ -1271,6 +1405,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._ModuleEntryPointList = []\r
         return self._ModuleEntryPointList\r
 \r
+    ## Retrieve UNLOAD_IMAGE\r
     def _GetUnloadImage(self):\r
         if self._ModuleUnloadImageList == None:\r
             if self._Header_ == None:\r
@@ -1279,6 +1414,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._ModuleUnloadImageList = []\r
         return self._ModuleUnloadImageList\r
 \r
+    ## Retrieve CONSTRUCTOR\r
     def _GetConstructor(self):\r
         if self._ConstructorList == None:\r
             if self._Header_ == None:\r
@@ -1287,6 +1423,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._ConstructorList = []\r
         return self._ConstructorList\r
 \r
+    ## Retrieve DESTRUCTOR\r
     def _GetDestructor(self):\r
         if self._DestructorList == None:\r
             if self._Header_ == None:\r
@@ -1295,6 +1432,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._DestructorList = []\r
         return self._DestructorList\r
                         \r
+    ## Retrieve binary files\r
     def _GetBinaryFiles(self):\r
         if self._Binaries == None:\r
             self._Binaries = []\r
@@ -1311,6 +1449,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._Binaries.append(ModuleBinaryFileClass(File, FileType, Target, FeatureFlag, self._Arch))\r
         return self._Binaries\r
 \r
+    ## Retrieve source files\r
     def _GetSourceFiles(self):\r
         if self._Sources == None:\r
             self._Sources = []\r
@@ -1328,6 +1467,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._Sources.append(ModuleSourceFileClass(File, TagName, ToolCode, ToolChainFamily, FeatureFlag))\r
         return self._Sources\r
 \r
+    ## Retrieve library classes employed by this module\r
     def _GetLibraryClassUses(self):\r
         if self._LibraryClasses == None:\r
             self._LibraryClasses = sdict()\r
@@ -1340,9 +1480,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._LibraryClasses[Lib] = Instance\r
         return self._LibraryClasses\r
 \r
-    def _SetLibraryClassUses(self, Value):\r
-        self._LibraryClasses = Value\r
-\r
+    ## Retrieve library names (for R8.x style of modules)\r
     def _GetLibraryNames(self):\r
         if self._Libraries == None:\r
             self._Libraries = []\r
@@ -1354,6 +1492,7 @@ class InfBuildData(ModuleBuildClassObject):
                     self._Libraries.append(LibraryName)\r
         return self._Libraries\r
 \r
+    ## Retrieve protocols consumed/produced by this module\r
     def _GetProtocols(self):\r
         if self._Protocols == None:\r
             self._Protocols = sdict()\r
@@ -1368,6 +1507,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._Protocols[CName] = Value\r
         return self._Protocols\r
 \r
+    ## Retrieve PPIs consumed/produced by this module\r
     def _GetPpis(self):\r
         if self._Ppis == None:\r
             self._Ppis = sdict()\r
@@ -1382,6 +1522,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._Ppis[CName] = Value\r
         return self._Ppis\r
 \r
+    ## Retrieve GUIDs consumed/produced by this module\r
     def _GetGuids(self):\r
         if self._Guids == None:\r
             self._Guids = sdict()\r
@@ -1396,6 +1537,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._Guids[CName] = Value\r
         return self._Guids\r
 \r
+    ## Retrieve include paths necessary for this module (for R8.x style of modules)\r
     def _GetIncludes(self):\r
         if self._Includes == None:\r
             self._Includes = []\r
@@ -1420,6 +1562,7 @@ class InfBuildData(ModuleBuildClassObject):
                 self._Includes.append(File)\r
         return self._Includes\r
 \r
+    ## Retrieve packages this module depends on\r
     def _GetPackages(self):\r
         if self._Packages == None:\r
             self._Packages = []\r
@@ -1430,10 +1573,12 @@ class InfBuildData(ModuleBuildClassObject):
                 if not ValidFile(File):\r
                     EdkLogger.error('build', FILE_NOT_FOUND, ExtraData=File,\r
                                     File=self.DescFilePath, Line=LineNo)\r
+                # parse this package now. we need it to get protocol/ppi/guid value\r
                 Package = self._Bdb[File, self._Arch]\r
                 self._Packages.append(Package)\r
         return self._Packages\r
 \r
+    ## Retrieve PCDs used in this module\r
     def _GetPcds(self):\r
         if self._Pcds == None:\r
             self._Pcds = {}\r
@@ -1444,6 +1589,7 @@ class InfBuildData(ModuleBuildClassObject):
             self._Pcds.update(self._GetPcd(MODEL_PCD_DYNAMIC_EX))\r
         return self._Pcds\r
 \r
+    ## Retrieve build options specific to this module\r
     def _GetBuildOptions(self):\r
         if self._BuildOptions == None:\r
             self._BuildOptions = sdict()\r
@@ -1455,10 +1601,12 @@ class InfBuildData(ModuleBuildClassObject):
                 if (ToolChainFamily, ToolChain) not in self._BuildOptions:\r
                     self._BuildOptions[ToolChainFamily, ToolChain] = Option\r
                 else:\r
+                    # concatenate the option string if they're for the same tool \r
                     OptionString = self._BuildOptions[ToolChainFamily, ToolChain]\r
                     self._BuildOptions[ToolChainFamily, ToolChain] = OptionString + " " + Option\r
         return self._BuildOptions\r
 \r
+    ## Retrieve depedency expression\r
     def _GetDepex(self):\r
         if self._Depex == None:\r
             self._Depex = []\r
@@ -1469,6 +1617,7 @@ class InfBuildData(ModuleBuildClassObject):
                     if Token in DEPEX_SUPPORTED_OPCODE or Token.endswith(".inf"):\r
                         self._Depex.append(Token)\r
                     else:\r
+                        # get the GUID value now\r
                         Value = GuidValue(Token, self.Packages)\r
                         if Value == None:\r
                             PackageList = '\t' + "\n\t".join([str(P) for P in self.Packages])\r
@@ -1477,6 +1626,7 @@ class InfBuildData(ModuleBuildClassObject):
                         self._Depex.append(Value)\r
         return self._Depex\r
 \r
+    ## Retrieve PCD for given type\r
     def _GetPcd(self, Type):\r
         Pcds = {}\r
         PcdDict = tdict(True, 4)\r
@@ -1485,6 +1635,7 @@ class InfBuildData(ModuleBuildClassObject):
         for TokenSpaceGuid, PcdCName, Setting, Arch, Platform, Dummy1, LineNo in RecordList:\r
             PcdDict[Arch, Platform, PcdCName, TokenSpaceGuid] = (Setting, LineNo)\r
             PcdSet.add((PcdCName, TokenSpaceGuid))\r
+            # get the guid value\r
             if TokenSpaceGuid not in self.Guids:\r
                 Value = GuidValue(TokenSpaceGuid, self.Packages)\r
                 if Value == None:\r
@@ -1571,7 +1722,7 @@ class InfBuildData(ModuleBuildClassObject):
 \r
     Binaries                = property(_GetBinaryFiles)\r
     Sources                 = property(_GetSourceFiles)\r
-    LibraryClasses          = property(_GetLibraryClassUses, _SetLibraryClassUses)\r
+    LibraryClasses          = property(_GetLibraryClassUses)\r
     Libraries               = property(_GetLibraryNames)\r
     Protocols               = property(_GetProtocols)\r
     Ppis                    = property(_GetPpis)\r
@@ -1585,18 +1736,16 @@ class InfBuildData(ModuleBuildClassObject):
 \r
 ## Database\r
 #\r
-# This class defined the build databse\r
-# During the phase of initialization, the database will create all tables and\r
-# insert all records of table DataModel\r
+#   This class defined the build databse for all modules, packages and platform.\r
+# It will call corresponding parser for the given file if it cannot find it in\r
+# the database.\r
 # \r
-# @param object:      Inherited from object class\r
-# @param DbPath:      A string for the path of the ECC database\r
-#\r
-# @var Conn:          Connection of the ECC database\r
-# @var Cur:           Cursor of the connection\r
-# @var TblDataModel:  Local instance for TableDataModel\r
+# @param DbPath             Path of database file\r
+# @param GlobalMacros       Global macros used for replacement during file parsing\r
+# @prarm RenewDb=False      Create new database file if it's already there\r
 #\r
 class WorkspaceDatabase(object):\r
+    # file parser\r
     _FILE_PARSER_ = {\r
         MODEL_FILE_INF  :   InfParser,\r
         MODEL_FILE_DEC  :   DecParser,\r
@@ -1605,14 +1754,20 @@ class WorkspaceDatabase(object):
         MODEL_FILE_CIF  :   None\r
     }\r
 \r
+    # file table\r
     _FILE_TABLE_ = {\r
         MODEL_FILE_INF  :   ModuleTable,\r
         MODEL_FILE_DEC  :   PackageTable,\r
         MODEL_FILE_DSC  :   PlatformTable,\r
     }\r
 \r
+    # default database file path\r
     _DB_PATH_ = "Conf/.cache/build.db"\r
 \r
+    # \r
+    # internal class used for call corresponding file parser and caching the result\r
+    # to avoid unnecessary re-parsing\r
+    # \r
     class BuildObjectFactory(object):\r
         _FILE_TYPE_ = {\r
             ".INF"  : MODEL_FILE_INF,\r
@@ -1621,7 +1776,8 @@ class WorkspaceDatabase(object):
             ".FDF"  : MODEL_FILE_FDF,\r
             ".CIF"  : MODEL_FILE_CIF,\r
         }\r
-    \r
+\r
+        # convert to xxxBuildData object\r
         _GENERATOR_ = {\r
             MODEL_FILE_INF  :   InfBuildData,\r
             MODEL_FILE_DEC  :   DecBuildData,\r
@@ -1629,8 +1785,9 @@ class WorkspaceDatabase(object):
             MODEL_FILE_FDF  :   None #FlashDefTable,\r
         }\r
 \r
-        _CACHE_ = {}    # FilePath  : <object>\r
+        _CACHE_ = {}    # (FilePath, Arch)  : <object>\r
 \r
+        # constructor\r
         def __init__(self, WorkspaceDb):\r
             self.WorkspaceDb = WorkspaceDb\r
 \r
@@ -1642,7 +1799,7 @@ class WorkspaceDatabase(object):
                 Arch = Key[1]\r
             return (FilePath, Arch) in self._CACHE_\r
 \r
-        # key = (FilePath, Arch='COMMON', Platform='COMMON')\r
+        # key = (FilePath, Arch='COMMON')\r
         def __getitem__(self, Key):\r
             FilePath = Key[0]\r
             Arch = 'COMMON'\r
@@ -1678,28 +1835,36 @@ class WorkspaceDatabase(object):
             self._CACHE_[Key] = BuildObject\r
             return BuildObject\r
 \r
+    # placeholder for file format conversion\r
     class TransformObjectFactory:\r
         def __init__(self, WorkspaceDb):\r
             self.WorkspaceDb = WorkspaceDb\r
 \r
-        # key = FilePath\r
+        # key = FilePath, Arch\r
         def __getitem__(self, Key):\r
             pass\r
 \r
+    ## Constructor of WorkspaceDatabase\r
+    # \r
+    # @param DbPath             Path of database file\r
+    # @param GlobalMacros       Global macros used for replacement during file parsing\r
+    # @prarm RenewDb=False      Create new database file if it's already there\r
+    #\r
     def __init__(self, DbPath, GlobalMacros={}, RenewDb=False):\r
         self._GlobalMacros = GlobalMacros\r
 \r
         if DbPath == None or DbPath == '':\r
             DbPath = self._DB_PATH_\r
 \r
+        # don't create necessary path for db in memory\r
         if DbPath != ':memory:':\r
             DbDir = os.path.split(DbPath)[0]\r
             if not os.path.exists(DbDir):\r
                 os.makedirs(DbDir)\r
-\r
+        # remove db file in case inconsistency between db and file in file system\r
         if RenewDb and os.path.exists(DbPath):\r
             os.remove(DbPath)\r
-\r
+        # create db with optimized parameters\r
         self.Conn = sqlite3.connect(DbPath, isolation_level='DEFERRED')\r
         self.Conn.execute("PRAGMA synchronous=OFF")\r
         self.Conn.execute("PRAGMA temp_store=MEMORY")\r
@@ -1711,18 +1876,15 @@ class WorkspaceDatabase(object):
         self.Conn.text_factory = str\r
         self.Cur = self.Conn.cursor()\r
 \r
+        # create table for internal uses\r
         self.TblDataModel = TableDataModel(self.Cur)\r
         self.TblFile = TableFile(self.Cur)\r
 \r
+        # conversion object for build or file format conversion purpose\r
         self.BuildObject = WorkspaceDatabase.BuildObjectFactory(self)\r
         self.TransformObject = WorkspaceDatabase.TransformObjectFactory(self)\r
     \r
     ## Initialize build database\r
-    #\r
-    # 1. Delete all old existing tables\r
-    # 2. Create new tables\r
-    # 3. Initialize table DataModel\r
-    #\r
     def InitDatabase(self):\r
         EdkLogger.verbose("\nInitialize build database started ...")\r
         \r
@@ -1755,56 +1917,43 @@ class WorkspaceDatabase(object):
         self.Cur.close()\r
         self.Conn.close()\r
 \r
+    ## Get unique file ID for the gvien file\r
     def GetFileId(self, FilePath):\r
         return self.TblFile.GetFileId(FilePath)\r
 \r
+    ## Get file type value for the gvien file ID\r
     def GetFileType(self, FileId):\r
         return self.TblFile.GetFileType(FileId)\r
 \r
+    ## Get time stamp stored in file table\r
     def GetTimeStamp(self, FileId):\r
         return self.TblFile.GetFileTimeStamp(FileId)\r
 \r
+    ## Update time stamp in file table\r
     def SetTimeStamp(self, FileId, TimeStamp):\r
         return self.TblFile.SetFileTimeStamp(FileId, TimeStamp)\r
 \r
+    ## Check if a table integrity flag exists or not\r
     def CheckIntegrity(self, TableName):\r
         Result = self.Cur.execute("select min(ID) from %s" % (TableName)).fetchall()\r
         if Result[0][0] != -1:\r
             return False\r
         return True\r
 \r
+    ## Compose table name for given file type and file ID\r
     def GetTableName(self, FileType, FileId):\r
         return "_%s_%s" % (FileType, FileId)\r
 \r
-    ## TRICK: \r
-    # Key = FilePath\r
-    # Value = FileType\r
-    #def __setitem__(self, FilePath, FileType):\r
-    #    FileId = self.GetFileId(FilePath)\r
-    #    if FileId != None:\r
-    #        TimeStamp = os.stat(FilePath)[8]\r
-    #        TableName = self.GetTableName(FileType, FileId)\r
-    #        if TimeStamp != self.GetTimeStamp(FileId):\r
-    #            self.SetTimeStamp(FileId, TimeStamp)\r
-    #        else:\r
-    #            if self.CheckIntegrity(TableName) == True:\r
-    #                return\r
-    #    else:\r
-    #        FileId = self.TblFile.InsertFile(FilePath, FileType)\r
-    #        TableName = self.GetTableName(FileType, FileId)\r
-    #\r
-    #    FileTable = self._FILE_TABLE_[FileType](self.Cur, TableName, FileId)\r
-    #    FileTable.Create()\r
-    #    Parser = self._FILE_PARSER_[FileType](FilePath, FileId, FileType, FileTable)\r
-    #    Parser.Start()\r
-\r
     ## Return a temp table containing all content of the given file\r
     # \r
+    #   @param  FileInfo    The tuple containing path and type of a file\r
+    # \r
     def __getitem__(self, FileInfo):\r
         FilePath, FileType = FileInfo\r
         if FileType not in self._FILE_TABLE_:\r
             return None\r
 \r
+        # flag used to indicate if it's parsed or not\r
         Parsed = False\r
         FileId = self.GetFileId(FilePath)\r
         if FileId != None:\r
@@ -1823,10 +1972,11 @@ class WorkspaceDatabase(object):
         FileTable = self._FILE_TABLE_[FileType](self.Cur, TableName, FileId)\r
         FileTable.Create(not Parsed)\r
         Parser = self._FILE_PARSER_[FileType](FilePath, FileId, FileType, FileTable)\r
+        # set the "Finished" flag in parser in order to avoid re-parsing (if parsed)\r
         Parser.Finished = Parsed\r
-\r
         return Parser\r
 \r
+    ## Summarize all packages in the database\r
     def _GetPackageList(self):\r
         PackageList = []\r
         for Module in self.ModuleList:\r
@@ -1835,6 +1985,7 @@ class WorkspaceDatabase(object):
                     PackageList.append(Package)\r
         return PackageList\r
 \r
+    ## Summarize all platforms in the database\r
     def _GetPlatformList(self):\r
         PlatformList = []\r
         for PlatformFile in self.TblFile.GetFileList(MODEL_FILE_DSC):\r
@@ -1846,6 +1997,7 @@ class WorkspaceDatabase(object):
                 PlatformList.append(Platform)\r
         return PlatformList\r
 \r
+    ## Summarize all modules in the database\r
     def _GetModuleList(self):\r
         ModuleList = []\r
         for ModuleFile in self.TblFile.GetFileList(MODEL_FILE_INF):\r
@@ -1868,3 +2020,4 @@ class WorkspaceDatabase(object):
 #\r
 if __name__ == '__main__':\r
     pass\r
+\r