public inbox for devel@edk2.groups.io
 help / color / mirror / Atom feed
* [Patch] Build spec: Add a Common PCD rules section for build report
@ 2018-06-05 12:17 Yonghong Zhu
  2018-06-07  8:12 ` Gao, Liming
  0 siblings, 1 reply; 2+ messages in thread
From: Yonghong Zhu @ 2018-06-05 12:17 UTC (permalink / raw)
  To: edk2-devel; +Cc: Liming Gao, Michael Kinney, Kevin W Shaw

1. Add a Common PCD rules section to introduce 1)the *B, *F, *P, *M's
meaning, 2) the PCD display order, 3) both display hex value and
integer for UINT* type PCD.
2. Update some items to match with code, eg: UEFI Spec Version
3. Update some typo, eg: Fv Name.

Cc: Liming Gao <liming.gao@intel.com>
Cc: Michael Kinney <michael.d.kinney@intel.com>
Cc: Kevin W Shaw <kevin.w.shaw@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Yonghong Zhu <yonghong.zhu@intel.com>
---
 .../132_sample_launch_steps_nt32_platform.md       |   4 +-
 13_build_reports/133_output.md                     |   9 +-
 13_build_reports/134_platform_summary.md           |  58 ++++++-----
 13_build_reports/135_mixed_pcd_section.md          |   8 +-
 13_build_reports/136_global_pcd_section.md         |  67 ++++++-------
 13_build_reports/137_fd_section.md                 |  18 ++--
 13_build_reports/138_module_section.md             | 107 +++++++--------------
 13_build_reports/README.md                         |   4 +-
 8 files changed, 122 insertions(+), 153 deletions(-)

diff --git a/13_build_reports/132_sample_launch_steps_nt32_platform.md b/13_build_reports/132_sample_launch_steps_nt32_platform.md
index 099dc07..7c73a5d 100644
--- a/13_build_reports/132_sample_launch_steps_nt32_platform.md
+++ b/13_build_reports/132_sample_launch_steps_nt32_platform.md
@@ -1,9 +1,9 @@
 <!--- @file
   13.2 Sample Launch Steps: NT32 platform
 
-  Copyright (c) 2008-2017, Intel Corporation. All rights reserved.<BR>
+  Copyright (c) 2008-2018, Intel Corporation. All rights reserved.<BR>
 
   Redistribution and use in source (original document form) and 'compiled'
   forms (converted to PDF, epub, HTML and other formats) with or without
   modification, are permitted provided that the following conditions are met:
 
@@ -32,11 +32,11 @@
 ## 13.2 Sample Launch Steps: NT32 platform
 
 BRG functionality is switched on by **-y** or **-Y** option from **build**
 command. The following steps output the build report for NT32 platform:
 
-1. Check out edk2 packages from https://svn.code.sf.net/p/edk2/code/trunk/edk2
+1. Check out edk2 packages from git@github.com:tianocore/edk2.git
    to `c:\Users\YourLogin\Documents\edk2` directory[^1].
 2. Run **cmd.exe**, cd to your Documents directory and enter `subst s:`.
 3. Cd to `s:\edk2`
 4. Run **edksetup.bat --nt32**
 5. Run **build.exe -a IA32 -p Nt32Pkg\Nt32Pkg.dsc -y ReportFile.txt**
diff --git a/13_build_reports/133_output.md b/13_build_reports/133_output.md
index 8c23346..230dec7 100644
--- a/13_build_reports/133_output.md
+++ b/13_build_reports/133_output.md
@@ -1,9 +1,9 @@
 <!--- @file
   13.3 Output
 
-  Copyright (c) 2008-2017, Intel Corporation. All rights reserved.<BR>
+  Copyright (c) 2008-2018, Intel Corporation. All rights reserved.<BR>
 
   Redistribution and use in source (original document form) and 'compiled'
   forms (converted to PDF, epub, HTML and other formats) with or without
   modification, are permitted provided that the following conditions are met:
 
@@ -98,13 +98,18 @@ may further consist of sections and sub-sections with the following rules:
 Platform Name:      NT32
 Platform DSC Path:  s:\edk2\Nt32Pkg\Nt32Pkg.dsc
 Architectures:      IA32
 Tool Chain:         VS2008x86
 Target:             DEBUG
+SKUID:              DEFAULT
+DefaultStore:       STANDARD
 Output Path:        s:\edk2\Build\NT32IA32
 Build Environment:  Windows-7-6.1.7601-SP1
-Build Duration:     00:01:53
+Build Duration:     00:01:29
+AutoGen Duration:   00:00:10
+Make Duration:      00:01:02
+GenFds Duration:    00:00:15
 Report Contents:    PCD, LIBRARY, BUILD_FLAGS, DEPEX, HASH, FLASH, FIXED_ADDRESS
 >==========================================================================<
 Firmware Device (FD)
 FD Name:            NT32
 Base Address:       0x0
diff --git a/13_build_reports/134_platform_summary.md b/13_build_reports/134_platform_summary.md
index 23964af..de18bec 100644
--- a/13_build_reports/134_platform_summary.md
+++ b/13_build_reports/134_platform_summary.md
@@ -32,18 +32,17 @@
 ## 13.4 Platform Summary
 
 Platform summary displays at the beginning of the output report, including the
 following items:
 
-* Platform Name : %Platform UI name: '`PLATFORM_NAME`' in DSC `[Defines]`
-  section%
-* Platform DSC Path: %Path of platform DSC file%
+* Platform Name : %`PLATFORM_NAME` in DSC `[Defines]` section%
+* Platform DSC Path : %Path of platform DSC file%
 * Architectures : %List string of all architectures used in build%
 * Tool Chain : %Tool chain string%
 * Target : %Target String%
-* SKUID: %Platform SKUID String%
-* DefaultStore: %Platform DefaultStore String%
+* SKUID : %Platform SKUID String%
+* DefaultStore : %Platform DefaultStore String%
 * Output Path : %Path to platform build directory%
 * Build Environment : %Environment string reported by Python%
 * Build Duration : %Build duration time string%
 * AutoGen Duration : %AutoGen duration time string if it exists%
 * Make Duration : %Make duration time string if it exists%
@@ -64,19 +63,40 @@ Output Path:        s:\edk2\Build\NT32IA32
 Build Environment:  Windows-7-6.1.7601-SP1
 Build Duration:     00:01:29
 AutoGen Duration:   00:00:10
 Make Duration:      00:01:02
 GenFds Duration:    00:00:15
-Report Contents:    PCD, LIBRARY, BUILD_FLAGS, DEPEX, FLASH, FIXED_ADDRESS
+Report Contents:    PCD, LIBRARY, BUILD_FLAGS, DEPEX, HASH, FLASH, FIXED_ADDRESS
 ```
 
 **********
 **Note:** Platform Summary is always present and appears at the beginning of
 report.
 **********
 
-### 13.4.1 PCDs in Conditional Directives
+### 13.4.1 Common PCD rules
+
+There have several PCD sections in the report file, following rules are apply
+to all those PCD sections.
+1. The content of PCD section in the report is grouped by token space, and the
+order of PCD is sorted by token space first, then by PcdCName.
+2. `*B` means the PCD's value was obtained from build option.
+3. `*F` means the PCD's value was obtained from the FDF file.
+4. `*P` means the PCD's value was obtained from the DSC file PCD sections.
+5. `*M` means the PCD's value was obtained from the INF file or from the DSC
+file [Components] sections <Pcd*> scope.[^2]
+6. If no `*B`, `*F`, `*P` or `*M` is shown, the PCD's value comes from DEC file.
+If the value obtained from either a build option, DSC, FDF or INF is the same as
+the value in the DEC, then `*B`, `*F`, `*P` or `*M` will not be shown in the report.
+7. If the PCD's datum type is UINT8, UINT16, UINT32 or UINT64, then in the report
+will display both hexadecimal format and integer format of PCD value.
+
+[^2] If both INF file and DSC file [Components] sections <Pcd*> scope have this PCD,
+the value would obtained from DSC file [Components] sections <Pcd*> scope base on PCD
+value precedence rule.
+
+### 13.4.2 PCDs in Conditional Directives
 
 If a PCD is used in a conditional directive statement in DSC or FDF file, this
 PCD section is generated. This is optional section.
 
 PCD values derived from expressions or other PCDs are not differentiated in the
@@ -84,17 +104,10 @@ report. Only the final value is displayed.
 
 The first line is required:
 
 `[*P|*F|*B] <PcdCName>: <PcdType> (<DatumType>) = <PcdValue>`
 
-* `*P` means the Pcd's value was obtained from the DSC file
-* `*F` means the PCD's value was obtained from the FDF file.
-* `*B` means the PCD's value set by a build option.
-* If no `*P`, `*F` or `*B` is shown, the PCD's value comes from DEC file. If the
-  value obtained from either a build option, the DSC or FDF is the same as the
-  value in the DEC, then `*B`, `*P` or `*F` will not be shown in the report.
-
 **Note: ** If the Pcd is a Structure PCD, `<DatumType>` is the Struct Name.
 
 Additional lines may be displayed showing default values when the value is not a
 default value.
 
@@ -105,19 +118,19 @@ default value.
 Conditional Directives used by the build system
 ============================================================================
 PCD statements
 >--------------------------------------------------------------------------<
 gMyTokenSpaceGuid
+*B LogEnable                   : FIXED   (UNIT32) = 0x1 (1)
+                                         DEC DEFAULT = 0x0 (0)
 *P SmmEnable                   : FEATURE (BOOLEAN) = 0x0
                                          DEC DEFAULT = 0x1
-*B LogEnable                   : FIXED   (UNIT32) = 0x1
-                                         DEC DEFAULT = 0x0
 <-------------------------------------------------------------------------->
 >==========================================================================<
 ```
 
-### 13.4.2 PCDs not used
+### 13.4.3 PCDs not used
 
 If a PCD defined in DSC or FDF file, but the PCD is not used in a conditional
 directive statement and not used by any module, the not used PCD section is
 generated. This is optional section.
 
@@ -126,17 +139,10 @@ report. Only the final value is displayed.
 
 The first line is required:
 
 `[*P|*F|*B] <PcdCName>: <PcdType> (<DatumType>) [(<SKUID>)][(<DefaultStore>)] = <PcdValue>`
 
-* `*P` means the Pcd's value was obtained from the DSC file
-* `*F` means the PCD's value was obtained from the FDF file.
-* `*B` means the PCD's value set by a build option.
-* If no `*P`, `*F` or `*B` is shown, the PCD's value comes from DEC file. If the
-  value obtained from either a build option, the DSC or FDF is the same as the
-  value in the DEC, then `*B`, `*P` or `*F` will not be shown in the report.
-
 **Note: ** If the Pcd is a Structure PCD, `<DatumType>` is the Struct Name.
 
 Additional lines may be displayed showing default values when the value is not a
 default value.
 
@@ -154,10 +160,10 @@ PCDs not used by modules or in conditional directives
 PCD statements
 >--------------------------------------------------------------------------<
 gMyTokenSpaceGuid
 *P SmmEnable                   : FEATURE (BOOLEAN) = 0x0
                                          DEC DEFAULT = 0x1
-*B UsbEnable                   : FIXED   (UNIT32) = 0x1
-                                         DEC DEFAULT = 0x0
+*B UsbEnable                   : FIXED   (UNIT32) = 0x1 (1)
+                                         DEC DEFAULT = 0x0 (0)
 <-------------------------------------------------------------------------->
 >==========================================================================<
 ```
diff --git a/13_build_reports/135_mixed_pcd_section.md b/13_build_reports/135_mixed_pcd_section.md
index b09f46c..654f157 100644
--- a/13_build_reports/135_mixed_pcd_section.md
+++ b/13_build_reports/135_mixed_pcd_section.md
@@ -1,9 +1,9 @@
 <!--- @file
   13.5 Mixed PCD Section
 
-  Copyright (c) 2008-2017, Intel Corporation. All rights reserved.<BR>
+  Copyright (c) 2008-2018, Intel Corporation. All rights reserved.<BR>
 
   Redistribution and use in source (original document form) and 'compiled'
   forms (converted to PDF, epub, HTML and other formats) with or without
   modification, are permitted provided that the following conditions are met:
 
@@ -29,17 +29,17 @@
 
 -->
 
 ## 13.5 Mixed PCD Section
 
-There is an optional sub-section that, when present, lists the PCDs in the
-platform that use multiple access methods. This sub-section is only present if
+There is an optional section that, when present, lists the PCDs in the
+platform that use multiple access methods. This section is only present if
 there are Binary modules included in the platform build and the binary module
 uses a different PCD access method than other modules in the same platform
 build.
 
-The sub-section header is:
+The section header is:
 
 ```
 >===============================================================================<
 The following PCDs use different access methods:
 =================================================================================
diff --git a/13_build_reports/136_global_pcd_section.md b/13_build_reports/136_global_pcd_section.md
index 2a5b682..64f800c 100644
--- a/13_build_reports/136_global_pcd_section.md
+++ b/13_build_reports/136_global_pcd_section.md
@@ -29,19 +29,18 @@
 
 -->
 
 ## 13.6 Global PCD Section
 
-This section contains the information for all PCDs whose values are the same
-for all modules in a platform. The content of global PCD sub-section is grouped
-by token space:
+This section contains the information for all PCDs that used for all modules in
+a platform. The content of global PCD section is grouped by token space:
 
 ```
-gEfiNt32PkgTokenSpaceGuid
+gEfiMdeModulePkgTokenSpaceGuid
 ...
 ...
-gEfiMdeModulePkgTokenSpaceGuid
+gEfiNt32PkgTokenSpaceGuid
 ...
 ...
 ...
 ```
 
@@ -54,29 +53,22 @@ Each global PCD item contains one or more lines:
 
 The first line is required:
 
 `[*P|*F|*B] <PcdCName>: <PcdType> (<DatumType>) [(<SKUID>)][(<DefaultStore>)] = <PcdValue>`
 
-* `*P` means the PCD's value was obtained from the DSC file
-* `*F` means the PCD's value was obtained from the FDF file.
-* `*B` means the PCD's value was obtained from a build option.
-* If no `*P`, `*F` or `*B` is shown, the PCD's value comes from DEC file. If the
-  value obtained from either a build option, the DSC or FDF is the same as the
-  value in the DEC, then `*B`, `*P` or `*F` will not be shown in the report.
-
 **Note: ** If the Pcd is a Structure PCD, `<DatumType>` is the Struct Name.
 
 #### Examples
 
 ```
 *P PcdWinNtFirmwareVolume               : FIXED   (VOID*) = L"..\\Fv\\Nt32.fd"
-*F PcdWinNtFlashNvStorageFtwWorkingBase : FIXED   (UINT32) = 0x0028E000
-                                                  DEC DEFAULT = 0x0
+*F PcdWinNtFlashNvStorageFtwWorkingBase : FIXED   (UINT32) = 0x0028E000 (2678784)
+                                                  DEC DEFAULT = 0x0 (0)
 
 gTokenSpaceGuid
-*B LogEnable                            : FIXED   (UNIT32) = 0x1
-                                                  DEC DEFAULT = 0x0
+*B LogEnable                            : FIXED   (UNIT32) = 0x1 (1)
+                                                  DEC DEFAULT = 0x0 (0)
 *P TestDynamic                          :  DYN    (VOID*) (DEFAULT) = L"COM1!COM2"
                                         :  DYN    (VOID*) (SKU1)    = L"COM3!COM4"
                                         :  DYN    (VOID*) (SKU2)    = L"COM5!COM6"
                                                   DEC DEFAULT = L"COM1!COM0"
 ```
@@ -90,22 +82,22 @@ gTokenSpaceGuid
 `<VariableGuid>:<VariableName>:<Offset>`
 
 #### Example
 
 ```
-*P PcdGMchDvmtTotalSize : DYN-HII (UINT8) = 0
+*P PcdGMchDvmtTotalSize : DYN-HII (UINT8) = 0x0 (0)
                           gSysConfigGuid: L"Setup": 0xAA
 ```
 
 * if `<PcdType>` is DYN-VPD
 
 `<Offset relative to VPD base address>`
 
 #### Example
 
 ```
-*F PcdVpdSample : DYN-VPD (UINT32) = 1
+*F PcdVpdSample : DYN-VPD (UINT32) = 0x1 (1)
                   0x0001FFF
 ```
 
 #### 13.6.2.2 Default (optional) line
 
@@ -120,34 +112,33 @@ It is formatted as follows:
 `DEC DEFAULT = <Value in DEC>`
 
 #### Example
 
 ```
-*P PcdWinNtFirmwareFdSize   : FIXED (UINT32) = 0x2a0000
-                              DEC DEFAULT = 0x0
+*P PcdWinNtFirmwareFdSize   : FIXED (UINT32) = 0x2a0000 (2752512)
+                              DEC DEFAULT = 0x0 (0)
 ```
 
 #### 13.6.2.3 Additional optional lines
 
 Additional lines are optional and show if the PCD's value was obtained from the
-INF file. This will be listed if the module's final PCD value is not the same
-as the first line. The value can be obtained from the INF file only if a single
-module uses the PCD.
+INF file or DSC file components module scoped PCD section. This will be listed
+if the module's final PCD value is not the same as the first line.
 
-*M means the PCD's value was obtained from the INF file.
+*M means the PCD's value was obtained from the INF file or DSC file components
+module scoped PCD section.
 
 These lines are formatted as:
 
 `*M Inf Filename = <Value>`
 
 #### Example
 
 ```
-*P PcdDebugPrintErrorLevel : PATCH (UINT32) = 0x80000042
-                                DEC DEFAULT = 0x80000000
-                                            = 0x80000000
-*M Tcp4Dxe.inf                              = 0x0
+*P PcdDebugPrintErrorLevel : PATCH (UINT32) = 0x80000042 (2147483714)
+                                DEC DEFAULT = 0x80000000 (2147483648)
+*M Tcp4Dxe.inf                              = 0x0 (0)
 ```
 
 **********
 **Note:** Global PCD section is present when **PCD** is specified in **-Y**
 option.
@@ -162,20 +153,10 @@ additional print a *B Flag.
 
 #### Example
 
 ```
 gEfiMdePkgTokenSpaceGuid
-*P TestFix                        :  FIXED   (TEST) = {
-    0xff,0x02,0x00,0x2e,0xf6,0x08,0x6f,0x19,0x5c,0x8e,0x49,0x91,0x57,0x00,0x00,0x00,
-    0x00,0x64,0x00,0x00,0x00}
-           .A             = 0x2
-           .C             = 0x0
-           .Array         = {0x2e,0xf6,0x08,0x6f,0x19,0x5c,0x8e,0x49,0x91,0x57}
-           .D             = 0x64
-                                        DEC DEFAULT = {0xFF,0xFF}
-           .A             = 0xF
-           .C             = 0xF
 *B TestDynamicExHii               : DEXHII    (TEST) (SKU1) (STANDARD) = {
     0xff,0x01,0x00,0x2e,0xf6,0x08,0x6f,0x19,0x5c,0x8e,0x49,0x91,0x57,0x00,0x00,0x00,
     0x00,0x64,0x00,0x00,0x00}
            .A             = 0x1
        *B  .C             = 0x0
@@ -189,6 +170,16 @@ gEfiMdePkgTokenSpaceGuid
            .Array         = {0x2e,0xf6,0x08,0x6f,0x20,0x5c,0x8e,0x49,0x91,0x57}
            .D             = 0x68
                                         DEC DEFAULT = {0xFF,0xFF}
            .A             = 0xF
            .C             = 0xF
+*P TestFix                        :  FIXED   (TEST) = {
+    0xff,0x02,0x00,0x2e,0xf6,0x08,0x6f,0x19,0x5c,0x8e,0x49,0x91,0x57,0x00,0x00,0x00,
+    0x00,0x64,0x00,0x00,0x00}
+           .A             = 0x2
+           .C             = 0x0
+           .Array         = {0x2e,0xf6,0x08,0x6f,0x19,0x5c,0x8e,0x49,0x91,0x57}
+           .D             = 0x64
+                                        DEC DEFAULT = {0xFF,0xFF}
+           .A             = 0xF
+           .C             = 0xF
 ```
diff --git a/13_build_reports/137_fd_section.md b/13_build_reports/137_fd_section.md
index 49c2695..43d26ec 100644
--- a/13_build_reports/137_fd_section.md
+++ b/13_build_reports/137_fd_section.md
@@ -1,9 +1,9 @@
 <!--- @file
   13.7 FD Section
 
-  Copyright (c) 2008-2017, Intel Corporation. All rights reserved.<BR>
+  Copyright (c) 2008-2018, Intel Corporation. All rights reserved.<BR>
 
   Redistribution and use in source (original document form) and 'compiled'
   forms (converted to PDF, epub, HTML and other formats) with or without
   modification, are permitted provided that the following conditions are met:
 
@@ -40,11 +40,11 @@ more than once in the output report. The section header lists the name of FD
 and its base address and size. The contents of the section consist of one or
 more FD region subsection.
 
 The line format is: "`%-20(key)s: %(value)s`" to ensure vertical alignment.
 
-* FD Name : %FD UI name: FD file base name%
+* FD Name : %FD file base name%
 * Base Address: %Base address for the FD image%
 * Size : %Size of the FD image%
 
 #### Example
 
@@ -61,19 +61,19 @@ Size:             0x2a0000(2688KB)
 
 ### 13.7.2 FD Region Sub-section
 
 This sub-section contains FD region information of platform flash device. If
 the region is a firmware volume, it lists the set of modules and its space
-information; otherwise, it only lists its region name, base address and size in
+information; otherwise, it only lists its region type, base address and size in
 its sub-section header.
 
 The line format is: "`%-20(key)s: %(values)s`" to ensure vertical alignment.
 
-* Region Type : %The type of the FD region (FV, Data, File or None)%
-* Base Address: %Base address for the FD region%
+* Type : %The type of the FD region (FV, DATA, FILE or None)%
+* Base Address : %Base address for the FD region%
 * Size : %Size of the FD region%
-* FV Name*: %FV name and occupation percentage%
+* Fv Name*: %FV name and occupation percentage%
 * Occupied Size*: %The occupied size of the FV%
 * Free Size*: %The free size of the FV%
 
 The contents of FD region sub-section contain the list:
 
@@ -87,11 +87,11 @@ The items marked with \* are only available when the region type is FV.
 >--------------------------------------------------------------------------<
 FD Region
 Type:             FV
 Base Address:     0x0
 Size:             0x280000 (2560K)
-FV Name:          FvRecovery (65.9% Full)
+Fv Name:          FvRecovery (65.9% Full)
 Occupied Size:    0x1A6028 (1688K)
 Free Size:        0xD9FD8 (872K)
 Offset     Module
 ----------------------------------------------------------------------------
 0x00000078 PEI Apriori
@@ -125,12 +125,12 @@ Size:             0x2000 (8K)
 ### 13.7.3 VPD PCD Sub-section
 
 This section lists, in Offset order, every VPD PCD specified in the DSC file.
 The line format for this section is PcdName SkuId Offset PcdSize PcdValue.
 
-* Base Address:%Base address from the start of the FD file%
-* Size :%Size of the FD region%
+* Base Address : %Base address from the start of the FD file%
+* Size : %Size of the FD VPD region%
 
 For each PCD in this region:
 
 * PcdName : PcdTokenSpaceGuidCname.PcdCname
 * SkuId : The string name of the SkuId for this build (or DEFAULT if no SkuId
diff --git a/13_build_reports/138_module_section.md b/13_build_reports/138_module_section.md
index 88e9ac2..52288d7 100644
--- a/13_build_reports/138_module_section.md
+++ b/13_build_reports/138_module_section.md
@@ -36,38 +36,33 @@ Module section lists all modules involved in the platform build. If the
 are sorted according to their PEI or DXE dispatch order; otherwise the module
 sections are listed according to their DSC position.
 
 ### 13.8.1 Module Section Summary
 
-This sub-section lists the module basic information: Module name: INF file,
-file GUID, module size, module build time stamp and driver type.
-
-* `Module Name` : %Module UI name: '`BASE_NAME`' in INF `[Defines]` section%
-* Module INF Path: %Path of Module INF file%
-* File GUID: %Module GUID: '`FILE_GUID`' in INF `[Defines]` section%
-* Size: %Module EFI image size%
-* Build time stamp: %The time stamp in module PE32 image% (If the time stamp is
-  cleared to be zero, the build time stamp is 1970-01-01 00:00:00 UTC time.)
-* Module Build Time: %The time string for this module's build%
-* Driver Type: %The driver's file type code[^2] and name in firmware volume%
+This sub-section lists the module basic information: Module name, INF file
+path, File GUID, Size, hash value, module build time stamp, module build time
+and driver type.
+
+* Module Name : %`BASE_NAME` in INF `[Defines]` section%
+* Module INF Path : %Path of Module INF file%
+* File GUID : %`FILE_GUID` in INF `[Defines]` section%
+* Size : %Module EFI image size%
+* SHA1 HASH : %SHA1 hash value and efi file name with \* character%
+* Build Time Stamp : %The time stamp in module PE32 image% (If the time stamp is
+  cleared to be zero, the build time stamp is 1970-01-01 08:00:00 UTC time.)
+* Module Build Time : %The time string for this module's build%
+* Driver Type : %The driver's file type code[^3] and name in firmware volume%
 
 The following entries are options:
 
-* If using defaults or the `HASH` flag is specified:
-  - SHA1 HASH: %SHA1 HASH% and *%Module .efi file name%
-* UEFI Specification Version: %The UEFI specification
-  version:'`UEFI_SPECIFICATION_VERSION`' in INF `[Defines]` section%
-* PI Specification Version: %The PI specification
-  version:'`PI_SPECIFICATION_VERSION`' in the INF `[Defines]` section%
-* `PCI Device ID`: %The PCI device ID for the device: '`PCI_DEVICE_ID`' in INF
-  `[Defines]` section%
-* `PCI Vendor ID`: %The PCI vendor ID for the device: '`PCI_VENDOR_ID`' in INF
-  `[Defines]` section%
-* `PCI Class Code`: %The PCI class code for the device: '`PCI_CLASS_CODE`' in
-  INF `[Defines]` section%
-
-[^2] The hex value in this field is the Firmware File Type value defined in
+* UEFI Spec Version : %`UEFI_SPECIFICATION_VERSION` in INF `[Defines]` section%
+* PI Spec Version : %`PI_SPECIFICATION_VERSION` in INF `[Defines]` section%
+* PCI Device ID : %`PCI_DEVICE_ID` in INF `[Defines]` section%
+* PCI Vendor ID : %`PCI_VENDOR_ID` in INF `[Defines]` section%
+* PCI Class Code : %`PCI_CLASS_CODE` in INF `[Defines]` section%
+
+[^3] The hex value in this field is the Firmware File Type value defined in
 Volume 3 of the PI Specification (Table 3 Defined File Types).
 
 
 #### Example1:
 
@@ -77,11 +72,11 @@ Module Summary
 Module Name:        SmbiosDxe
 Module INF Path:    MdeModule\Universal\SmbiosDxe\SmbiosDxe.inf
 File GUID:          F9D88642-0737-49BC-81B5-6889CD57D9EA
 Size:               0x7000 (28.00K)
 SHA1 HASH:          d94c3f180f25d6b562f477bc4a16b286cb66a8b6 *SmbiosDxe.efi
-Build Time Stamp:   1969-12-31 16:00:00
+Build Time Stamp:   1970-01-01 08:00:00
 Module Build Time:  1060ms
 Driver Type:        0x7 (DRIVER)
 ============================================================================
 ... (Module Section Details for SmbiosDxe)
 <==========================================================================>
@@ -95,11 +90,11 @@ Module Summary
 Module Name:        EbcDxe
 Module INF Path:    MdeModule\Universal\EbcDxe\EbcDxe.inf
 File GUID:          13AC6DD0-73D0-11D4-B06B-00AA00BD6DE7
 Size:               0x9000 (36.00K)
 SHA1 HASH:          ff4c019345614afe5c88e7fc37219c30a07f4af4 *EbcDxe.efi
-Time Stamp:         1969-12-31 16:00:00
+Time Stamp:         1970-01-01 08:00:00
 Module Build Time:  1731ms
 Driver Type:        0x7 (DRIVER)
 ============================================================================
 ... (Module Section Details for EbcDxe)
 
@@ -128,12 +123,11 @@ instance's INF path.
 An example of the module's library instance section is shown below.
 
 Following the subsection header, for each library instance that was linked, the
 format is:
 
-1. The first line is the INF file name; this is the fully qualified path and
-   file name of the library instance
+1. The first line is the INF file path of the library instance
 
 2. {ClassName} - the name of the library class that the above INF file provides
 
    * If constructors are provided, for each constructor, the following content
      is inserted in the curly braces after the ClassName:
@@ -150,11 +144,11 @@ format is:
    * Display the build time.
      ```
      Time = TimeString
      ```
 
-#### Example1:
+#### Example:
 
 ```c
 >--------------------------------------------------------------------------<
 Library
 ---------------------------------------------------------------------------
@@ -193,31 +187,10 @@ s:\edk2\MdePkg\Library\UefiDriverEntryPoint\UefiDriverEntryPoint.inf
 s:\edk2\MdePkg\Library\UefiRuntimeLib\UefiRuntimeLib.inf
 {UefiRuntimeLib: C = UefiRuntimeLibConstructor D = UefiRuntimeLibDestructor Time = 265ms}
 <-------------------------------------------------------------------------->
 ```
 
-#### Example2:
-
-```
->--------------------------------------------------------------------------<
-Library
----------------------------------------------------------------------------
-s:\edk2\R8MyPlatformPkg\Guid\GuidLib.inf
-s:\edk2\EdkCompatibilityPkg\Foundation\Guid\EdkGuidLib.inf
-s:\edk2\EdkCompatibilityPkg\Foundation\Protocol\EdkProtocolLib.inf
-s:\edk2\EdkCompatibilityPkg\Foundation\Library\RuntimeDxe\EfiRuntimeLib\EfiRuntimeLib.inf
-s:\edk2\EdkCompatibilityPkg\Foundation\Core\Dxe\ArchProtocol\ArchProtocolLib.inf
-s:\edk2\EdkCompatibilityPkg\Foundation\Library\CompilerStub\CompilerStubLib.inf
-s:\edk2\EdkCompatibilityPkg\Foundation\Guid\EdkGuidLib.inf
-s:\edk2\EdkCompatibilityPkg\Foundation\Framework\Protocol\EdkFrameworkProtocolLib.inf
-s:\edk2\EdkCompatibilityPkg\Foundation\Efi\Guid\EfiGuidLib.inf
-s:\edk2\EdkCompatibilityPkg\Foundation\Efi\Protocol\EfiProtocolLib.inf
-s:\edk2\EdkCompatibilityPkg\Foundation\Library\EfiCommonLib\EfiCommonLib.inf
-s:\edk2\EdkCompatibilityPkg\Foundation\Framework\Guid\EdkFrameworkGuidLib.inf
-<-------------------------------------------------------------------------->
-```
-
 **********
 **Note:** This sub-section is present when **LIBRARY** is specified in **-Y**
 option.
 **********
 
@@ -226,34 +199,28 @@ option.
 This sub-section (following the Module Summary information) holds the
 information for all PCDs used in this module. The content of module PCD
 sub-section is divided by token space such as:
 
 ```
-gEfiNt32PkgTokenSpaceGuid
+gEfiMdeModulePkgTokenSpaceGuid
 ...
 ...
-gEfiMdeModulePkgTokenSpaceGuid
+gEfiNt32PkgTokenSpaceGuid
 ...
 ...
 ...
 ```
 
-Each PCD may contain up to four lines:
+Each PCD may contain up to following lines:
 
 1. The first line is a mandatory line with the following format:
-   `[*P|*F|*B|*M] <PcdCName>: <PcdType> (<DatumType>) [(<SKUID>)][(<DefaultStore>)] = <PcdValue>`
+
+   `[*B|*F|*P|*M] <PcdCName> : <PcdType> (<DatumType>) [(<SKUID>)][(<DefaultStore>)] = <PcdValue>`
 
    **Note: ** If the Pcd is a Structure PCD, `<DatumType>` is the Struct Name.
 
-   - \*P means the Pcd's value is the platform default (listed in DSC PCD common
-     section or inherited from Module INF file).
-   - \*M means the PCD's value in module INF was obtained from the `[Components]`
-     section of the DSC file.
-   - \*F means the PCD's value is override in FDF file.
-   - \*B means the PCD's value is override in build option.
-   - If no \*P or \*F or \*B or \*M, mean the PCD's value comes from DEC file.
-   - For example:
+   For example:
      ```
      *P PcdWinNtFirmwareVolume : FIXED (VOID*) = L"..\\Fv\\Nt32.fd"
      ```
 
 2. The second line is the optional line
@@ -261,20 +228,20 @@ Each PCD may contain up to four lines:
      ```
      <VariableGuid>:<VariableName>:<Offset>
      ```
      For example:
      ```
-     *P PcdGMchDvmtTotalSize : DYN-HII (UINT8) = 0
+     *P PcdGMchDvmtTotalSize : DYN-HII (UINT8) = 0x0 (0)
                                gSysConfigGuid: L"Setup": 0xAA
      ```
    - if `<PcdType>` is DYN-VPD
      ```
      <Offset relative to VPD base address>
      ```
      For example:
      ```
-     *F PcdVpdSample : DYN-VPD (UINT32) = 1
+     *F PcdVpdSample : DYN-VPD (UINT32) = 0x1 (1)
                        0x0001FFF
      ```
 
 3. The third and fourth lines are both option if the module's final
    `<PcdValue>` is not equal to the PCD value in the PCD common section in the
@@ -283,16 +250,16 @@ Each PCD may contain up to four lines:
    DSC DEFAULT = <Value in PCD Common Section in DSC>
    DEC DEFAULT = <Value in DEC>
    ```
    For example:
    ```
-   *P PcdPlatformBootTimeOut : DYNHII (UINT16) = 10
+   *M PcdDebugPrintErrorLevel : FIXED   (UINT32) = 0x80000042 (2147483714)
+                                DSC DEFAULT = 0x80000040 (2147483712)
+                                DEC DEFAULT = 0x80000000 (2147483648)
+   *P PcdPlatformBootTimeOut : DYNHII (UINT16) = 0xA (10)
                      gEfiGlobalVariableGuid: L"Timeout": 0x0
-                                                   DEC DEFAULT = 0xffff
-   *M PcdDebugPrintErrorLevel : FIXED   (UINT32) = 0x80000042
-                                DSC DEFAULT = 0x80000040
-                                DEC DEFAULT = 0x80000000
+                                DEC DEFAULT = 0xffff (65535)
    ```
 
 4. Additional lines may exist if the PCD is Structure PCD. Every field value
 that user specified in DSC/DEC file and build command will print out. The field
 value is from DSC/DEC file or build command, not from the final structure byte
diff --git a/13_build_reports/README.md b/13_build_reports/README.md
index 9050690..b774d68 100644
--- a/13_build_reports/README.md
+++ b/13_build_reports/README.md
@@ -1,9 +1,9 @@
 <!--- @file
   13 Build Reports
 
-  Copyright (c) 2008-2017, Intel Corporation. All rights reserved.<BR>
+  Copyright (c) 2008-2018, Intel Corporation. All rights reserved.<BR>
 
   Redistribution and use in source (original document form) and 'compiled'
   forms (converted to PDF, epub, HTML and other formats) with or without
   modification, are permitted provided that the following conditions are met:
 
@@ -34,11 +34,11 @@
 This section introduces the build report generation tool functionality and its
 output report format. It describes the external behaviors of the tool, i.e. the
 accepted command line options and the detailed output report format.
 
 Unless the quiet or silent options are given to the build command, the build
-system automatically reports the following:
+system automatically reports the following in build log file:
 
 * Each region, offset and size defined in the FD.
 * The location of the GUID cross reference file.
 * The size of the data in each FV region.
 * The date and time the build completed.
-- 
2.6.1.windows.1



^ permalink raw reply related	[flat|nested] 2+ messages in thread

* Re: [Patch] Build spec: Add a Common PCD rules section for build report
  2018-06-05 12:17 [Patch] Build spec: Add a Common PCD rules section for build report Yonghong Zhu
@ 2018-06-07  8:12 ` Gao, Liming
  0 siblings, 0 replies; 2+ messages in thread
From: Gao, Liming @ 2018-06-07  8:12 UTC (permalink / raw)
  To: Zhu, Yonghong, edk2-devel@lists.01.org; +Cc: Kinney, Michael D, Shaw, Kevin W

Reviewed-by: Liming Gao <liming.gao@intel.com>

>-----Original Message-----
>From: Zhu, Yonghong
>Sent: Tuesday, June 05, 2018 8:18 PM
>To: edk2-devel@lists.01.org
>Cc: Gao, Liming <liming.gao@intel.com>; Kinney, Michael D
><michael.d.kinney@intel.com>; Shaw, Kevin W <kevin.w.shaw@intel.com>
>Subject: [Patch] Build spec: Add a Common PCD rules section for build report
>
>1. Add a Common PCD rules section to introduce 1)the *B, *F, *P, *M's
>meaning, 2) the PCD display order, 3) both display hex value and
>integer for UINT* type PCD.
>2. Update some items to match with code, eg: UEFI Spec Version
>3. Update some typo, eg: Fv Name.
>
>Cc: Liming Gao <liming.gao@intel.com>
>Cc: Michael Kinney <michael.d.kinney@intel.com>
>Cc: Kevin W Shaw <kevin.w.shaw@intel.com>
>Contributed-under: TianoCore Contribution Agreement 1.1
>Signed-off-by: Yonghong Zhu <yonghong.zhu@intel.com>
>---
> .../132_sample_launch_steps_nt32_platform.md       |   4 +-
> 13_build_reports/133_output.md                     |   9 +-
> 13_build_reports/134_platform_summary.md           |  58 ++++++-----
> 13_build_reports/135_mixed_pcd_section.md          |   8 +-
> 13_build_reports/136_global_pcd_section.md         |  67 ++++++-------
> 13_build_reports/137_fd_section.md                 |  18 ++--
> 13_build_reports/138_module_section.md             | 107 +++++++--------------
> 13_build_reports/README.md                         |   4 +-
> 8 files changed, 122 insertions(+), 153 deletions(-)
>
>diff --git a/13_build_reports/132_sample_launch_steps_nt32_platform.md
>b/13_build_reports/132_sample_launch_steps_nt32_platform.md
>index 099dc07..7c73a5d 100644
>--- a/13_build_reports/132_sample_launch_steps_nt32_platform.md
>+++ b/13_build_reports/132_sample_launch_steps_nt32_platform.md
>@@ -1,9 +1,9 @@
> <!--- @file
>   13.2 Sample Launch Steps: NT32 platform
>
>-  Copyright (c) 2008-2017, Intel Corporation. All rights reserved.<BR>
>+  Copyright (c) 2008-2018, Intel Corporation. All rights reserved.<BR>
>
>   Redistribution and use in source (original document form) and 'compiled'
>   forms (converted to PDF, epub, HTML and other formats) with or without
>   modification, are permitted provided that the following conditions are met:
>
>@@ -32,11 +32,11 @@
> ## 13.2 Sample Launch Steps: NT32 platform
>
> BRG functionality is switched on by **-y** or **-Y** option from **build**
> command. The following steps output the build report for NT32 platform:
>
>-1. Check out edk2 packages from
>https://svn.code.sf.net/p/edk2/code/trunk/edk2
>+1. Check out edk2 packages from git@github.com:tianocore/edk2.git
>    to `c:\Users\YourLogin\Documents\edk2` directory[^1].
> 2. Run **cmd.exe**, cd to your Documents directory and enter `subst s:`.
> 3. Cd to `s:\edk2`
> 4. Run **edksetup.bat --nt32**
> 5. Run **build.exe -a IA32 -p Nt32Pkg\Nt32Pkg.dsc -y ReportFile.txt**
>diff --git a/13_build_reports/133_output.md
>b/13_build_reports/133_output.md
>index 8c23346..230dec7 100644
>--- a/13_build_reports/133_output.md
>+++ b/13_build_reports/133_output.md
>@@ -1,9 +1,9 @@
> <!--- @file
>   13.3 Output
>
>-  Copyright (c) 2008-2017, Intel Corporation. All rights reserved.<BR>
>+  Copyright (c) 2008-2018, Intel Corporation. All rights reserved.<BR>
>
>   Redistribution and use in source (original document form) and 'compiled'
>   forms (converted to PDF, epub, HTML and other formats) with or without
>   modification, are permitted provided that the following conditions are met:
>
>@@ -98,13 +98,18 @@ may further consist of sections and sub-sections with
>the following rules:
> Platform Name:      NT32
> Platform DSC Path:  s:\edk2\Nt32Pkg\Nt32Pkg.dsc
> Architectures:      IA32
> Tool Chain:         VS2008x86
> Target:             DEBUG
>+SKUID:              DEFAULT
>+DefaultStore:       STANDARD
> Output Path:        s:\edk2\Build\NT32IA32
> Build Environment:  Windows-7-6.1.7601-SP1
>-Build Duration:     00:01:53
>+Build Duration:     00:01:29
>+AutoGen Duration:   00:00:10
>+Make Duration:      00:01:02
>+GenFds Duration:    00:00:15
> Report Contents:    PCD, LIBRARY, BUILD_FLAGS, DEPEX, HASH, FLASH,
>FIXED_ADDRESS
> >==========================================================
>================<
> Firmware Device (FD)
> FD Name:            NT32
> Base Address:       0x0
>diff --git a/13_build_reports/134_platform_summary.md
>b/13_build_reports/134_platform_summary.md
>index 23964af..de18bec 100644
>--- a/13_build_reports/134_platform_summary.md
>+++ b/13_build_reports/134_platform_summary.md
>@@ -32,18 +32,17 @@
> ## 13.4 Platform Summary
>
> Platform summary displays at the beginning of the output report, including
>the
> following items:
>
>-* Platform Name : %Platform UI name: '`PLATFORM_NAME`' in DSC
>`[Defines]`
>-  section%
>-* Platform DSC Path: %Path of platform DSC file%
>+* Platform Name : %`PLATFORM_NAME` in DSC `[Defines]` section%
>+* Platform DSC Path : %Path of platform DSC file%
> * Architectures : %List string of all architectures used in build%
> * Tool Chain : %Tool chain string%
> * Target : %Target String%
>-* SKUID: %Platform SKUID String%
>-* DefaultStore: %Platform DefaultStore String%
>+* SKUID : %Platform SKUID String%
>+* DefaultStore : %Platform DefaultStore String%
> * Output Path : %Path to platform build directory%
> * Build Environment : %Environment string reported by Python%
> * Build Duration : %Build duration time string%
> * AutoGen Duration : %AutoGen duration time string if it exists%
> * Make Duration : %Make duration time string if it exists%
>@@ -64,19 +63,40 @@ Output Path:        s:\edk2\Build\NT32IA32
> Build Environment:  Windows-7-6.1.7601-SP1
> Build Duration:     00:01:29
> AutoGen Duration:   00:00:10
> Make Duration:      00:01:02
> GenFds Duration:    00:00:15
>-Report Contents:    PCD, LIBRARY, BUILD_FLAGS, DEPEX, FLASH,
>FIXED_ADDRESS
>+Report Contents:    PCD, LIBRARY, BUILD_FLAGS, DEPEX, HASH, FLASH,
>FIXED_ADDRESS
> ```
>
> **********
> **Note:** Platform Summary is always present and appears at the beginning
>of
> report.
> **********
>
>-### 13.4.1 PCDs in Conditional Directives
>+### 13.4.1 Common PCD rules
>+
>+There have several PCD sections in the report file, following rules are apply
>+to all those PCD sections.
>+1. The content of PCD section in the report is grouped by token space, and
>the
>+order of PCD is sorted by token space first, then by PcdCName.
>+2. `*B` means the PCD's value was obtained from build option.
>+3. `*F` means the PCD's value was obtained from the FDF file.
>+4. `*P` means the PCD's value was obtained from the DSC file PCD sections.
>+5. `*M` means the PCD's value was obtained from the INF file or from the
>DSC
>+file [Components] sections <Pcd*> scope.[^2]
>+6. If no `*B`, `*F`, `*P` or `*M` is shown, the PCD's value comes from DEC file.
>+If the value obtained from either a build option, DSC, FDF or INF is the same
>as
>+the value in the DEC, then `*B`, `*F`, `*P` or `*M` will not be shown in the
>report.
>+7. If the PCD's datum type is UINT8, UINT16, UINT32 or UINT64, then in the
>report
>+will display both hexadecimal format and integer format of PCD value.
>+
>+[^2] If both INF file and DSC file [Components] sections <Pcd*> scope have
>this PCD,
>+the value would obtained from DSC file [Components] sections <Pcd*>
>scope base on PCD
>+value precedence rule.
>+
>+### 13.4.2 PCDs in Conditional Directives
>
> If a PCD is used in a conditional directive statement in DSC or FDF file, this
> PCD section is generated. This is optional section.
>
> PCD values derived from expressions or other PCDs are not differentiated in
>the
>@@ -84,17 +104,10 @@ report. Only the final value is displayed.
>
> The first line is required:
>
> `[*P|*F|*B] <PcdCName>: <PcdType> (<DatumType>) = <PcdValue>`
>
>-* `*P` means the Pcd's value was obtained from the DSC file
>-* `*F` means the PCD's value was obtained from the FDF file.
>-* `*B` means the PCD's value set by a build option.
>-* If no `*P`, `*F` or `*B` is shown, the PCD's value comes from DEC file. If the
>-  value obtained from either a build option, the DSC or FDF is the same as the
>-  value in the DEC, then `*B`, `*P` or `*F` will not be shown in the report.
>-
> **Note: ** If the Pcd is a Structure PCD, `<DatumType>` is the Struct Name.
>
> Additional lines may be displayed showing default values when the value is
>not a
> default value.
>
>@@ -105,19 +118,19 @@ default value.
> Conditional Directives used by the build system
>
>===========================================================
>=================
> PCD statements
> >--------------------------------------------------------------------------<
> gMyTokenSpaceGuid
>+*B LogEnable                   : FIXED   (UNIT32) = 0x1 (1)
>+                                         DEC DEFAULT = 0x0 (0)
> *P SmmEnable                   : FEATURE (BOOLEAN) = 0x0
>                                          DEC DEFAULT = 0x1
>-*B LogEnable                   : FIXED   (UNIT32) = 0x1
>-                                         DEC DEFAULT = 0x0
> <-------------------------------------------------------------------------->
> >==========================================================
>================<
> ```
>
>-### 13.4.2 PCDs not used
>+### 13.4.3 PCDs not used
>
> If a PCD defined in DSC or FDF file, but the PCD is not used in a conditional
> directive statement and not used by any module, the not used PCD section is
> generated. This is optional section.
>
>@@ -126,17 +139,10 @@ report. Only the final value is displayed.
>
> The first line is required:
>
> `[*P|*F|*B] <PcdCName>: <PcdType> (<DatumType>)
>[(<SKUID>)][(<DefaultStore>)] = <PcdValue>`
>
>-* `*P` means the Pcd's value was obtained from the DSC file
>-* `*F` means the PCD's value was obtained from the FDF file.
>-* `*B` means the PCD's value set by a build option.
>-* If no `*P`, `*F` or `*B` is shown, the PCD's value comes from DEC file. If the
>-  value obtained from either a build option, the DSC or FDF is the same as the
>-  value in the DEC, then `*B`, `*P` or `*F` will not be shown in the report.
>-
> **Note: ** If the Pcd is a Structure PCD, `<DatumType>` is the Struct Name.
>
> Additional lines may be displayed showing default values when the value is
>not a
> default value.
>
>@@ -154,10 +160,10 @@ PCDs not used by modules or in conditional
>directives
> PCD statements
> >--------------------------------------------------------------------------<
> gMyTokenSpaceGuid
> *P SmmEnable                   : FEATURE (BOOLEAN) = 0x0
>                                          DEC DEFAULT = 0x1
>-*B UsbEnable                   : FIXED   (UNIT32) = 0x1
>-                                         DEC DEFAULT = 0x0
>+*B UsbEnable                   : FIXED   (UNIT32) = 0x1 (1)
>+                                         DEC DEFAULT = 0x0 (0)
> <-------------------------------------------------------------------------->
> >==========================================================
>================<
> ```
>diff --git a/13_build_reports/135_mixed_pcd_section.md
>b/13_build_reports/135_mixed_pcd_section.md
>index b09f46c..654f157 100644
>--- a/13_build_reports/135_mixed_pcd_section.md
>+++ b/13_build_reports/135_mixed_pcd_section.md
>@@ -1,9 +1,9 @@
> <!--- @file
>   13.5 Mixed PCD Section
>
>-  Copyright (c) 2008-2017, Intel Corporation. All rights reserved.<BR>
>+  Copyright (c) 2008-2018, Intel Corporation. All rights reserved.<BR>
>
>   Redistribution and use in source (original document form) and 'compiled'
>   forms (converted to PDF, epub, HTML and other formats) with or without
>   modification, are permitted provided that the following conditions are met:
>
>@@ -29,17 +29,17 @@
>
> -->
>
> ## 13.5 Mixed PCD Section
>
>-There is an optional sub-section that, when present, lists the PCDs in the
>-platform that use multiple access methods. This sub-section is only present if
>+There is an optional section that, when present, lists the PCDs in the
>+platform that use multiple access methods. This section is only present if
> there are Binary modules included in the platform build and the binary
>module
> uses a different PCD access method than other modules in the same platform
> build.
>
>-The sub-section header is:
>+The section header is:
>
> ```
> >==========================================================
>=====================<
> The following PCDs use different access methods:
>
>===========================================================
>======================
>diff --git a/13_build_reports/136_global_pcd_section.md
>b/13_build_reports/136_global_pcd_section.md
>index 2a5b682..64f800c 100644
>--- a/13_build_reports/136_global_pcd_section.md
>+++ b/13_build_reports/136_global_pcd_section.md
>@@ -29,19 +29,18 @@
>
> -->
>
> ## 13.6 Global PCD Section
>
>-This section contains the information for all PCDs whose values are the same
>-for all modules in a platform. The content of global PCD sub-section is
>grouped
>-by token space:
>+This section contains the information for all PCDs that used for all modules in
>+a platform. The content of global PCD section is grouped by token space:
>
> ```
>-gEfiNt32PkgTokenSpaceGuid
>+gEfiMdeModulePkgTokenSpaceGuid
> ...
> ...
>-gEfiMdeModulePkgTokenSpaceGuid
>+gEfiNt32PkgTokenSpaceGuid
> ...
> ...
> ...
> ```
>
>@@ -54,29 +53,22 @@ Each global PCD item contains one or more lines:
>
> The first line is required:
>
> `[*P|*F|*B] <PcdCName>: <PcdType> (<DatumType>)
>[(<SKUID>)][(<DefaultStore>)] = <PcdValue>`
>
>-* `*P` means the PCD's value was obtained from the DSC file
>-* `*F` means the PCD's value was obtained from the FDF file.
>-* `*B` means the PCD's value was obtained from a build option.
>-* If no `*P`, `*F` or `*B` is shown, the PCD's value comes from DEC file. If the
>-  value obtained from either a build option, the DSC or FDF is the same as the
>-  value in the DEC, then `*B`, `*P` or `*F` will not be shown in the report.
>-
> **Note: ** If the Pcd is a Structure PCD, `<DatumType>` is the Struct Name.
>
> #### Examples
>
> ```
> *P PcdWinNtFirmwareVolume               : FIXED   (VOID*) = L"..\\Fv\\Nt32.fd"
>-*F PcdWinNtFlashNvStorageFtwWorkingBase : FIXED   (UINT32) = 0x0028E000
>-                                                  DEC DEFAULT = 0x0
>+*F PcdWinNtFlashNvStorageFtwWorkingBase : FIXED   (UINT32) =
>0x0028E000 (2678784)
>+                                                  DEC DEFAULT = 0x0 (0)
>
> gTokenSpaceGuid
>-*B LogEnable                            : FIXED   (UNIT32) = 0x1
>-                                                  DEC DEFAULT = 0x0
>+*B LogEnable                            : FIXED   (UNIT32) = 0x1 (1)
>+                                                  DEC DEFAULT = 0x0 (0)
> *P TestDynamic                          :  DYN    (VOID*) (DEFAULT) = L"COM1!COM2"
>                                         :  DYN    (VOID*) (SKU1)    = L"COM3!COM4"
>                                         :  DYN    (VOID*) (SKU2)    = L"COM5!COM6"
>                                                   DEC DEFAULT = L"COM1!COM0"
> ```
>@@ -90,22 +82,22 @@ gTokenSpaceGuid
> `<VariableGuid>:<VariableName>:<Offset>`
>
> #### Example
>
> ```
>-*P PcdGMchDvmtTotalSize : DYN-HII (UINT8) = 0
>+*P PcdGMchDvmtTotalSize : DYN-HII (UINT8) = 0x0 (0)
>                           gSysConfigGuid: L"Setup": 0xAA
> ```
>
> * if `<PcdType>` is DYN-VPD
>
> `<Offset relative to VPD base address>`
>
> #### Example
>
> ```
>-*F PcdVpdSample : DYN-VPD (UINT32) = 1
>+*F PcdVpdSample : DYN-VPD (UINT32) = 0x1 (1)
>                   0x0001FFF
> ```
>
> #### 13.6.2.2 Default (optional) line
>
>@@ -120,34 +112,33 @@ It is formatted as follows:
> `DEC DEFAULT = <Value in DEC>`
>
> #### Example
>
> ```
>-*P PcdWinNtFirmwareFdSize   : FIXED (UINT32) = 0x2a0000
>-                              DEC DEFAULT = 0x0
>+*P PcdWinNtFirmwareFdSize   : FIXED (UINT32) = 0x2a0000 (2752512)
>+                              DEC DEFAULT = 0x0 (0)
> ```
>
> #### 13.6.2.3 Additional optional lines
>
> Additional lines are optional and show if the PCD's value was obtained from
>the
>-INF file. This will be listed if the module's final PCD value is not the same
>-as the first line. The value can be obtained from the INF file only if a single
>-module uses the PCD.
>+INF file or DSC file components module scoped PCD section. This will be
>listed
>+if the module's final PCD value is not the same as the first line.
>
>-*M means the PCD's value was obtained from the INF file.
>+*M means the PCD's value was obtained from the INF file or DSC file
>components
>+module scoped PCD section.
>
> These lines are formatted as:
>
> `*M Inf Filename = <Value>`
>
> #### Example
>
> ```
>-*P PcdDebugPrintErrorLevel : PATCH (UINT32) = 0x80000042
>-                                DEC DEFAULT = 0x80000000
>-                                            = 0x80000000
>-*M Tcp4Dxe.inf                              = 0x0
>+*P PcdDebugPrintErrorLevel : PATCH (UINT32) = 0x80000042 (2147483714)
>+                                DEC DEFAULT = 0x80000000 (2147483648)
>+*M Tcp4Dxe.inf                              = 0x0 (0)
> ```
>
> **********
> **Note:** Global PCD section is present when **PCD** is specified in **-
>Y**
> option.
>@@ -162,20 +153,10 @@ additional print a *B Flag.
>
> #### Example
>
> ```
> gEfiMdePkgTokenSpaceGuid
>-*P TestFix                        :  FIXED   (TEST) = {
>-
>0xff,0x02,0x00,0x2e,0xf6,0x08,0x6f,0x19,0x5c,0x8e,0x49,0x91,0x57,0x00,0x00,
>0x00,
>-    0x00,0x64,0x00,0x00,0x00}
>-           .A             = 0x2
>-           .C             = 0x0
>-           .Array         = {0x2e,0xf6,0x08,0x6f,0x19,0x5c,0x8e,0x49,0x91,0x57}
>-           .D             = 0x64
>-                                        DEC DEFAULT = {0xFF,0xFF}
>-           .A             = 0xF
>-           .C             = 0xF
> *B TestDynamicExHii               : DEXHII    (TEST) (SKU1) (STANDARD) = {
>
>0xff,0x01,0x00,0x2e,0xf6,0x08,0x6f,0x19,0x5c,0x8e,0x49,0x91,0x57,0x00,0x00,
>0x00,
>     0x00,0x64,0x00,0x00,0x00}
>            .A             = 0x1
>        *B  .C             = 0x0
>@@ -189,6 +170,16 @@ gEfiMdePkgTokenSpaceGuid
>            .Array         = {0x2e,0xf6,0x08,0x6f,0x20,0x5c,0x8e,0x49,0x91,0x57}
>            .D             = 0x68
>                                         DEC DEFAULT = {0xFF,0xFF}
>            .A             = 0xF
>            .C             = 0xF
>+*P TestFix                        :  FIXED   (TEST) = {
>+
>0xff,0x02,0x00,0x2e,0xf6,0x08,0x6f,0x19,0x5c,0x8e,0x49,0x91,0x57,0x00,0x00,
>0x00,
>+    0x00,0x64,0x00,0x00,0x00}
>+           .A             = 0x2
>+           .C             = 0x0
>+           .Array         = {0x2e,0xf6,0x08,0x6f,0x19,0x5c,0x8e,0x49,0x91,0x57}
>+           .D             = 0x64
>+                                        DEC DEFAULT = {0xFF,0xFF}
>+           .A             = 0xF
>+           .C             = 0xF
> ```
>diff --git a/13_build_reports/137_fd_section.md
>b/13_build_reports/137_fd_section.md
>index 49c2695..43d26ec 100644
>--- a/13_build_reports/137_fd_section.md
>+++ b/13_build_reports/137_fd_section.md
>@@ -1,9 +1,9 @@
> <!--- @file
>   13.7 FD Section
>
>-  Copyright (c) 2008-2017, Intel Corporation. All rights reserved.<BR>
>+  Copyright (c) 2008-2018, Intel Corporation. All rights reserved.<BR>
>
>   Redistribution and use in source (original document form) and 'compiled'
>   forms (converted to PDF, epub, HTML and other formats) with or without
>   modification, are permitted provided that the following conditions are met:
>
>@@ -40,11 +40,11 @@ more than once in the output report. The section
>header lists the name of FD
> and its base address and size. The contents of the section consist of one or
> more FD region subsection.
>
> The line format is: "`%-20(key)s: %(value)s`" to ensure vertical alignment.
>
>-* FD Name : %FD UI name: FD file base name%
>+* FD Name : %FD file base name%
> * Base Address: %Base address for the FD image%
> * Size : %Size of the FD image%
>
> #### Example
>
>@@ -61,19 +61,19 @@ Size:             0x2a0000(2688KB)
>
> ### 13.7.2 FD Region Sub-section
>
> This sub-section contains FD region information of platform flash device. If
> the region is a firmware volume, it lists the set of modules and its space
>-information; otherwise, it only lists its region name, base address and size in
>+information; otherwise, it only lists its region type, base address and size in
> its sub-section header.
>
> The line format is: "`%-20(key)s: %(values)s`" to ensure vertical alignment.
>
>-* Region Type : %The type of the FD region (FV, Data, File or None)%
>-* Base Address: %Base address for the FD region%
>+* Type : %The type of the FD region (FV, DATA, FILE or None)%
>+* Base Address : %Base address for the FD region%
> * Size : %Size of the FD region%
>-* FV Name*: %FV name and occupation percentage%
>+* Fv Name*: %FV name and occupation percentage%
> * Occupied Size*: %The occupied size of the FV%
> * Free Size*: %The free size of the FV%
>
> The contents of FD region sub-section contain the list:
>
>@@ -87,11 +87,11 @@ The items marked with \* are only available when the
>region type is FV.
> >--------------------------------------------------------------------------<
> FD Region
> Type:             FV
> Base Address:     0x0
> Size:             0x280000 (2560K)
>-FV Name:          FvRecovery (65.9% Full)
>+Fv Name:          FvRecovery (65.9% Full)
> Occupied Size:    0x1A6028 (1688K)
> Free Size:        0xD9FD8 (872K)
> Offset     Module
> ----------------------------------------------------------------------------
> 0x00000078 PEI Apriori
>@@ -125,12 +125,12 @@ Size:             0x2000 (8K)
> ### 13.7.3 VPD PCD Sub-section
>
> This section lists, in Offset order, every VPD PCD specified in the DSC file.
> The line format for this section is PcdName SkuId Offset PcdSize PcdValue.
>
>-* Base Address:%Base address from the start of the FD file%
>-* Size :%Size of the FD region%
>+* Base Address : %Base address from the start of the FD file%
>+* Size : %Size of the FD VPD region%
>
> For each PCD in this region:
>
> * PcdName : PcdTokenSpaceGuidCname.PcdCname
> * SkuId : The string name of the SkuId for this build (or DEFAULT if no SkuId
>diff --git a/13_build_reports/138_module_section.md
>b/13_build_reports/138_module_section.md
>index 88e9ac2..52288d7 100644
>--- a/13_build_reports/138_module_section.md
>+++ b/13_build_reports/138_module_section.md
>@@ -36,38 +36,33 @@ Module section lists all modules involved in the
>platform build. If the
> are sorted according to their PEI or DXE dispatch order; otherwise the module
> sections are listed according to their DSC position.
>
> ### 13.8.1 Module Section Summary
>
>-This sub-section lists the module basic information: Module name: INF file,
>-file GUID, module size, module build time stamp and driver type.
>-
>-* `Module Name` : %Module UI name: '`BASE_NAME`' in INF `[Defines]`
>section%
>-* Module INF Path: %Path of Module INF file%
>-* File GUID: %Module GUID: '`FILE_GUID`' in INF `[Defines]` section%
>-* Size: %Module EFI image size%
>-* Build time stamp: %The time stamp in module PE32 image% (If the time
>stamp is
>-  cleared to be zero, the build time stamp is 1970-01-01 00:00:00 UTC time.)
>-* Module Build Time: %The time string for this module's build%
>-* Driver Type: %The driver's file type code[^2] and name in firmware volume%
>+This sub-section lists the module basic information: Module name, INF file
>+path, File GUID, Size, hash value, module build time stamp, module build
>time
>+and driver type.
>+
>+* Module Name : %`BASE_NAME` in INF `[Defines]` section%
>+* Module INF Path : %Path of Module INF file%
>+* File GUID : %`FILE_GUID` in INF `[Defines]` section%
>+* Size : %Module EFI image size%
>+* SHA1 HASH : %SHA1 hash value and efi file name with \* character%
>+* Build Time Stamp : %The time stamp in module PE32 image% (If the time
>stamp is
>+  cleared to be zero, the build time stamp is 1970-01-01 08:00:00 UTC time.)
>+* Module Build Time : %The time string for this module's build%
>+* Driver Type : %The driver's file type code[^3] and name in firmware
>volume%
>
> The following entries are options:
>
>-* If using defaults or the `HASH` flag is specified:
>-  - SHA1 HASH: %SHA1 HASH% and *%Module .efi file name%
>-* UEFI Specification Version: %The UEFI specification
>-  version:'`UEFI_SPECIFICATION_VERSION`' in INF `[Defines]` section%
>-* PI Specification Version: %The PI specification
>-  version:'`PI_SPECIFICATION_VERSION`' in the INF `[Defines]` section%
>-* `PCI Device ID`: %The PCI device ID for the device: '`PCI_DEVICE_ID`' in INF
>-  `[Defines]` section%
>-* `PCI Vendor ID`: %The PCI vendor ID for the device: '`PCI_VENDOR_ID`' in
>INF
>-  `[Defines]` section%
>-* `PCI Class Code`: %The PCI class code for the device: '`PCI_CLASS_CODE`' in
>-  INF `[Defines]` section%
>-
>-[^2] The hex value in this field is the Firmware File Type value defined in
>+* UEFI Spec Version : %`UEFI_SPECIFICATION_VERSION` in INF `[Defines]`
>section%
>+* PI Spec Version : %`PI_SPECIFICATION_VERSION` in INF `[Defines]` section%
>+* PCI Device ID : %`PCI_DEVICE_ID` in INF `[Defines]` section%
>+* PCI Vendor ID : %`PCI_VENDOR_ID` in INF `[Defines]` section%
>+* PCI Class Code : %`PCI_CLASS_CODE` in INF `[Defines]` section%
>+
>+[^3] The hex value in this field is the Firmware File Type value defined in
> Volume 3 of the PI Specification (Table 3 Defined File Types).
>
>
> #### Example1:
>
>@@ -77,11 +72,11 @@ Module Summary
> Module Name:        SmbiosDxe
> Module INF Path:    MdeModule\Universal\SmbiosDxe\SmbiosDxe.inf
> File GUID:          F9D88642-0737-49BC-81B5-6889CD57D9EA
> Size:               0x7000 (28.00K)
> SHA1 HASH:          d94c3f180f25d6b562f477bc4a16b286cb66a8b6
>*SmbiosDxe.efi
>-Build Time Stamp:   1969-12-31 16:00:00
>+Build Time Stamp:   1970-01-01 08:00:00
> Module Build Time:  1060ms
> Driver Type:        0x7 (DRIVER)
>
>===========================================================
>=================
> ... (Module Section Details for SmbiosDxe)
>
><==========================================================
>================>
>@@ -95,11 +90,11 @@ Module Summary
> Module Name:        EbcDxe
> Module INF Path:    MdeModule\Universal\EbcDxe\EbcDxe.inf
> File GUID:          13AC6DD0-73D0-11D4-B06B-00AA00BD6DE7
> Size:               0x9000 (36.00K)
> SHA1 HASH:          ff4c019345614afe5c88e7fc37219c30a07f4af4 *EbcDxe.efi
>-Time Stamp:         1969-12-31 16:00:00
>+Time Stamp:         1970-01-01 08:00:00
> Module Build Time:  1731ms
> Driver Type:        0x7 (DRIVER)
>
>===========================================================
>=================
> ... (Module Section Details for EbcDxe)
>
>@@ -128,12 +123,11 @@ instance's INF path.
> An example of the module's library instance section is shown below.
>
> Following the subsection header, for each library instance that was linked, the
> format is:
>
>-1. The first line is the INF file name; this is the fully qualified path and
>-   file name of the library instance
>+1. The first line is the INF file path of the library instance
>
> 2. {ClassName} - the name of the library class that the above INF file provides
>
>    * If constructors are provided, for each constructor, the following content
>      is inserted in the curly braces after the ClassName:
>@@ -150,11 +144,11 @@ format is:
>    * Display the build time.
>      ```
>      Time = TimeString
>      ```
>
>-#### Example1:
>+#### Example:
>
> ```c
> >--------------------------------------------------------------------------<
> Library
> ---------------------------------------------------------------------------
>@@ -193,31 +187,10 @@
>s:\edk2\MdePkg\Library\UefiDriverEntryPoint\UefiDriverEntryPoint.inf
> s:\edk2\MdePkg\Library\UefiRuntimeLib\UefiRuntimeLib.inf
> {UefiRuntimeLib: C = UefiRuntimeLibConstructor D =
>UefiRuntimeLibDestructor Time = 265ms}
> <-------------------------------------------------------------------------->
> ```
>
>-#### Example2:
>-
>-```
>->--------------------------------------------------------------------------<
>-Library
>----------------------------------------------------------------------------
>-s:\edk2\R8MyPlatformPkg\Guid\GuidLib.inf
>-s:\edk2\EdkCompatibilityPkg\Foundation\Guid\EdkGuidLib.inf
>-s:\edk2\EdkCompatibilityPkg\Foundation\Protocol\EdkProtocolLib.inf
>-
>s:\edk2\EdkCompatibilityPkg\Foundation\Library\RuntimeDxe\EfiRuntimeLib
>\EfiRuntimeLib.inf
>-
>s:\edk2\EdkCompatibilityPkg\Foundation\Core\Dxe\ArchProtocol\ArchProtoc
>olLib.inf
>-
>s:\edk2\EdkCompatibilityPkg\Foundation\Library\CompilerStub\CompilerStu
>bLib.inf
>-s:\edk2\EdkCompatibilityPkg\Foundation\Guid\EdkGuidLib.inf
>-
>s:\edk2\EdkCompatibilityPkg\Foundation\Framework\Protocol\EdkFramewor
>kProtocolLib.inf
>-s:\edk2\EdkCompatibilityPkg\Foundation\Efi\Guid\EfiGuidLib.inf
>-s:\edk2\EdkCompatibilityPkg\Foundation\Efi\Protocol\EfiProtocolLib.inf
>-
>s:\edk2\EdkCompatibilityPkg\Foundation\Library\EfiCommonLib\EfiCommonL
>ib.inf
>-
>s:\edk2\EdkCompatibilityPkg\Foundation\Framework\Guid\EdkFrameworkG
>uidLib.inf
>-<-------------------------------------------------------------------------->
>-```
>-
> **********
> **Note:** This sub-section is present when **LIBRARY** is specified in **-
>Y**
> option.
> **********
>
>@@ -226,34 +199,28 @@ option.
> This sub-section (following the Module Summary information) holds the
> information for all PCDs used in this module. The content of module PCD
> sub-section is divided by token space such as:
>
> ```
>-gEfiNt32PkgTokenSpaceGuid
>+gEfiMdeModulePkgTokenSpaceGuid
> ...
> ...
>-gEfiMdeModulePkgTokenSpaceGuid
>+gEfiNt32PkgTokenSpaceGuid
> ...
> ...
> ...
> ```
>
>-Each PCD may contain up to four lines:
>+Each PCD may contain up to following lines:
>
> 1. The first line is a mandatory line with the following format:
>-   `[*P|*F|*B|*M] <PcdCName>: <PcdType> (<DatumType>)
>[(<SKUID>)][(<DefaultStore>)] = <PcdValue>`
>+
>+   `[*B|*F|*P|*M] <PcdCName> : <PcdType> (<DatumType>)
>[(<SKUID>)][(<DefaultStore>)] = <PcdValue>`
>
>    **Note: ** If the Pcd is a Structure PCD, `<DatumType>` is the Struct Name.
>
>-   - \*P means the Pcd's value is the platform default (listed in DSC PCD
>common
>-     section or inherited from Module INF file).
>-   - \*M means the PCD's value in module INF was obtained from the
>`[Components]`
>-     section of the DSC file.
>-   - \*F means the PCD's value is override in FDF file.
>-   - \*B means the PCD's value is override in build option.
>-   - If no \*P or \*F or \*B or \*M, mean the PCD's value comes from DEC file.
>-   - For example:
>+   For example:
>      ```
>      *P PcdWinNtFirmwareVolume : FIXED (VOID*) = L"..\\Fv\\Nt32.fd"
>      ```
>
> 2. The second line is the optional line
>@@ -261,20 +228,20 @@ Each PCD may contain up to four lines:
>      ```
>      <VariableGuid>:<VariableName>:<Offset>
>      ```
>      For example:
>      ```
>-     *P PcdGMchDvmtTotalSize : DYN-HII (UINT8) = 0
>+     *P PcdGMchDvmtTotalSize : DYN-HII (UINT8) = 0x0 (0)
>                                gSysConfigGuid: L"Setup": 0xAA
>      ```
>    - if `<PcdType>` is DYN-VPD
>      ```
>      <Offset relative to VPD base address>
>      ```
>      For example:
>      ```
>-     *F PcdVpdSample : DYN-VPD (UINT32) = 1
>+     *F PcdVpdSample : DYN-VPD (UINT32) = 0x1 (1)
>                        0x0001FFF
>      ```
>
> 3. The third and fourth lines are both option if the module's final
>    `<PcdValue>` is not equal to the PCD value in the PCD common section in
>the
>@@ -283,16 +250,16 @@ Each PCD may contain up to four lines:
>    DSC DEFAULT = <Value in PCD Common Section in DSC>
>    DEC DEFAULT = <Value in DEC>
>    ```
>    For example:
>    ```
>-   *P PcdPlatformBootTimeOut : DYNHII (UINT16) = 10
>+   *M PcdDebugPrintErrorLevel : FIXED   (UINT32) = 0x80000042 (2147483714)
>+                                DSC DEFAULT = 0x80000040 (2147483712)
>+                                DEC DEFAULT = 0x80000000 (2147483648)
>+   *P PcdPlatformBootTimeOut : DYNHII (UINT16) = 0xA (10)
>                      gEfiGlobalVariableGuid: L"Timeout": 0x0
>-                                                   DEC DEFAULT = 0xffff
>-   *M PcdDebugPrintErrorLevel : FIXED   (UINT32) = 0x80000042
>-                                DSC DEFAULT = 0x80000040
>-                                DEC DEFAULT = 0x80000000
>+                                DEC DEFAULT = 0xffff (65535)
>    ```
>
> 4. Additional lines may exist if the PCD is Structure PCD. Every field value
> that user specified in DSC/DEC file and build command will print out. The field
> value is from DSC/DEC file or build command, not from the final structure
>byte
>diff --git a/13_build_reports/README.md b/13_build_reports/README.md
>index 9050690..b774d68 100644
>--- a/13_build_reports/README.md
>+++ b/13_build_reports/README.md
>@@ -1,9 +1,9 @@
> <!--- @file
>   13 Build Reports
>
>-  Copyright (c) 2008-2017, Intel Corporation. All rights reserved.<BR>
>+  Copyright (c) 2008-2018, Intel Corporation. All rights reserved.<BR>
>
>   Redistribution and use in source (original document form) and 'compiled'
>   forms (converted to PDF, epub, HTML and other formats) with or without
>   modification, are permitted provided that the following conditions are met:
>
>@@ -34,11 +34,11 @@
> This section introduces the build report generation tool functionality and its
> output report format. It describes the external behaviors of the tool, i.e. the
> accepted command line options and the detailed output report format.
>
> Unless the quiet or silent options are given to the build command, the build
>-system automatically reports the following:
>+system automatically reports the following in build log file:
>
> * Each region, offset and size defined in the FD.
> * The location of the GUID cross reference file.
> * The size of the data in each FV region.
> * The date and time the build completed.
>--
>2.6.1.windows.1



^ permalink raw reply	[flat|nested] 2+ messages in thread

end of thread, other threads:[~2018-06-07  8:12 UTC | newest]

Thread overview: 2+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2018-06-05 12:17 [Patch] Build spec: Add a Common PCD rules section for build report Yonghong Zhu
2018-06-07  8:12 ` Gao, Liming

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox