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

[Laszlo Ersek <lersek@redhat.com>]

On 04/11/17 17:16, Liming Gao wrote:
> 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. 

My only request at this point is to please file two BZs:
- one for the feature itself (apparently the requirement exists already),
- another one for the DEC spec, to document the feature.

Thank you,
Laszlo

> 
> 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
>