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

_______________________________________________
edk2-devel mailing list
edk2-devel@lists.01.org
https://lists.01.org/mailman/listinfo/edk2-devel

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

_______________________________________________
edk2-devel mailing list
edk2-devel@lists.01.org
https://lists.01.org/mailman/listinfo/edk2-devel