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

[Yonghong Zhu <yonghong.zhu@intel.com>]

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