8.4 Auto-generated PCD Database File

The EDK II code-base provides platform configuration data that can be modified at runtime. The two PCD data types are Dynamic PCDs scoped to only the platform drivers and DynamicEx PCDs, which may be accessed by other modules. There are two drivers, a PEIM and DXE driver that are used to provide access to these configurable items.

Since binary modules may need to add additional DynamicEx PCDs, the EDK II drivers and the EDK II build system create external binary (PeiPcdDataBase.raw and DxePcdDataBase.raw) database files. These files are generated by the build system based on PCDs listed in the FDF and DSC files, as well as from INF files listed in the DSC and FDF files. The files are a union of all of the Dynamic and DynamicEx PCDs found from these EDK II meta-data files. During the ImageGen stage, the files will be put into the FFS file (EFI_SECTION_RAW) for both the PEIM and DXE driver. Each driver has been coded to locate the file. The rule for the PEI_PCD_DRIVER module and DXE_PCD_DRIVER module is integrated into the build system. The EDK II build system limits the offset of Dynamic and DynamicEx PCDs that are defined in the DSC file using the subtype of HII to a UINT16 value.

No special rules are required to add the FFS raw section in the FDF file to process these drivers. Standard PEIM and DXE_DRIVER rules can be specified, as the build system will always insert the database raw sections in to these drivers if the database file exists.

If Dynamic or DynamicEx PCDs are used by the platform and no database file is created by the build, the build tools must break with an appropriate error message.

Table 16 Access Method Section Tags

The FDF file does not have specific sections for setting PCD values. PCD values are either automatically set in the [FD] sections (region offset and region size) or using SET statements.

8.4.1 PCD Rules:

The subsections that follow cover the rules for processing PCDs defined in FDF, DSC, INF or DEC files.

8.4.1.1 General Rules:

1. A FeatureFlag PCD cannot use be listed under any other access method in the DEC file. If a PCD name is listed in an FeatureFlag section, and also in another section type, the build must break.

2. For PCDs using Dynamic or DynamicEx access methods, the PCD must be listed in the DSC file. The build parser must break with an appropriate error message if a Dynamic or DynamicEx PCD is not specified in the DSC.

3. For a given platform build, a PCD can only use one access method. Any INF files in a platform that specifically limit the PCD access method for a given PCD must all list the same access method OR for source INF files only, the list the PCD in a [Pcd] section.

4. BINARY INF files (that do not list files under a [Sources] section) can only contain [PcdEx] and [PatchPcd] Sections - if they contain any other type of PCD, break the build.

5. If a PCD has a Token Space GUID specified in DEC file and the [Guids] section tag contains the Private modifier ([Guids.common.Private] for example), the PCD may only be used by modules in the package containing the DEC file. If a module outside of that package attempts to use the PCD, the build must break with an appropriate error message.

8.4.1.2 Precedence Rules for PCDs not listed in the DSC or FDF Files:

This subsection covers PCDs that are used by modules listed in the DSC file, but the PCD itself is not listed in any PCD section (module scoped or global) within the DSC file. The following general rules are processed in order until one of them is satisfied. If none of these rules can be satisfied, then other rules (below this list) will be tested.

1. If all modules that use a PCD list it in a [Pcd] section and the DEC file declares PcdsFixedAtBuild as a PCD access method, then the build will use PcdsFixedAtBuild for the PCD.

2. If all modules that use a PCD list it in a [Pcd] section and the DEC file declares PcdsPatchableInModule as a PCD access method, then the build will use PcdsPatchableInModule for the PCD.

3. If all modules that use a PCD list it in a [Pcd] section and the DEC file declares PcdsDynamic as a PCD access method, then the build will use PcdsDynamicDefault for the PCD.

4. If all modules that use a PCD list it in a [Pcd] section and the DEC file declares PcdsDynamicEx as a PCD access method, then the build will use PcdsDynamicExDefault for the PCD.

Certain rules in this section assume that the EDK II package creator omitted some entries in the DEC file on purpose. These rules cover the case where a module does not follow the DEC file's access method declarations.

1. PCD access method assignment from Binary INF files take precedence over any access method assignment from Source INF files;

   • If a Binary INF listed only in the FDF file and the PCD access method is listed under a [PatchPcd] section and the Source INF files list the PCD in either [PatchPcd] or [Pcd] sections, then the build system must assign the PCD to use the PcdsPatchableInModule access method for all INF files that use the PCD.

   • If a Binary INF listed only in the FDF file and the PCD access method is listed under a [PcdEx] section and the Source INF files list the PCD in either [PcdEx] or [Pcd] sections, then the build system must assign the PCD to use the PcdsDynamicExDefault access method for all INF files that use the PCD. The PCD must be added to the Platform's PCD Database.

2. When building modules from source INFs, a PCD can only use one access method for all modules in a platform; a PCD cannot use the patch access method in one source module and fixed access method in another source module in the same platform. The build parser must break with an error message if this occurs.

3. Binary modules included in a platform build are permitted to use the PatchableInModule or DynamicEx access methods (the Binary module must specify which of these two methods were used to create the binary module) regardless of the method used for a given PCD in modules built from source. The build supports binary modules that use the same or different PCD access method than the source modules or other binary modules. The build parser must break with an error if a PCD is listed as FixedAtBuild or Dynamic (not DynamicEx) in the Binary INF.

4. If the PCD is listed under different access methods in all source INF files in the platform that use the PCD, the build parser must break with an appropriate error message.

5. If the PCD is listed in a [Pcd] section in all of the source modules using that PCD that are listed in the DSC file, AND the PCD is listed in the DEC file under [PcdsDynamicEx] and/or [PcdsDynamic] and/or [PcdsPatchableInModule] and [PcdsFixedAtBuild] sections, the build must use the PcdsFixedAtBuild access method for this PCD in all source modules in the platform that use this PCD.

6. If the PCD is listed in a [Pcd] section in all of the source modules using that PCD that are listed in the DSC file, AND the PCD is listed in the DEC file under [PcdsDynamicEx] and/or [PcdsDynamic] and [PcdsPatchableInModule] sections, the build must use the PcdsPatchableInModule access method for this PCD in all source modules in the platform that use this PCD.

7. If the PCD is listed in a [Pcd] section in all of the source modules using that PCD that are listed in the DSC file, AND the PCD is listed in the DEC file under [PcdsDynamicEx] and [PcdsDynamic] sections, the build must use the PcdsDynamicDefault access method for this PCD in all source modules in the platform that use this PCD.

8. If the PCD is listed in a [Pcd] section in all of the source modules using that PCD that are listed in the DSC file, AND the PCD is listed in the DEC file under [PcdsDynamicEx] sections, the build must use the PcdsDynamicExDefault access method for this PCD in all source modules in the platform that use this PCD.

9. If multiple source modules set the Dynamic or DynamicEx PCD to the different value in the same platform, and the PCD is not listed in the DSC file, the build should break with an appropriate error message.

10. If a PCD is used in a module listed in the DSC or FDF file and the PCD is not declared in any of the DEC files that the module depends on (listed in the [Packages] section) the build must break with an appropriate error message.

11. If a PCD is listed in the DSC or FDF file and the PCD is not declared in any of the DEC files AND the PCD is not used by any of the modules listed in the DSC or FDF file, the build must break with an appropriate error message.

8.4.1.3 Precedence Rules

The rules are listed in order, such that the first match stops any additional processing. The following rules apply to Binary modules listed in a platform DSC file.

1. PCD value assignment from command-line using --pcd flag takes precedence over all other assignments.

2. PCD assignments are not permitted in the FDF file except through SET statements or the automatic assignments from the [FD] section regions.

3. PCD value assignment in a module scoping section take precedence over values specified in the global section for PatchableInModule PCDs.

4. PCD value assignment in a global PCD section with an architectural modifier take precedence over assignments in a global section.

5. PCD value assignment in a global PCD section without an architectural modifier.

6. The value specified in the Binary INF has the lowest precedence; the DEC file is never used to determine a PCD value for a Binary INF.

The following rules apply to modules listed in a platform DSC file.

1. PCD value assignment from command-line using --pcd flag takes precedence over all other assignments.

2. PCD assignments in an FDF file are positional, with the last value taking precedence over previous assignments in the FDF file.

3. A PCD assignment in an FDF file takes precedence over PCD values assigned in the DSC file's module scoping section.

4. A PCD value of an entry listed in a module scoping section take precedence over the PCD value listed in a global section that has an architectural modifier in the DSC file.

5. A PCD value of an entry listed in a global section that has an architectural modifier takes precedence over the PCD value listed in a global section without an architectural modifier in the DSC file.

6. A PCD value of an entry listed in a global section without architectural modifiers in the DSC file takes precedence over the PCD value listed in an INF file in a section with an architectural modifier.

7. A PCD value of an entry listed in an INF file section with an architectural modifier takes precedence over an entry listed in an INF file section without an architectural modifier.

8. A PCD value of an entry listed in an INF file section without an architectural modifier takes precedence over a PCD value listed in a DEC file in a section with an architectural modifier.

9. A PCD value of an entry listed in a DEC file section with an architectural modifier takes precedence over a PCD value listed in a DEC file in a section without an architectural modifier.

Because the INF describes how a module is coded, a PCD can only be listed under one access method: a PCD section tag with architectural modifiers cannot specify a different access method for a PCD. The EDK II C Coding Standard prohibits using preprocessor directives for architectures within the C code.

• For instance, it is not possible to list a PCD as being FixedAtBuild for all architectures and PatchableInModule for X64 if the module uses only common files.

  For a given platform, a PCD can only use one access method for source modules. Having different access methods for same architecture is not permitted.

• For instance, it is prohibited to have one module for IA32 and another copy of the module for X64 that use different PCD access methods.

8.4.1.4 Dynamic and DynamicEx Database Rules

This subsection covers the rules for adding Dynamic or DynamicEx PCDs to the PCD database.

1. If a PCD is listed in a PcdsDynamicVpd or PcdsDynamicExVpd section, and the PCD is not used by any module that is listed in the DSC file, the build MUST ADD the entry in the Platform's PCD Database, and the parser must not throw an error or warning message.

2. If PCD is listed in a PcdsDynamicDefault or PcdsDynamicExDefault section, and the PCD is not used by any module that is listed in the FDF file (even if a module that uses the PCD is listed in the DSC file), the build must NOT add the entry in the Platform's PCD Database.

   • The build may provide a warning message.

3. If PCD is listed in a PcdsDynamicHii or PcdsDynamicExHii section, and the PCD is not used by any module that is listed in the FDF file (even if a module that uses the PCD is listed in the DSC file), the build must NOT add the entry in the Platform's PCD Database.

   • The build may provide a warning message.

4. If a PCD is not listed in the DSC file but is listed under a [PcdsEx] section in a Binary INF file listed in the FDF file, then the build must add the entry to the Platform's PCD Database as PcdsDynamicExDefault.

5. If a PCD is not listed in the DSC file, but binary INF files used by this platform use this PCD and list the PCD in a [PcdsEx] section, AND any source INF files that use the PCD list the PCD in either a [Pcds] or [PcdsEx] section, then the tools MUST ADD the PCD to the Platform's PCD Database.

   • The build must assign the access method for this PCD as PcdsDynamicExDefault.

6. If a PCD is not listed in the DSC file, but binary INF files used by this platform all (that use this PCD) list the PCD in a [PatchPcds] section, AND all source INF files used by this platform the build that use the PCD list the PCD in either a [Pcds] or [PatchPcds] section, then the tools must NOT add the PCD to the Platform's PCD Database.

   • The build must assign the access method for this PCD as PcdsPatchableInModule.

7. If one of the Source built modules listed in the DSC is not listed in FDF modules, and the INF lists a PCD can only use the PcdsDynamic access method (it is only listed in the DEC file that declares the PCD as PcdsDynamic), then build tool will report warning message that notifies the PI of an attempt to build a module that must be included in a flash image in order to be functional.

   • These Dynamic PCD will not be added into the Database unless it is used by other modules that are included in the FDF file.

8. If one of the Source built modules listed in the DSC is not listed in FDF modules, and the INF lists a PCD can only use the PcdsDynamicEx access method (it is only listed in the DEC file that declares the PCD as PcdsDynamicEx), then DO NOT break the build.

   • DO NOT add the PCD to the Platform's PCD Database.

9. If a module is listed in FDF file and use a Dynamic or DynamicEx PCD, the PCD MUST be added into the PCD Database.

The build system must emit a line containing the total number of warnings from the above rules at the end of a build.

Note: Because parsing warnings may appear for only a short period prior to calling other tools that emit a copious number of informational messages, this line will ensure that the PI knows that warnings were emitted.

8.4.1.5 FeatureFlag PCDs used in conditional directive statements in code

FeatureFlag PCDs used in conditional directive statements in code have the following rules.

1. A FeatureFlag PCD cannot use any other access method. If a PCD name is listed in an FF section, and also in another section type, the build must break.

2. A PCD can only be use one access method for all modules in a platform; a PCD cannot use the patch access method in one module and fixed access method in another module in the same platform. The build parser must break with an error message if this occurs.

3. Duplicate PCD names listed within a section are positional, such that only the value of the last entry will be used.

Note: A PCD name & value listed in an architectural section takes precedence over the PCD name & value specified in a common section when build for a specific architecture. If a PCD name is not listed in a section that contains an architectural modifier, and is listed in a section that is common, the value in from the entry in a common section will be used.