Re: [Patch V2] Build spec: Add flexible PCD value format into spec

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

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

>-----Original Message-----
>From: Zhu, Yonghong
>Sent: Wednesday, February 07, 2018 8:36 PM
>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 V2] Build spec: Add flexible PCD value format into spec
>
>V2: update EBNF for Array format.
>
>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>
>---
> 7_build_environment/73_guided_tools.md             |  8 +--
> .../82_auto-generation_process.md                  | 18 +++---
> appendix_d_buildexe_command/d4_usage.md            | 72
>+++++++++++++++++++---
> 3 files changed, 77 insertions(+), 21 deletions(-)
>
>diff --git a/7_build_environment/73_guided_tools.md
>b/7_build_environment/73_guided_tools.md
>index a8881d3..50119f1 100644
>--- a/7_build_environment/73_guided_tools.md
>+++ b/7_build_environment/73_guided_tools.md
>@@ -119,21 +119,21 @@ file required by the build system is provided in the
>appendix, VPD Tool.
>     ```
>
>   If using automatic offset feature, the build tools byte-align numeric values,
>   while `VOID*` PCD types will be aligned using the following rules:
>
>-  * ASCII strings, "string", will be byte aligned.
>-  * Unicode strings, L"string" will be two-byte aligned.
>+  * ASCII strings, "string" or 'string', will be byte aligned.
>+  * Unicode strings, L"string" or L'string' will be two-byte aligned.
>   * Byte arrays, {0x00, 0x01} will be 8-byte aligned.
>
>   If the developer manually assigns offset values in the DSC file, the developer
>   must follow the same rules.
>
>   **********
>   **Note:** If a developer manually sets the offset of a `VOID*` PCD with
>-  Unicode string, L"string", style to a value that is not 2-byte aligned, then
>-  an error is generated and the build halts.
>+  Unicode string, L"string"/L'string' style to a value that is not 2-byte aligned,
>+  then an error is generated and the build halts.
>   **********
>   **Note:** If a developer manually sets the offset of a `VOID*` PCD with
>byte
>   array {} style to a value that is not 8-byte aligned, then a warning is
>   generated, but the build will continue.
>   **********
>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 f610185..5a950d7 100644
>--- a/8_pre-build_autogen_stage/82_auto-generation_process.md
>+++ b/8_pre-build_autogen_stage/82_auto-generation_process.md
>@@ -875,41 +875,41 @@ 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:
>+`<Value>` supports the following syntax:
>
>-* ASCII string value for a `VOID*` PCD
>+* ASCII string value for a PCD
>
>   `--pcd  [<TokenSpaceGuidCname>.]<PcdCName>="String"`
>+  `--pcd  [<TokenSpaceGuidCname>.]<PcdCName>='String'`
>
>-*  Unicode string value for a `VOID*` PCD
>+* Unicode string value for a PCD
>
>   `--pcd  [<TokenSpaceGuidCname>.]<PcdCName>=L"String"`
>+  `--pcd  [<TokenSpaceGuidCname>.]<PcdCName>=L'String'`
>
>-*  Byte array value for a `VOID*` PCD
>+* Byte array value for a 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.
> **********
>-**Caution:** Dynamic and DynamicEx `VOID*` VPD PCD array values must be
>hex byte
>-arrays. Using a Registry or C format GUID value in the value field of a `VOID*`
>-VPD PCD is not permitted.
>-**********
>
> If the maximum size of a `VOID*` PCD is not specified in the DSC file, then the
> maximum size is calculated based on the largest size of 1) the string or array
> in the DSC file, 2) the string or array in the INF file and 3) the string or
> array in the DEC file. If the value is a quoted text string, the size of the
> string will be incremented by one to handle string termination. If the quoted
> string is preceded by L, as in `L"This is a string"`, then the size of the string
> will be incremented by two to handle unicode string termination. If the value
>-is a byte array, then the size of the byte array is not modified.
>+is a byte array, then the size of the byte array is not modified. If the value is
>+a single quoted string, as in 'string' or L'string', the size of the string doesn't
>+need to include string null termination character.
>
> For example, if the string in the DSC file is `L"DSC Length"`, the INF file has
> `L"Module Length"` and the DEC file declares the default as `L"Length"`, then
> the maximum size that will be allocated for this PCD will be 28 bytes (`
> L"Module Length"` 26 bytes, 2 bytes for null termination character).
>diff --git a/appendix_d_buildexe_command/d4_usage.md
>b/appendix_d_buildexe_command/d4_usage.md
>index c901266..57d2656 100644
>--- a/appendix_d_buildexe_command/d4_usage.md
>+++ b/appendix_d_buildexe_command/d4_usage.md
>@@ -195,24 +195,80 @@ precedence over PCD provided in DSC, FDF, INF, and
>DEC files.
>
> ```c
> <PcdOption>       ::= "--pcd" <PcdName> ["=" <PcdValue>] <MTS>
> <SP>              ::= 0x20
> <MTS>             ::= <SP>+
>+<TS>              ::= <SP>*
>+<CommaSpace>      ::= "," <SP>*
>+<HexDigit>        ::= (a-fA-F0-9)
>+<CName>           ::= A valid C variable name.
> <PcdName>         ::= [<TokenSpaceCName> "."] <PcdCName>
> <TokenSpaceCName> ::= C Variable Name of the Token Space GUID
> <PcdCName>        ::= C Variable Name of the PCD
>-<PcdValue>        ::= {<Boolean>} {<Number>} {<CString>} {<CArray>}
>+<PcdValue>        ::= {<Boolean>} {<Number>} {<String>} {<Array>}
> <Number>          ::= {<Integer>} {<HexNumber>}
> <Integer>         ::= {(0-9)} {(1-9)(0-9)+}
> <HexNumber>       ::= {"0x"} {"0X"} (a-fA-F0-9){1,16}
> <Boolean>         ::= {<True>} {<False>}
> <True>            ::= {"TRUE"} {"True"} {"true"} {"1"} {"0x1"} {"0x01"}
> <False>           ::= {"FALSE"} {"False"} {"false"} {"0"} {"0x0"} {"0x00"}
>-<CString>         ::= ["L"] <QuotedString>
>-<QuotedString>    ::= <DblQuote> <CChars>* <DblQuote>
>+<String>          ::= ["L"] {<QuotedString>} {<SglQuotedString>}
>+<SglQuotedString> ::= <SglQuote> <PrintChars>* <SglQuote>
>+<QuotedString>    ::= <DblQuote> <PrintChars>* <DblQuote>
>+<PrintChars>      ::= {<TS>} {<CChars>}
> <DblQuote>        ::= 0x22
>-<CChars>          ::= {0x21} {(0x23 - 0x5B)} {(0x5D - 0x7E)} {<EscapeSequence>}
>-<EscapeSequence>  ::= "\" {"n"} {"t"} {"f"} {"r"} {"b"} {"0"} {"\"} {0x22}
>-<CArray>          ::= "H" "{" <NList> "}"
>-<NList>           ::= <HexByte> ["," <HexByte>]*
>-<HexByte>         ::= {"0x"} {"0X"} (a-fA-F0-9){1,2}
>+<SglQuote>        ::= 0x27
>+<CChars>          ::= {0x21} {(0x23 - 0x26)} {(0x28 - 0x5B)} {(0x5D - 0x7E)}
>+                      {<EscapeSequence>}
>+<EscapeSequence>  ::= "\" {"n"} {"t"} {"f"} {"r"} {"b"} {"0"} {"\"}
>+                      {<DblQuote>} {<SglQuote>}
>+<Array>           ::= "H" "{"[<Lable>] <ArrayVal>
>+                      [<CommaSpace> [<Lable>] <ArrayVal>]*"}"
>+<ArrayVal>        ::= {<Num8Array>} {<GuidStr>} {<DevicePath>}
>+<ShortNum>        ::= (0-255)
>+<IntNum>          ::= (0-65535)
>+<LongNum>         ::= (0-4294967295)
>+<LongLongNum>     ::= (0-18446744073709551615)
>+<UINT8>           ::= {"0x"} {"0X"} (a-fA-F0-9){1,2}
>+<UINT16>          ::= {"0x"} {"0X"} (a-fA-F0-9){1,4}
>+<UINT32>          ::= {"0x"} {"0X"} (a-fA-F0-9){1,8}
>+<UINT64>          ::= <HexNumber>
>+<NonNumType>      ::= {<Boolean>} {<String>} {<Offset>} {<UintMac>}
>+<Num8Array>       ::= {<NonNumType>} {<ShortNum>} {<UINT8>}
>+<Num16Array>      ::= {<NonNumType>} {<IntNum>} {<UINT16>}
>+<Num32Array>      ::= {<NonNumType>} {<LongNum>} {<UINT32>}
>+<Num64Array>      ::= {<NonNumType>} {<LongLongNum>} {<UINT64>}
>+<GuidStr>         ::= "GUID(" <GuidVal> ")"
>+<GuidVal>         ::= {<DblQuote> <RegistryFormatGUID> <DblQuote>}
>+                      {<CFormatGUID>} {<CName>}
>+<RegistryFormatGUID>::= <RHex8> "-" <RHex4> "-" <RHex4> "-" <RHex4> "-
>"
>+                      <RHex12>
>+<RHex4>           ::= <HexDigit> <HexDigit> <HexDigit> <HexDigit>
>+<RHex8>           ::= <RHex4> <RHex4>
>+<RHex12>          ::= <RHex4> <RHex4> <RHex4>
>+<RawH2>           ::= <HexDigit>? <HexDigit>
>+<RawH4>           ::= <HexDigit>? <HexDigit>? <HexDigit>? <HexDigit>
>+<OptRawH4>        ::= <HexDigit>? <HexDigit>? <HexDigit>? <HexDigit>?
>+<Hex2>            ::= {"0x"} {"0X"} <RawH2>
>+<Hex4>            ::= {"0x"} {"0X"} <RawH4>
>+<Hex8>            ::= {"0x"} {"0X"} <OptRawH4> <RawH4>
>+<Hex12>           ::= {"0x"} {"0X"} <OptRawH4> <OptRawH4> <RawH4>
>+<Hex16>           ::= {"0x"} {"0X"} <OptRawH4> <OptRawH4> <OptRawH4>
>+                      <RawH4>
>+<CFormatGUID>     ::= "{" <Hex8> <CommaSpace> <Hex4> <CommaSpace>
>+                      <Hex4> <CommaSpace> "{"
>+                      <Hex2> <CommaSpace> <Hex2> <CommaSpace>
>+                      <Hex2> <CommaSpace> <Hex2> <CommaSpace>
>+                      <Hex2> <CommaSpace> <Hex2> <CommaSpace>
>+                      <Hex2> <CommaSpace> <Hex2> "}" "}"
>+<DevicePath>      ::= "DEVICE_PATH(" <DevicePathStr> ")"
>+<DevicePathStr>   ::= A double quoted string that follow the device path
>+                      as string format defined in UEFI Specification 2.6
>+                      Section 9.6
>+<UintMac>         ::= {<Uint8Mac>} {<Uint16Mac>} {<Uint32Mac>}
>{<Uint64Mac>}
>+<Uint8Mac>        ::= "UINT8(" <Num8Array> ")"
>+<Uint16Mac>       ::= "UINT16(" <Num16Array> ")"
>+<Uint32Mac>       ::= "UINT32(" <Num32Array> ")"
>+<Uint64Mac>       ::= "UINT64(" <Num64Array> ")"
>+<Lable>           ::= "LABEL(" <CName> ")"
>+<Offset>          ::= "OFFSET_OF(" <CName> ")"
> ```
>--
>2.6.1.windows.1