[edk2-BuildSpecification PATCH V2 0/2] Add --pcd flag to override PCD values on command line

[edk2-BuildSpecification PATCH V2 0/2] Add --pcd flag to override PCD values on command line

[Michael Kinney]

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

GitHub branch for review:

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

GitHub word diff view of the patches in this series:

* [1/2] https://github.com/mdkinney/edk2-BuildSpecification/commit/53408b682ae7e31a4a98e96fb6ed3e9843605dd2?w=1
* [2/2] https://github.com/mdkinney/edk2-BuildSpecification/commit/9dd3bf48cbdfc0ace23141127b2b471e58d59b53?w=1

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 (2):
  Clean up minor formatting issues
  Add --pcd flag to override PCD values on command line

 .../43_pre-build_stage_overview.md                 | 35 ++++++++++----------
 .../45_post-build_stage.md                         | 12 +++----
 .../82_auto-generation_process.md                  | 37 ++++++++++++++++++----
 .../84_auto-generated_pcd_database_file.md         | 34 +++++++++++---------
 .../87_generated_asbuilt_inf_files.md              |  2 +-
 README.md                                          |  1 +
 appendix_d_buildexe_command/d4_usage.md            |  1 +
 7 files changed, 75 insertions(+), 47 deletions(-)

-- 
2.6.3.windows.1

[edk2-BuildSpecification PATCH V2 1/2] Clean up minor formatting issues

[Michael Kinney]

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>
---
 .../43_pre-build_stage_overview.md                 | 22 ++++++++++------------
 .../45_post-build_stage.md                         | 12 ++++++------
 .../82_auto-generation_process.md                  |  2 +-
 .../87_generated_asbuilt_inf_files.md              |  2 +-
 4 files changed, 18 insertions(+), 20 deletions(-)

diff --git a/4_edk_ii_build_process_overview/43_pre-build_stage_overview.md b/4_edk_ii_build_process_overview/43_pre-build_stage_overview.md
index 30177a8..0fde612 100644
--- a/4_edk_ii_build_process_overview/43_pre-build_stage_overview.md
+++ b/4_edk_ii_build_process_overview/43_pre-build_stage_overview.md
@@ -250,21 +250,19 @@ directory name and the `BASE_NAME` of the module's INF file.
 
    * Create the module Makefiles
 
-   Individual modules may require different compilation options, over-riding any
-   global definitions. If an INF file is not listed in the DSC file and is listed
-   in the FDF file, the parsing tools must check if the INF in the FDF file
-   contains `PatchableInModule` or `DynamicEX` entries. If the INF lists other PCD
-   access methods (FeatureFlag,
-
-   FixedAtBuild or Dynamic), and the INF contains files listed in a `[Sources]`
-   section and does not contain a `[Binaries]` section, then the build tools must
-   break the build with an appropriate error message.
+   Individual modules may require different compilation options, over-riding
+   any global definitions. If an INF file is not listed in the DSC file and is
+   listed in the FDF file, the parsing tools must check if the INF in the FDF
+   file contains `PatchableInModule` or `DynamicEX` entries. If the INF lists
+   other PCD access methods (FeatureFlag, FixedAtBuild or Dynamic), and the INF
+   contains files listed in a `[Sources]` section and does not contain a
+   `[Binaries]` section, then the build tools must break the build with an
+   appropriate error message.
 
 6. The tools are also responsible for creating binary files containing all
    `DynamicEx` PCDs that are listed in the DSC, FDF and Binary INF files
-   (listed in the FDF file).
-   These binaries are automatically placed into the (PEIM and DXE) PCD driver FFS
-   files.
+   (listed in the FDF file). These binaries are automatically placed into the
+   (PEIM and DXE) PCD driver FFS files.
 
 7. If the build option, --ignore-sources is present on the build command-line,
    none of the source files listed in a [Sources] section will be processed,
diff --git a/4_edk_ii_build_process_overview/45_post-build_stage.md b/4_edk_ii_build_process_overview/45_post-build_stage.md
index c8a90e1..c35d9be 100644
--- a/4_edk_ii_build_process_overview/45_post-build_stage.md
+++ b/4_edk_ii_build_process_overview/45_post-build_stage.md
@@ -64,12 +64,12 @@ following must occur.
    that entry must be ignored - these files are not to be placed into an
    `EFI_SECTION_DISPOSABLE` encapsulation section.
 
-2. If an INF not listed in the DSC file. is listed in the FDF file and the INF
-   contains a `[PatchPcd]` section, the tools must test to determine if the PCD
-   is listed in the DSC (or FDF) file, and whether the value listed in the DSC
-   (or FDF) file is different from the value in the INF file. If the value is
-   different, the tools must patch the binary .efi file with the value from the
-   FDF or DSC file prior to creating the EFI leaf section.
+2. If an INF not listed in the DSC file, but is listed in the FDF file and the
+   INF contains a `[PatchPcd]` section, the tools must test to determine if the
+   PCD is listed in the DSC (or FDF) file, and whether the value listed in the
+   DSC (or FDF) file is different from the value in the INF file. If the value
+   is different, the tools must patch the binary .efi file with the value from
+   the FDF or DSC file prior to creating the EFI leaf section.
 
 3. The tools are also responsible for creating binary files containing all
    DynamicEx PCDs that are listed in the DSC, FDF and Binary INF files (listed
diff --git a/8_pre-build_autogen_stage/82_auto-generation_process.md b/8_pre-build_autogen_stage/82_auto-generation_process.md
index 6868d62..92b6d99 100644
--- a/8_pre-build_autogen_stage/82_auto-generation_process.md
+++ b/8_pre-build_autogen_stage/82_auto-generation_process.md
@@ -772,7 +772,7 @@ that is unique to the GUID known as the TokenSpaceGuidCName.
 
 The following list defines the five PCD access methods.
 
-* **FeatureFlag PCD**; used in conditional directive statements in code.
+* **FeatureFlag PCD** - used in conditional directive statements in code.
 
 * **PatchableInModule PCD** - a volatile variable that can be updated either
   during a build or by a tool that knows the offset and data size of the
diff --git a/8_pre-build_autogen_stage/87_generated_asbuilt_inf_files.md b/8_pre-build_autogen_stage/87_generated_asbuilt_inf_files.md
index 9e89d83..0f39879 100644
--- a/8_pre-build_autogen_stage/87_generated_asbuilt_inf_files.md
+++ b/8_pre-build_autogen_stage/87_generated_asbuilt_inf_files.md
@@ -431,7 +431,7 @@ For ACPI files from a platform, the entry must use the following format:
 
 `<TS> ACPI|Filename.acpi <EOL>`
 
-For a Binary or raw binary file, the entry may use either of the the following
+For a Binary or raw binary file, the entry may use either of the following
 two formats:
 
 ```
-- 
2.6.3.windows.1

[edk2-BuildSpecification PATCH V2 2/2] Add --pcd flag to override PCD values on command line

[Michael Kinney]

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

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>
---
 .../43_pre-build_stage_overview.md                 | 13 ++++----
 .../82_auto-generation_process.md                  | 35 ++++++++++++++++++----
 .../84_auto-generated_pcd_database_file.md         | 34 +++++++++++----------
 README.md                                          |  1 +
 appendix_d_buildexe_command/d4_usage.md            |  1 +
 5 files changed, 57 insertions(+), 27 deletions(-)

diff --git a/4_edk_ii_build_process_overview/43_pre-build_stage_overview.md b/4_edk_ii_build_process_overview/43_pre-build_stage_overview.md
index 0fde612..7dca93a 100644
--- a/4_edk_ii_build_process_overview/43_pre-build_stage_overview.md
+++ b/4_edk_ii_build_process_overview/43_pre-build_stage_overview.md
@@ -213,9 +213,10 @@ directory name and the `BASE_NAME` of the module's INF file.
      system parses the name of the 'map' file that contains an ordered list
      of VPD PCDs.
 
-   * There are some PCD values that get set in the FDF file, listed in binary
-     INF files or listed in source INF files, so generating the C files is
-     delayed until all PCD values have been finalized.
+   * There are some PCD values that get set on the command line, in the FDF
+     file, listed in binary INF files or listed in source INF files, so
+     generating the C files is delayed until all PCD values have been
+     finalized.
 
 4. Obtain the FDF filename and obtain the Flash related PCDs from the FDF file.
    FeatureFlag and FixedAtBuild PCD names which are defined in the DSC file can
@@ -230,9 +231,9 @@ directory name and the `BASE_NAME` of the module's INF file.
 
    * Create the Library Instance's AutoGen.c files containing PCD, Guid,
      Protocol, Ppi and EntryPoint definitions and data structures. PCD values
-     come from FDF file, DSC's INF scoped section, DSC's global PCD sections,
-     default values in the INF file's PCD section, or the DEC file's default
-     values.
+     come from command line, FDF file, DSC's INF scoped section, DSC's global
+     PCD sections, default values in the INF file's PCD section, or the DEC
+     file's default values.
 
    * Create the module's library instance Makefiles
 
diff --git a/8_pre-build_autogen_stage/82_auto-generation_process.md b/8_pre-build_autogen_stage/82_auto-generation_process.md
index 92b6d99..a4cb1b4 100644
--- a/8_pre-build_autogen_stage/82_auto-generation_process.md
+++ b/8_pre-build_autogen_stage/82_auto-generation_process.md
@@ -417,15 +417,16 @@ FDF files.
 of the DSC, FDF and any of the included EDK INF files.
 
 Macro values must be defined prior to using them in directive statements or for
-PCD values. The following provides the rules for obtaining macro values.
+PCD values. The following provides the precedence (high to low) for obtaining
+macro values.
 
-* Highest - Command-line, `-D` flags (left most has higher priority)
+* Command-line, `-D` flags (left most has higher priority)
 * FDF file, `DEFINE` statements override previous definitions in the
   `[Defines]` section
 * FDF file, `DEFINE` statements in the `[Defines]` section
 * DSC file, Component INF `DEFINE` statements embedded in `<subsections>`
 * DSC file, `DEFINE` statements in sections following the `[Defines]` section
-* Lowest - DSC file, `DEFINE` statements in the `[Defines]` section
+* DSC file, `DEFINE` statements in the `[Defines]` section
 
 **********
 **Note:** Macros defined in the DSC file's `[Defines]` section are common to
@@ -852,15 +853,16 @@ create a platform scoped PCD Database.
 
 The values that are assigned to individual PCDs required by a build may come
 from different locations and different meta-data files. The following provides
-the rules required to assign a value to a PCD.
+the precedence (high to low) to assign a value to a PCD.
 
-* Highest - FDF file, SET statements within a section
+* Command-line, `--pcd` flags (left most has higher priority)
+* FDF file, SET statements within a section
 * FDF file, grammar describing automatic assignment of PCD values
 * FDF file, SET statement in the [Defines] section
 * DSC file, Component INF `<Pcd*>` section statements
 * DSC file, global [Pcd*] sections
 * INF file, PCD sections, Default Values
-* Lowest - DEC file, PCD sections, Default Values
+* DEC file, PCD sections, Default Values
 
 In addition to the above precedence rules, PCDs set in sections with
 architectural modifiers take precedence over PCD sections that are common to
@@ -869,6 +871,26 @@ all architectures.
 When listed in the same section. If listed multiple times, the last one will be
 used.
 
+A PCD value set on the command-line has the highest precedence. It overrides
+all instances of the PCD value specified in the DSC or FDF file. The following
+is the syntax to override the value of a PCD on the command line:
+
+`--pcd [<TokenSpaceGuidCname>.]<PcdCName>=<Value>`
+
+For `VOID*` type PCDs, `<Value>` supports the following syntax:
+
+* ASCII string value for a `VOID*` PCD
+
+  `--pcd  [<TokenSpaceGuidCname>.]<PcdCName>="String"`
+
+*  Unicode string value for a `VOID*` PCD
+
+  `--pcd  [<TokenSpaceGuidCname>.]<PcdCName>=L"String"`
+
+*  Byte array value for a `VOID*` PCD
+
+  `--pcd  [<TokenSpaceGuidCname>.]<PcdCName>= H"{0x1, 0x2}"`
+
 **********
 **Note:** The EDK II meta-data specs have changed to permit a PCD entry (or any
 other entry) to be listed only one time per section.
@@ -1050,6 +1072,7 @@ is required, the library instance should be listed in the INF scoping
   module, the tools must obtain unique PCD values using the following
   precedence (high to low):
 
+  - Command-line, `--pcd` flags (left most has higher priority)
   - The DSC file's component INF scoping `<Pcds*>` sections
   - The DSC file's `[Pcd*.arch.skuid]` sections
   - The DSC file's `[Pcd*.common.skuid]` sections
diff --git a/8_pre-build_autogen_stage/84_auto-generated_pcd_database_file.md b/8_pre-build_autogen_stage/84_auto-generated_pcd_database_file.md
index d309246..198644b 100644
--- a/8_pre-build_autogen_stage/84_auto-generated_pcd_database_file.md
+++ b/8_pre-build_autogen_stage/84_auto-generated_pcd_database_file.md
@@ -97,8 +97,6 @@ DSC, INF or DEC files.
    only contain `[PcdEx]` and `[PatchPcd]` Sections - if they contain any other
    type of PCD, break the build.
 
-5. Command line cannot be used to set the PCD value.
-
 #### 8.4.1.2 Precedence Rules for PCDs not listed in the DSC or FDF Files:
 
 This subsection covers PCDs that are used by modules listed in the DSC file,
@@ -206,50 +204,56 @@ The rules are listed in order, such that the first match stops any additional
 processing. The following rules apply to Binary modules listed in a platform
 DSC file.
 
-1. PCD assignments are not permitted in the FDF file except through SET
+1. PCD value assignment from command-line using `--pcd` flag takes precedence
+   over all other assignments.
+
+2. PCD assignments are not permitted in the FDF file except through SET
    statements or the automatic assignments from the [FD] section regions.
 
-2. PCD value assignment in a module scoping section take precedence over values
+3. PCD value assignment in a module scoping section take precedence over values
    specified in the global section for PatchableInModule PCDs.
 
-3. PCD value assignment in a global PCD section with an architectural modifier
+4. PCD value assignment in a global PCD section with an architectural modifier
    take precedence over assignments in a global section.
 
-4. PCD value assignment in a global PCD section without an architectural
+5. PCD value assignment in a global PCD section without an architectural
    modifier.
 
-5. The value specified in the Binary INF has the lowest precedence; the DEC
+6. The value specified in the Binary INF has the lowest precedence; the DEC
    file is never used to determine a PCD value for a Binary INF.
 
 The following rules apply to modules listed in a platform DSC file.
 
-1. PCD assignments in an FDF file are positional, with the last value taking
+1. PCD value assignment from command-line using `--pcd` flag takes precedence
+   over all other assignments.
+
+2. PCD assignments in an FDF file are positional, with the last value taking
    precedence over previous assignments in the FDF file.
 
-2. A PCD assignment in an FDF file takes precedence over PCD values assigned in
+3. A PCD assignment in an FDF file takes precedence over PCD values assigned in
    the DSC file's module scoping section.
 
-3. A PCD value of an entry listed in a module scoping section take precedence
+4. A PCD value of an entry listed in a module scoping section take precedence
    over the PCD value listed in a global section that has an architectural
    modifier in the DSC file.
 
-4. A PCD value of an entry listed in a global section that has an architectural
+5. A PCD value of an entry listed in a global section that has an architectural
    modifier takes precedence over the PCD value listed in a global section
    without an architectural modifier in the DSC file.
 
-5. A PCD value of an entry listed in a global section without architectural
+6. A PCD value of an entry listed in a global section without architectural
    modifiers in the DSC file takes precedence over the PCD value listed in an
    INF file in a section with an architectural modifier.
 
-6. A PCD value of an entry listed in an INF file section with an architectural
+7. A PCD value of an entry listed in an INF file section with an architectural
    modifier takes precedence over an entry listed in an INF file section
    without an architectural modifier.
 
-7. A PCD value of an entry listed in an INF file section without an
+8. A PCD value of an entry listed in an INF file section without an
    architectural modifier takes precedence over a PCD value listed in a DEC
    file in a section with an architectural modifier.
 
-8. A PCD value of an entry listed in a DEC file section with an architectural
+9. A PCD value of an entry listed in a DEC file section with an architectural
    modifier takes precedence over a PCD value listed in a DEC file in a section
    without an architectural modifier.
 
diff --git a/README.md b/README.md
index 89578d0..f3c56c2 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                                                                                                                                                                                                                                                            |               |
+|            | [#480](https://bugzilla.tianocore.org/show_bug.cgi?id=480) Build spec: add description for Override PCD value on the command line                                                                                                                                                                                                                                   |               |
diff --git a/appendix_d_buildexe_command/d4_usage.md b/appendix_d_buildexe_command/d4_usage.md
index c262f1a..739270f 100644
--- a/appendix_d_buildexe_command/d4_usage.md
+++ b/appendix_d_buildexe_command/d4_usage.md
@@ -112,6 +112,7 @@ Options:
   --conf=CONFDIRECTORY  Specify the customized Conf directory.
   --check-usage         Check usage content of entries listed in INF file.
   --ignore-sources      Focus to a binary build and ignore all source files
+  --pcd=OPTIONPCD       Set PCD value by command line. Format: "PcdName=Value"
 ```
 
 ### D.4.1 Debug Levels
-- 
2.6.3.windows.1

Re: [edk2-BuildSpecification PATCH V2 0/2] Add --pcd flag to override PCD values on command line

[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:57 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 V2 0/2] Add --pcd flag to override PCD values on command line

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

GitHub branch for review:

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

GitHub word diff view of the patches in this series:

* [1/2] https://github.com/mdkinney/edk2-BuildSpecification/commit/53408b682ae7e31a4a98e96fb6ed3e9843605dd2?w=1
* [2/2] https://github.com/mdkinney/edk2-BuildSpecification/commit/9dd3bf48cbdfc0ace23141127b2b471e58d59b53?w=1

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 (2):
  Clean up minor formatting issues
  Add --pcd flag to override PCD values on command line

 .../43_pre-build_stage_overview.md                 | 35 ++++++++++----------
 .../45_post-build_stage.md                         | 12 +++----
 .../82_auto-generation_process.md                  | 37 ++++++++++++++++++----
 .../84_auto-generated_pcd_database_file.md         | 34 +++++++++++---------
 .../87_generated_asbuilt_inf_files.md              |  2 +-
 README.md                                          |  1 +
 appendix_d_buildexe_command/d4_usage.md            |  1 +
 7 files changed, 75 insertions(+), 47 deletions(-)

-- 
2.6.3.windows.1