[RFC 0/3] Structure PCD value assignment in DEC/DSC

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

Requirment: Map VOID* PCD to C structure
1. When PCD is configured as DynamicHii, it will be map to one EFI variable. If PCD is VOID*, it can map to the 
whole EFI variable. Most EFI variable data are defined as C structure. 
2. Some PCDs are designed as C style structure, such as gEfiMdeModulePkgTokenSpaceGuid.PcdPciSerialParameters.

Current limitation:
1. VOID* PCD Value must be byte array. Its value is hard to be specified. 
2. If single PCD is defined to map one field in structure, its offset and width will be required when this PCD 
is configured as DynamicHii or DynamicVpd. If the structure is big, it will require lots of PCDs to map its 
each field. If the structure has the bit field, its bit field can't match PCD. 

Proposal:
Enhance EDKII Build system to support VOID* PCD be mapped to C structure in DEC or DSC. PCD value can be specified
by structure field as C language style in DEC and DSC. Then, its value will be converted to byte array and assigned
to VOID* PCD. This is a pure build enhancement, and no change in PCD driver.
1. New syntax in DEC and DSC defines PCD with C structure. 
  a. PCD Data type will be C structure name.
  b. C structure header file and the dependent packages are required to be listed. 
  c. Example in DEC [PcdsFixedAtBuild] section:
    gStructuredPcdPkgTokenSpaceGuid.PcdTest|{0xFF}|TEST|0x00010080 {
        <HeaderFile>
          Guid/Test.h
        <Packages>
          MdePkg/MdePkg.dec
          MdeModulePkg/MdeModulePkg.dec
    }
2. Set the value to the structure fields like normal PCD in DEC/DSC/FDF. 
  a. If the field value is not specified, its default value will be zero. 
  b. Example in DEC/DSC [PcdsFixedAtBuild] section:
    gStructuredPcdPkgTokenSpaceGuid.PcdTest.Bool|TRUE
    gStructuredPcdPkgTokenSpaceGuid.PcdTest.Array[1].Foo|"ABC"
    gStructuredPcdPkgTokenSpaceGuid.PcdTest.C|0xFEDC
    gStructuredPcdPkgTokenSpaceGuid.PcdTest.D|2222
3. Pre AutoGen phase, Build tool will prepare the value for structure PCD. 
  a. Generate C file (name as pcdc file) and its Makefile to include PCD value initialization. 
    i. Parse PCD field values in DEC/DSC/FDF to generate pcdc file.
    ii. Developer provides their pcdc files to customize PCD value in one module INF.
  b. Compile C file to the executable tool like BaseTools C tools.
  c. Run the executable file to output the byte array PCD value. 
  d. Build tool gets the byte array PCD value and generate AutoGen code, continue to normal edk2 build process. 
4. Pcdc file will include the different functions to initialize the different PCD value on the different SKU 
  a. BaseTools CommonLib adds the generic APIs to parse Args, Get/Set PCD value.
  b. Pcdc file is compiled and run by Build tool, user doesn't need aware it.
5. Report
  a. Error report will point to the specified value in DEC or DSC when the value can't be assigned to structure field.
  b. Build Report will print Structure PCD value with byte array and field value both. 
6. C Structure requirement
  a. Structure field data type can't be VOID* or UINTN. its size must be same at the crossing ARCHs. 
  b. Structure field can be bits, union, nest structure, structure array, enum, pack, unpack. 
  c. Structure field value can be MACRO, Enum or constant value. 

Patch:
This patches add TestPkg to show StructurePcd Value Assignment usage in DEC and DSC.

Python StructuredPcdValueGenerator.py is added to show structure PCD usage. Its logic will be 
integrated into BaseTools later. This script bases on Package dec and Package dsc 
to convert structure PCD value to byte array. It depends on BaseTools C source CommonLib.
Before run this script, BaseTools are required to be compiled first. This script will
generate $(WORKSPACE)\Build\PcdValueInit\PcdValueInit.c with the structure PCD field value,
and generate $(WORKSPACE)\Build\PcdValueInit\Makefile to compile it to the executable file. 
It also generates $(WORKSPACE)\Build\PcdValueInit\Input.txt to include the initial PCD value
from its declartion in dec file. Last, run the generated executable file with Input.txt, and 
output the final PCD value in $(WORKSPACE)\Build\PcdValueInit\Output.txt.

In Windows:
1. enter into edk2
2. type edksetup.bat --nt32
3. nmake -f BaseTools\Makefile
4. C:\Python27\python.exe TestPkg\StructuredPcdValueGenerator.py -p TestPkg\TestPkg.dec -d TestPkg\TestPkg.dsc

In Linux:
1. enter into edk2
2. . edksetup.sh BaseTools
3. cd BaseTools
4. make
5. cd edk2
6. python TestPkg/StructuredPcdValueGenerator.py -p TestPkg/TestPkg.dec -d TestPkg/TestPkg.dsc

After run StructuredPcdValueGenerator.py, Structure PCD value will output as byte array.

Liming Gao (3):
  BaseTools: Update Makefile to work at absolute path
  BaseTools: Add PcdValueCommon logic into CommonLib
  TestPkg: Show Structure PCD value assignment

 BaseTools/Source/C/Common/GNUmakefile      |   3 +-
 BaseTools/Source/C/Common/Makefile         |   3 +-
 BaseTools/Source/C/Common/PcdValueCommon.c | 601 ++++++++++++++++++++++++
 BaseTools/Source/C/Common/PcdValueCommon.h |  78 ++++
 BaseTools/Source/C/Makefiles/app.makefile  |   2 +-
 BaseTools/Source/C/Makefiles/lib.makefile  |   2 +
 BaseTools/Source/C/Makefiles/ms.app        |   4 +-
 TestPkg/Include/Guid/Test.h                |  31 ++
 TestPkg/StructuredPcdValueGenerator.py     | 702 +++++++++++++++++++++++++++++
 TestPkg/TestPkg.dec                        |  44 ++
 TestPkg/TestPkg.dsc                        |  69 +++
 11 files changed, 1534 insertions(+), 5 deletions(-)
 create mode 100644 BaseTools/Source/C/Common/PcdValueCommon.c
 create mode 100644 BaseTools/Source/C/Common/PcdValueCommon.h
 create mode 100644 TestPkg/Include/Guid/Test.h
 create mode 100644 TestPkg/StructuredPcdValueGenerator.py
 create mode 100644 TestPkg/TestPkg.dec
 create mode 100644 TestPkg/TestPkg.dsc

-- 
2.8.0.windows.1