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

[Michael Kinney <michael.d.kinney@intel.com>]

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..57c8134 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 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..ea0078b 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 assignmenment 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 assignmenment 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