Re: [Patch] Build spec: Add some clarification and clean up for build report

["Gao, Liming" <liming.gao@intel.com>]

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

>-----Original Message-----
>From: Zhu, Yonghong
>Sent: Monday, April 02, 2018 11:30 AM
>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 some clarification and clean up for build
>report
>
>Add some clarification and clean up for build report section.
>
>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>
>---
> 13_build_reports/134_platform_summary.md   | 44 +++++++++++-------------
>------
> 13_build_reports/136_global_pcd_section.md |  7 +++--
> 13_build_reports/138_module_section.md     | 11 +++++---
> 3 files changed, 27 insertions(+), 35 deletions(-)
>
>diff --git a/13_build_reports/134_platform_summary.md
>b/13_build_reports/134_platform_summary.md
>index 09b8db6..23964af 100644
>--- a/13_build_reports/134_platform_summary.md
>+++ b/13_build_reports/134_platform_summary.md
>@@ -1,9 +1,9 @@
> <!--- @file
>   13.4 Platform Summary
>
>-  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:
>
>@@ -72,35 +72,14 @@ 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.
>+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
> report. Only the final value is displayed.
>
> The first line is required:
>@@ -108,11 +87,15 @@ 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.
>-**Note:** If the Pcd is a Structure PCD, <DatumType> is the Struct Name.
>+* 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.
>
> ### Example
>@@ -132,12 +115,13 @@ gMyTokenSpaceGuid
> >==========================================================
>================<
> ```
>
> ### 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.
>+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.
>
> 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:
>@@ -145,11 +129,15 @@ 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.
>-**Note:** If the Pcd is a Structure PCD, <DatumType> is the Struct Name.
>+* 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.
>
> Since the PCDs in this section are not used by any module, the PCD value is
>not
>diff --git a/13_build_reports/136_global_pcd_section.md
>b/13_build_reports/136_global_pcd_section.md
>index a9661b6..2a5b682 100644
>--- a/13_build_reports/136_global_pcd_section.md
>+++ b/13_build_reports/136_global_pcd_section.md
>@@ -1,9 +1,9 @@
> <!--- @file
>   13.6 Global 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:
>
>@@ -60,11 +60,12 @@ The first line is required:
> * `*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.
>+
>+**Note: ** If the Pcd is a Structure PCD, `<DatumType>` is the Struct Name.
>
> #### Examples
>
> ```
> *P PcdWinNtFirmwareVolume               : FIXED   (VOID*) = L"..\\Fv\\Nt32.fd"
>@@ -109,11 +110,11 @@ gTokenSpaceGuid
> #### 13.6.2.2 Default (optional) line
>
> The second optional line is present if the value from the DSC was overridden
> by build option. It is formatted as follows:
>
>-`DSC DEFAULT = <Value in PCD SectionSection in DSC>`
>+`DSC DEFAULT = <Value in PCD Section in DSC>`
>
> The third optional line is present if the value from the DEC was overridden.
> It is formatted as follows:
>
> `DEC DEFAULT = <Value in DEC>`
>diff --git a/13_build_reports/138_module_section.md
>b/13_build_reports/138_module_section.md
>index fb2417d..88e9ac2 100644
>--- a/13_build_reports/138_module_section.md
>+++ b/13_build_reports/138_module_section.md
>@@ -1,9 +1,9 @@
> <!--- @file
>   13.8 Module 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:
>
>@@ -238,18 +238,21 @@ gEfiMdeModulePkgTokenSpaceGuid
> ```
>
> Each PCD may contain up to four lines:
>
> 1. The first line is a mandatory line with the following format:
>-   `[*P|*F|*B] <PcdCName>: <PcdType> (<DatumType>)
>[(<SKUID>)][(<DefaultStore>)] = <PcdValue>`
>-   **Note:** If the Pcd is a Structure PCD, <DatumType> is the Struct Name.
>+   `[*P|*F|*B|*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.
>-   - If no \*P or \*F, mean the PCD's value comes from DEC 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:
>      ```
>      *P PcdWinNtFirmwareVolume : FIXED (VOID*) = L"..\\Fv\\Nt32.fd"
>      ```
>
>--
>2.6.1.windows.1