[edk2-BuildSpecification PATCH] Add conditional and unused PCD report sections

[edk2-BuildSpecification PATCH] Add conditional and unused PCD report sections

[Michael Kinney]

https://bugzilla.tianocore.org/show_bug.cgi?id=508

GitHub branch for review:

* https://github.com/mdkinney/edk2-BuildSpecification/tree/Bugzilla_508_UpdatePcdReports

GitHub word diff view of the patches in this series:

* [1/1] https://github.com/mdkinney/edk2-BuildSpecification/commit/13482c8dab5491fa8965bcb7084310ad54b370be?w=1

* List PCDs that are used in conditional directives
  in the DSC and FDF files that are not used in
  module code.
* List PCDs that are not used anywhere
* Add *B PCD key to show PCD values set using
  a build option (e.g. --pcd)

Cc: Liming Gao <liming.gao@intel.com>
Cc: Yonghong Zhu <yonghong.zhu@intel.com>
Cc: Kevin W Shaw <kevin.w.shaw@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Michael Kinney <michael.d.kinney@intel.com>

Michael Kinney (1):
  Add conditional and unused PCD report sections

 13_build_reports/133_output.md             |  2 +
 13_build_reports/134_platform_summary.md   | 93 ++++++++++++++++++++++++++++++
 13_build_reports/136_global_pcd_section.md | 20 +++++--
 README.md                                  |  1 +
 4 files changed, 110 insertions(+), 6 deletions(-)

-- 
2.6.3.windows.1

[edk2-BuildSpecification PATCH] Add conditional and unused PCD report sections

[Michael Kinney]

https://bugzilla.tianocore.org/show_bug.cgi?id=508

* List PCDs that are used in conditional directives
  in the DSC and FDF files that are not used in
  module code.
* List PCDs that are not used anywhere
* Add *B PCD key to show PCD values set using
  a build option (e.g. --pcd)

Cc: Liming Gao <liming.gao@intel.com>
Cc: Yonghong Zhu <yonghong.zhu@intel.com>
Cc: Kevin W Shaw <kevin.w.shaw@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Michael Kinney <michael.d.kinney@intel.com>
---
 13_build_reports/133_output.md             |  2 +
 13_build_reports/134_platform_summary.md   | 93 ++++++++++++++++++++++++++++++
 13_build_reports/136_global_pcd_section.md | 20 +++++--
 README.md                                  |  1 +
 4 files changed, 110 insertions(+), 6 deletions(-)

diff --git a/13_build_reports/133_output.md b/13_build_reports/133_output.md
index ce64efd..5eb2c8e 100644
--- a/13_build_reports/133_output.md
+++ b/13_build_reports/133_output.md
@@ -51,6 +51,8 @@ The layout of the text report file:
 
 ```
 |---- Platform summary
+    |----- Conditional directives section
+    |----- Unused PCDs section
     |----- Mixed PCD section
     |----- Global PCD section
     |----- FD section*
diff --git a/13_build_reports/134_platform_summary.md b/13_build_reports/134_platform_summary.md
index 7c08050..e6f2a15 100644
--- a/13_build_reports/134_platform_summary.md
+++ b/13_build_reports/134_platform_summary.md
@@ -63,3 +63,96 @@ Report Contents:    PCD, LIBRARY, BUILD_FLAGS, DEPEX, FLASH, FIXED_ADDRESS
 **Note:** Platform Summary is always present and appears at the beginning of
 report.
 **********
+
+If the DSC or FDF file contains conditional directive statements (`!if`,
+`!elseif`, `!ifdef` or `!ifndef`) or the value of PCD is not used by a module is
+set in the DSC file (PCD Sections) or the FDF file (`SET` statements for
+example), the following sub-section is generated.
+
+```
+==========================================================================<
+Conditional Directives used by the build system
+============================================================================
+```
+
+If the DSC or FDF file define values for PCDs that are not used by any module
+and are not used in conditional directive statements, the following sub-section
+is generated.
+
+```
+==========================================================================<
+PCDs not used by modules or in conditional directives
+============================================================================
+```
+
+### 13.4.1 PCDs in Conditional Directives
+
+If a PCD is used in a conditional directive statement, the PCD section is
+generated.
+
+PCD values derived from expressions or other PCDs are not differentiated in the
+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.
+
+Additional lines may be displayed showing default values when the value is not a
+default value.
+
+### Example
+
+```
+>==========================================================================<
+Conditional Directives used by the build system
+============================================================================
+PCD statements
+>--------------------------------------------------------------------------<
+gMyTokenSpaceGuid
+*P SmmEnable                   : FEATURE (BOOLEAN) = 0x0
+                                         DEC DEFAULT = 0x1
+*B LogEnable                   : FIXED   (UNIT32) = 0x1
+                                         DEC DEFAULT = 0x0
+<-------------------------------------------------------------------------->
+>==========================================================================<
+```
+
+### 13.4.2 PCDs not used
+
+If a PCD is not used in a conditional directive statement or by a module, the
+not used PCD section is generated.
+
+PCD values derived from expressions or other PCDs are not differentiated in the
+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.
+
+Additional lines may be displayed showing default values when the value is not a
+default value.
+
+### Example
+
+```
+>==========================================================================<
+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
+<-------------------------------------------------------------------------->
+>==========================================================================<
+```
diff --git a/13_build_reports/136_global_pcd_section.md b/13_build_reports/136_global_pcd_section.md
index f24f97a..d768488 100644
--- a/13_build_reports/136_global_pcd_section.md
+++ b/13_build_reports/136_global_pcd_section.md
@@ -45,19 +45,23 @@ gEfiMdeModulePkgTokenSpaceGuid
 ...
 ```
 
+PCD values derived from expressions or other PCDs are not differentiated in the
+report. Only the final value is displayed.
+
 Each global PCD item contains one or more lines:
 
 ### 13.6.1 Required line
 
 The first line is required:
 
-`[*P|*F| ] <PcdCName>: <PcdType> (<DatumType>) = <PcdValue>`
+`[*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.
-* If no *P or *F is given, the PCD's value comes from DEC file. If the value
-  obtained from either the DSC or FDF is the same as the value in the DEC, then
-  neither *P nor *F will be shown in the report.
+* `*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.
 
 #### Examples
 
@@ -65,6 +69,10 @@ The first line is required:
 *P PcdWinNtFirmwareVolume               : FIXED   (VOID*) = L"..\\Fv\\Nt32.fd"
 *F PcdWinNtFlashNvStorageFtwWorkingBase : FIXED   (UINT32) = 0x0028E000
                                                   DEC DEFAULT = 0x0
+
+gTokenSpaceGuid
+*B LogEnable                            : FIXED   (UNIT32) = 0x1
+                                                  DEC DEFAULT = 0x0
 ```
 
 ### 13.6.2 Optional lines
diff --git a/README.md b/README.md
index 89578d0..817164a 100644
--- a/README.md
+++ b/README.md
@@ -208,3 +208,4 @@ Copyright (c) 2008-2017, Intel Corporation. All rights reserved.
 |            | [#479](https://bugzilla.tianocore.org/show_bug.cgi?id=479) Build spec: add description for nmake long command line handling                                                                                                                                                                                                                                         |               |
 |            | [#485](https://bugzilla.tianocore.org/show_bug.cgi?id=485) Build spec: add support for mixed Pcd access method                                                                                                                                                                                                                                                      |               |
 |            | [#476](https://bugzilla.tianocore.org/show_bug.cgi?id=476) Build spec: add support for HII image package                                                                                                                                                                                                                                                            |               |
+|            | [#508](https://bugzilla.tianocore.org/show_bug.cgi?id=508) Build Spec: Add sections to PCD report for PCDs only used in conditions PCDs that are not used anywhere                                                                                                                                                                                                  |               |
-- 
2.6.3.windows.1

Re: [edk2-BuildSpecification PATCH] Add conditional and unused PCD report sections

[Zhu, Yonghong]

Reviewed-by: Yonghong Zhu <yonghong.zhu@intel.com> 

Best Regards,
Zhu Yonghong


-----Original Message-----
From: Kinney, Michael D 
Sent: Wednesday, April 26, 2017 2:33 PM
To: edk2-devel@lists.01.org
Cc: Gao, Liming <liming.gao@intel.com>; Zhu, Yonghong <yonghong.zhu@intel.com>; Shaw, Kevin W <kevin.w.shaw@intel.com>
Subject: [edk2-BuildSpecification PATCH] Add conditional and unused PCD report sections

https://bugzilla.tianocore.org/show_bug.cgi?id=508

GitHub branch for review:

* https://github.com/mdkinney/edk2-BuildSpecification/tree/Bugzilla_508_UpdatePcdReports

GitHub word diff view of the patches in this series:

* [1/1] https://github.com/mdkinney/edk2-BuildSpecification/commit/13482c8dab5491fa8965bcb7084310ad54b370be?w=1

* List PCDs that are used in conditional directives
  in the DSC and FDF files that are not used in
  module code.
* List PCDs that are not used anywhere
* Add *B PCD key to show PCD values set using
  a build option (e.g. --pcd)

Cc: Liming Gao <liming.gao@intel.com>
Cc: Yonghong Zhu <yonghong.zhu@intel.com>
Cc: Kevin W Shaw <kevin.w.shaw@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Michael Kinney <michael.d.kinney@intel.com>

Michael Kinney (1):
  Add conditional and unused PCD report sections

 13_build_reports/133_output.md             |  2 +
 13_build_reports/134_platform_summary.md   | 93 ++++++++++++++++++++++++++++++
 13_build_reports/136_global_pcd_section.md | 20 +++++--
 README.md                                  |  1 +
 4 files changed, 110 insertions(+), 6 deletions(-)

-- 
2.6.3.windows.1