Re: [edk2-VfrSpecification PATCH V2] Add union data type and bit fields in VFR Data Struct Definition

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

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

>-----Original Message-----
>From: Bi, Dandan
>Sent: Friday, September 15, 2017 3:04 PM
>To: edk2-devel@lists.01.org
>Cc: Dong, Eric <eric.dong@intel.com>; Gao, Liming <liming.gao@intel.com>
>Subject: [edk2-VfrSpecification PATCH V2] Add union data type and bit fields
>in VFR Data Struct Definition
>
>V2: Add a note in the doc:for the bit field, the number of
>the bit width could not exceed 32.
>
>https://bugzilla.tianocore.org/show_bug.cgi?id=683
>
>Cc: Eric Dong <eric.dong@intel.com>
>Cc: Liming Gao <liming.gao@intel.com>
>Contributed-under: TianoCore Contribution Agreement 1.1
>Signed-off-by: Dandan Bi <dandan.bi@intel.com>
>Reviewed-by:  Eric Dong <eric.dong@intel.com>
>---
> .../23_vfr_data_struct_definition.md               | 40
>++++++++++++++++++++++
> README.md                                          |  1 +
> 2 files changed, 41 insertions(+)
>
>diff --git a/2_vfr_description_in_bnf/23_vfr_data_struct_definition.md
>b/2_vfr_description_in_bnf/23_vfr_data_struct_definition.md
>index 6d6730d..2769d4f 100644
>--- a/2_vfr_description_in_bnf/23_vfr_data_struct_definition.md
>+++ b/2_vfr_description_in_bnf/23_vfr_data_struct_definition.md
>@@ -36,10 +36,16 @@ vfrDataStructDefinition ::=
>  { "typedef" } "struct"
>  { StringIdentifier }
>  "{" vfrDataStructFields "}"
>  { StringIdentifier } ";"
>
>+vfrDataStructDefinition ::=
>+ { "typedef" } "union"
>+ { StringIdentifier }
>+ "{" vfrDataStructFields "}"
>+ { StringIdentifier } ";"
>+
> vfrDataStructFields ::=
>   (
>       dataStructField64
>     | dataStructField32
>     | dataStructField16
>@@ -48,10 +54,14 @@ vfrDataStructFields ::=
>     | dataStructFieldString
>     | dataStructFieldDate
>     | dataStructFieldTime
>     | dataStructFieldRef
>     | dataStructFieldUser
>+    | dataStructBitField64
>+    | dataStructBitField32
>+    | dataStructBitField16
>+    | dataStructBitField8
>   )*
>
> dataStructField64 ::=
>   "UINT64"
>   StringIdentifier { "[" Number "]" } ";"
>@@ -89,29 +99,59 @@ dataStructFieldRef ::=
>   StringIdentifier { "[" Number "]" } ";"
>
> dataStructFieldUser ::=
>   StringIdentifier
>   StringIdentifier { "[" Number "]" } ";"
>+
>+dataStructBitField64 ::=
>+  "UINT64"
>+  { StringIdentifier } ":" Number ";"
>+
>+dataStructBitField32 ::=
>+  "UINT32"
>+  { StringIdentifier } ":" Number ";"
>+
>+dataStructBitField16 ::=
>+  "UINT16"
>+  { StringIdentifier } ":" Number ";"
>+
>+dataStructBitField8 ::=
>+  "UINT8"
>+  { StringIdentifier } ":" Number ";"
> ```
>
> #### BEHAVIORS AND RESTRICTIONS
>
> The data structure definition is in C-style language. `enum` type is not
> supported. The keyword of the fields' type must be a user defined data
> structure or one of these types: `UINT8`, `UINT16`, `UINT32`, `UINT64`,
> `BOOLEAN`, `EFI_STRING_ID`, `EFI_HII_DATA`, `EFI_HII_TIME EFI_HII_REF`,
>and at
> most one-dimensional array is permitted.
>+Note: for the bit field, the number of the bit width could not exceed 32.
>
> #### Example
>
> ```c
> typedef struct {
>   UINT8 mU8;
>   UINT16 mU16;
>   UINT32 mU32[10];
>   UINT64 mU64;
> } MyData;
>+
>+typedef union {
>+  UINT16   Field16;
>+  UINT8    Field8;
>+} MyUnionData;
>+
>+typedef struct {
>+  UINT16   Field16;
>+  UINT8    MyBits1 : 1;
>+  UINT8    MyBits2 : 3;
>+  UINT8    MyBits3 : 3;
>+  UINT16   MyBits4 : 4;
>+} MyBitsData;
> ```
>
> **Unsupported Example of enum type:**
>
> ```c
>diff --git a/README.md b/README.md
>index 888eb81..0a596eb 100644
>--- a/README.md
>+++ b/README.md
>@@ -89,5 +89,6 @@ Copyright (c) 2007-2017, Intel Corporation. All rights
>reserved.
> | 1.60     | Update syntax for goto, image, questionref and constant value
>opcodes, correct CALLBACK flag to INTEREACTIVE, correct help string for old
>syntax date/time example, and add examples for expression opcodes.   |
>December 1, 2011  |
> | 1.70     | Clarify restriction that enum type and struct data filed with more
>than one dimensions array are not supported.
>| May 18, 2012      |
> | 1.80     | Add syntax for warningif opcode, update definition for name/value
>varstore and subtitle opcode, update referenced UEFI spec version info.
>| Jan 14, 2014      |
> | 1.90     | Correct sample code for catenate/match/cond opcode. Add syntax
>for match2 opcode. Add sample code to show the buffer type constant value
>for orderedlist opcode and default opcode.                            | July 2, 2015      |
> | 1.91     | Convert to Gitbook
>| April 2017        |
>+|          | [#683](https://bugzilla.tianocore.org/show_bug.cgi?id=683) VFR
>Spec: Add union data type and bit fields in VFR Data Struct Definition
>|                   |
>--
>1.9.5.msysgit.1