Re: [Patch V2] DEC 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] DEC 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>
>---
> 3_edk_ii_dec_file_format/310_pcd_sections.md       | 14 ++--
> .../32_package_declaration_dec_definitions.md      | 74
>++++++++++++++++++----
> 2 files changed, 67 insertions(+), 21 deletions(-)
>
>diff --git a/3_edk_ii_dec_file_format/310_pcd_sections.md
>b/3_edk_ii_dec_file_format/310_pcd_sections.md
>index 488f17f..36c32ff 100644
>--- a/3_edk_ii_dec_file_format/310_pcd_sections.md
>+++ b/3_edk_ii_dec_file_format/310_pcd_sections.md
>@@ -113,24 +113,24 @@ PCDs listed in `PcdsFeatureFlag` sections must only
>be listed in
>                       [<TS> <Prompt>]
>                       [<DoxComment>] <PcdEntry>
> <PcdEntry>        ::= <TS> {<PcdBool>} {<PcdNumEntry>} {<PcdPtr>}
> <PcdNumEntry>     ::= {<Pcd8>} {<Pcd16>} {<Pcd32>} {<Pcd64>}
> <PcdBool>         ::= <PcdName> <FS> <BoolPcd> <FS> <Token> <CbOrEol>
>-<BoolPcd>         ::= <BoolType> <FS> "BOOLEAN"
>+<BoolPcd>         ::= <Boolean> <FS> "BOOLEAN"
> <CbOrEol>         ::= {<CommentBlock>} {<EOL>}
> <Pcd8>            ::= <PcdName> <FS> <PcdUint8> <FS> <Token> <CbOrEol>
>-<PcdUint8>        ::= <NumValUint8> <FS> "UINT8"
>+<PcdUint8>        ::= {<NumValUint8>} {<Expression>} <FS> "UINT8"
> <Pcd16>           ::= <PcdName> <FS> <PcdUint16> <FS> <Token> <CbOrEol>
>-<PcdUint16>       ::= <NumValUint16> <FS> "UINT16"
>+<PcdUint16>       ::= {<NumValUint16>} {<Expression>} <FS> "UINT16"
> <Pcd32>           ::= <PcdName> <FS> <PcdUint32> <FS> <Token> <CbOrEol>
>-<PcdUint32>       ::= <NumValUint32> <FS> "UINT32"
>+<PcdUint32>       ::= {<NumValUint32>} {<Expression>} <FS> "UINT32"
> <Pcd64>           ::= <PcdName> <FS> <PcdUint64> <FS> <Token> <CbOrEol>
>-<PcdUint64>       ::= <NumValUint64> <FS> "UINT64"
>+<PcdUint64>       ::= {<NumValUint64>} {<Expression>} <FS> "UINT64"
> <PcdPtr>          ::= <PcdName> <FS> <PcdPtrVal> <FS> <Token> <CbOrEol>
> <PcdPtrVal>       ::= <PtrVal> <FS> "VOID*"
>-<PtrVal>          ::= {<CString>} {<CArray>}
>-<Token>           ::= <NumValUint32>
>+<PtrVal>          ::= {<StringVal>} {<Expression>}
>+<Token>           ::= {<LongNum>} {<UINT32>}
> <DoxComment>      ::= <TS> {<Range>+} {<List>} {<Express>+}
> <Prompt>          ::= "#" <TS> "@Prompt <MTS> <AsciiString> <EOL>
> <Range>           ::= "#" <TS> "@ValidRange" <TS> <ERangeValues> <EOL>
> <ERangeValues>    ::= [<ErrorCode> <TS>] <RangeValues>
> <List>            ::= "#" <TS> "@ValidList" <TS> <EValidValueList> <EOL>
>diff --git
>a/3_edk_ii_dec_file_format/32_package_declaration_dec_definitions.md
>b/3_edk_ii_dec_file_format/32_package_declaration_dec_definitions.md
>index 8e473f2..c701603 100644
>--- a/3_edk_ii_dec_file_format/32_package_declaration_dec_definitions.md
>+++
>b/3_edk_ii_dec_file_format/32_package_declaration_dec_definitions.md
>@@ -86,15 +86,16 @@ DEC file (for example, `<Expression>` statements are
>not permitted).
> <Digit>               ::= (0-9)
> <NonDigit>            ::= (a-zA-Z_)
> <Identifier>          ::= <NonDigit> <Chars>*
> <CName>               ::= <Identifier> # A valid C variable name.
> <AsciiChars>          ::= (0x21 - 0x7E)
>-<CChars>              ::= [{0x21} {(0x23 - 0x5B)} {(0x5D - 0x7E)}
>-                          {<EscapeSequence>}]*
>+<CChars>              ::= [{0x21} {(0x23 - 0x26)} {(0x28 - 0x5B)}
>+                          {(0x5D - 0x7E)} {<EscapeSequence>}]*
> <DblQuote>            ::= 0x22
>+<SglQuote>            ::= 0x27
> <EscapeSequence>      ::= "\" {"n"} {"t"} {"f"} {"r"} {"b"} {"0"} {"\"}
>-                          {<DblQuote>}
>+                          {<DblQuote>} {<SglQuote>}
> <TabSpace>            ::= {<Tab>} {<Space>}
> <TS>                  ::= <TabSpace>*
> <MTS>                 ::= <TabSpace>+
> <Tab>                 ::= 0x09
> <Space>               ::= 0x20
>@@ -112,15 +113,16 @@ DEC file (for example, `<Expression>` statements are
>not permitted).
> <AsciiString>         ::= [ <TS>* <AsciiChars>* ]*
> <EmptyString>         ::= <DblQuote><DblQuote>
> <CFlags>              ::= <AsciiString>
> <PrintChars>          ::= {<TS>} {<CChars>}
> <QuotedString>        ::= <DblQuote> <PrintChars>* <DblQuote>
>-<CString>             ::= ["L"] <QuotedString>
>+<SglQuotedString>     ::= <SglQuote> <PrintChars>* <SglQuote>
>+<CString>             ::= {<QuotedString>} {<SglQuotedString>}
> <NormalizedString>    ::= <DblQuote> [{<Word>} {<Space>}]+ <DblQuote>
> <GlobalComment>       ::= <WS> "#" [<TS> <AsciiString>] <EOL>+
> <Comment>             ::= "#" <TS> <AsciiString> <EOL>+
>-<UnicodeString>       ::= "L" <QuotedString>
>+<UnicodeString>       ::= "L" {<QuotedString>} {<SglQuotedString>}
> <HexDigit>            ::= (a-fA-F0-9)
> <HexByte>             ::= {"0x"} {"0X"} [<HexDigit>] <HexDigit>
> <HexNumber>           ::= {"0x"} {"0X"} <HexDigit>+
> <HexVersion>          ::= "0x" [0]* <Major> <Minor>
> <Major>               ::= <HexDigit>? <HexDigit>? <HexDigit>?
>@@ -157,11 +159,12 @@ DEC file (for example, `<Expression>` statements are
>not permitted).
> <Number>              ::= {<Integer>} {<HexNumber>}
> <TRUE>                ::= {"TRUE"} {"true"} {"True"} {"0x1"}
>                           {"0x01"} {"1"}
> <FALSE>               ::= {"FALSE"} {"false"} {"False"} {"0x0"}
>                           {"0x00"} {"0"}
>-<BoolType>            ::= {<TRUE>} {<FALSE>}
>+<BoolVal>             ::= {<TRUE>} {<FALSE>}
>+<BoolType>            ::= {<BoolVal>} {"{"<BoolVal>"}"}
> <MACRO>               ::= (A-Z)(A-Z0-9_)*
> <MACROVAL>            ::= "$(" <MACRO> ")"
> <PcdName>             ::= <TokenSpaceGuidCName> "." <PcdCName>
> <PcdCName>            ::= <CName>
> <TokenSpaceGuidCName> ::= <CName>
>@@ -182,14 +185,49 @@ DEC file (for example, `<Expression>` statements are
>not permitted).
>                           <HexDigit> <HexDigit>
> <ShortNum>            ::= (0-255)
> <IntNum>              ::= (0-65535)
> <LongNum>             ::= (0-4294967295)
> <LongLongNum>         ::= (0-18446744073709551615)
>-<NumValUint8>         ::= {<ShortNum>} {<UINT8>}
>-<NumValUint16>        ::= {<IntNum>} {<UINT16>}
>-<NumValUint32>        ::= {<LongNum>} {<UINT32>}
>-<NumValUint64>        ::= {<LongLongNum>} {<UINT64>}
>+<ValUint8>            ::= {<ShortNum>} {<UINT8>} {<BoolVal>}
>+                          {<CString>} {<UnicodeString>}
>+<ValUint16>           ::= {<IntNum>} {<UINT16>} {<BoolVal>}
>+                          {<CString>} {<UnicodeString>}
>+<ValUint32>           ::= {<LongNum>} {<UINT32>} {<BoolVal>}
>+                          {<CString>} {<UnicodeString>}
>+<ValUint64>           ::= {<LongLongNum>} {<UINT64>} {<BoolVal>}
>+                          {<CString>} {<UnicodeString>}
>+<NumValUint8>         ::= {<ValUint8>} {"{"<ValUint8>"}"}
>+<NumValUint16>        ::= {<ValUint16>}
>+                          {"{"<ValUint16> [<CommaSpace> <ValUint16>]*"}"}
>+<NumValUint32>        ::= {<ValUint32>}
>+                          {"{"<ValUint32> [<CommaSpace> <ValUint32>]*"}"}
>+<NumValUint64>        ::= {<ValUint64>}
>+                          {"{"<ValUint64> [<CommaSpace> <ValUint64>]*"}"}
>+<StringVal>           ::= {<UnicodeString>} {<CString>} {<Array>}
>+<Array>               ::= "{" {<Array>} {[<Lable>] <ArrayVal>
>+                           [<CommaSpace> [<Lable>] <ArrayVal>]* } "}"
>+<ArrayVal>            ::= {<Num8Array>} {<GuidStr>} {<DevicePath>}
>+<NonNumType>          ::= {<BoolVal>}{<UnicodeString>} {<CString>}
>+                          {<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>}
>+<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> ")"
> <ModuleType>          ::= {"BASE"} {"SEC"} {"PEI_CORE"} {"PEIM"}
>                           {"DXE_CORE"} {"DXE_DRIVER"} {"SMM_CORE"}
>                           {"DXE_RUNTIME_DRIVER"} {"DXE_SAL_DRIVER"}
>                           {"DXE_SMM_DRIVER"} {"UEFI_DRIVER"}
>                           {"UEFI_APPLICATION"} {"USER_DEFINED"}
>@@ -200,10 +238,18 @@ DEC file (for example, `<Expression>` statements are
>not permitted).
> <OA>                  ::= (a-zA-Z)(a-zA-Z0-9)*
> <arch>                ::= {"IA32"} {"X64"} {"IPF"} {"EBC"} {<OA>}
> ```
>
> **********
>+**Note:** When using CString, UnicodeString or byte array format as
>+UINT8/UINT16/UINT32/UINT64 values, please make sure they fit in the
>+target type's size, otherwise tool would report failure.
>+**********
>+**Note:** LABEL() macro in byte arrays to tag the byte offset of a
>+location in a byte array. OFFSET_OF() macro in byte arrays that returns
>+the byte offset of a LABEL() declared in a byte array.
>+**********
> **Note:** When using the characters "|" or "||" in an expression, the
> expression must be encapsulated in open "(" and close ")" parenthesis.
> **********
> **Note:** Comments may appear anywhere within a DEC file, provided they
>follow
> the rules that a comment may not be enclosed within Section headers, and
>that
>@@ -233,14 +279,14 @@ must cause a build break.
> **********
>
> **_UnicodeString_**
>
> When the `<UnicodeString>` element (these characters are string literals as
>-defined by the C99 specification: L"string", not actual Unicode characters) is
>-included in a value, the build tools may be required to expand the ASCII string
>-between the quotation marks into a valid UCS-2 character format string. The
>-build tools parser must treat all content between the field separators
>+defined by the C99 specification: L"string"/L'string', not actual Unicode
>+characters) is included in a value, the build tools may be required to expand
>+the ASCII string between the quotation marks into a valid UCS-2 character
>format
>+string. The build tools parser must treat all content between the field
>separators
> (excluding white space characters around the field separators) as ASCII literal
> content when generating the AutoGen.c and AutoGen.h files.
>
> **_Comments_**
>
>--
>2.6.1.windows.1