This schema defines the UEFI/PI Distribution Package description (PKG) file. It describes the content of: 1) Package descriptions with definitions and headers. 2) Modules in either source or binary format. (Note that Binary format is for FFS leaf section file types only, complete FFS files cannot be distributed using this distribution format.) 3) The distribution of custom tools used to modify the binary images to create UEFI/PI compliant images. 4) Finally, it can be used to distribute other miscellaneous content that is not specific to UEFI/PI images. The Package Surface Area describes the content of packages, while the Module Surface Area provides information relevant to source and/or binary distributions. This header contains (legal) information usually required for distributing both binary and/or source code. The list of packages in this distribution. Packages are groups of files and/or modules that are similar in nature. Packages are uniquely identified by a package GUID and a package version. A package can declare public mappings of C names to GUID values. A package can provide header files for library classes and/or other industry standard definitions. A package can also declare public mappings of platform configuration database (PCD) "knobs" to control features and operation of modules within a platform. Finally, a package lists the library instances and/or modules that are provided in a distribution package. The listing of UEFI/PI compliant modules in this distribution that are NOT part of a Package. Every module that is provided as part of a package needs to be described in a PackageSurfaceArea.Modules section. The ModuleSurfaceArea section describes how each module in a distribution is coded, or, in the case of a binary module distribution, how it was built. UEFI/PI compliant libraries and modules are uniquely identified by the Module's GUID and version number. This section will typically be used for modules that don't require any additional files that would be included in a package. For example, the Enhanced FAT driver binary does not need to have a package description, as no additional files are provided. This section is for distributing vendor specific executable tools, tool source code and/or configuration files. These tools are primarily for manipulating code and/or binary images. Tools in this section can: 1) Parse build meta-data files to create source code files and build scripts. 2) Modify image files to conform to UEFI/PI specifications. 3) Generate binary files from certain types of text/unicode files. 4) Generate PCI Option Roms or Firmware Device images. 5) Implement external encoding/decoding/signature/GUIDed tools. 6) Distribution Package create/install/remove tools. The list of miscellaneous files in this distribution. Any files that are not listed in either the Package, Module or Tools sections can be listed here. This section can be used to distribute specifications for packages and modules that are not "industry standards" such as a specification for a chipset or a video device. The UserExtensions section is used to disseminate processing instructions that may be custom to the content provided by the distribution. This section contains information that is common to all aspects of this disribution. This section defines the content of the UEIF/PI compliant Distribution Package Header. This is the only required element of a UEFI/PI compliant distribution package. This is the User Interface Name for this Distribution Package. Each Distribution Package is uniquely identified by it's GUID and Version number. The reference name of the Distribution Package file. This single word name can be used by tools as a keyword or for directory and/or file creation. White space and special characters (dash and underscore characters may be used) are not permitted in this name. This 128-bit GUID and the Version attribute uniquely identify this Distribution Package. Backward compatible releases of a distribution package need only change the version number, while non-backward compatible changes require the GUID to change (resetting the version number to 1.0 is optional.) This value, along with the GUID, is used to uniquely identify this object. The higher the number, the more recent the content. A string identifying who created this distribution package. The date and time this distribution was created. The format is: YYYY-MM-DDThh:mm:ss, for example: 2001-01-31T13:30:00 (note the T character separator between the calendar date and the time. The copyright for this file that is generated by the creator of the distribution. If a derivative work is generated from an existing distribution, then the existing copyright must be maintained, and additional copyrights may be appended to the end of this element. It may also be the primary copyright for all code provided in the Distribution Package. A license that describes any restrictions on the use of this distribution. If a derivative work is allowed by the original license and a derivative work is generated from an existing distribution, then the existing license must be maintained, and additional licenses may be appended to the end of this element. It may also be the primary license for all code provided in the distribution file. Alternatively, this may point to a filename that contains the License. The file (included in the content zip file) will be stored in the same location as the distribution package's .pkg file. A one line description of the Distribution Package. A complete description of the Distribution Package. This description may include the release name of the file, the version of the file, and a complete description of the file contents and/or features including a description of the updates since the previous file release. The packaging utilities will use this MD5 sum value of the included ZIP file containing files and/or code. If this element is not present, then installation tools should assume that the content is correct, or that other methods may be needed to verify content. This version of this XML Schema is 1.1 Changes to 1.1 from 1.0 #1 Updated to present date and new version which is important to reflect the present state of the matter #2 Added definition/enumeration of UNDEFIND type 2 is important since there is a large body of legacy code for which the GUID’s and other code/data objects were not decorated with their usage. This document will allow for importing today’s source artifacts and producing decorations using the ‘Undefined’ versus having an error #3 Allow for inclusion of ARM and future architecture types If set to true, all content within this Distribution Package should NOT be modified. The default permits modification of all content. If set to true, then the content can be repackaged into another distribution package. The default prohibits repackaging the Distribution content. A package is a collection of related objects - Includes, Libraries and Modules. Each package is uniquely identified by it's GUID and Version number. Backward compatible releases of a package need only change the version number, while non-backward compatible changes require the GUID to change (resetting the version number to 1.0 is optional.) This is the User Interface Name for this package. This is a single word BaseName of the package. This BaseName can be used by tools as a keyword and for directory/file creation. This GUID and the Version attribute uniquely identify a given package. This value, along with the GUID, is used to uniquely identify this object. Backward compatible changes must make sure this number is incremented from the most recent version. Non-backward compatible changes require a new GUID, and the version can be reset. If the package requires a different copyright than the distribution package, this element can list one or more copyright lines. If the package requires licenses that are different from the distribution package license, this element can contain one or more license text paragraphs (or license filenames.) A one line description of this package. A complete description of a package. This description may include the release name of the package, the version of the package, and a complete description of the package contents and/or features including a description of the updates since the previous package’s release. This element is the location (in the ZIP file) for the root directory of a package. The term cloned is used here to indicate that this package as been copied and modified to a completely different package. An example might be for a new generation of chipsets that have few or no elements in common with the original. This GUID and the Version attribute uniquely identify the Package that this Package was copied from. This value, along with the GUID, is used to uniquely identify the package that this package was cloned from. Library Classes are public interfaces that can be used by modules. One or more library instances can implement a library class, however only one library instance can be linked to an individual module. This provides the platform integrator with the flexibility of choosing one library instance's implementation over a different library instance. The header file provides definitions and function prototypes for a library class. Modules can be coded against these functions, using the definitions in this header, without concerning themselves about the libraries' implementation details. This is a PackagePath relative path and filename for the include file. This GUID and the Version attribute uniquely identify the Recommended Library Instance. This value, along with the GUID, is used to uniquely identify this object. If this value is not specified, then any version of the library instance is recommended. The single word name of the Library Class that module developers will use to identify a library class dependency. This section is used to list header files for industry standards not under the auspices of UEFI.org. For example, headers that contain definitions and data structures for the USB specifications. The package relative path and filename (in the content zip file) of the industry standard include file. All top level header files that are included by a package that are not listed above. They cannot be: 1) Local to a module (module specific.) 2) An industry standard header. 3) A library class header. This is the Package relative path and filename location within the content ZIP file. This section lists the Module Surface Area for all modules provided with this package. This section defines the mapping of GUID C names to GUID values as a Registry Format GUID. Modules that use these GUIDs must specify their dependency on this package. Individual GUID Declarations This section defines the mapping of Protocol C names to GUID values as a Registry Format GUID. Modules that use these Protocols must specify their dependency on this package. Individual Protocol Declarations This section defines the mapping of Ppi C names to GUID values as a Registry Format GUID. Modules that use these Ppis must specify their dependency on this package. Individual PPI Declarations This section is used to declare platform configuration knobs that are defined by this package. Modules that use these PCD values must specify their dependency on this package. Specifies the C name of the Token Space GUID of which this PCD Entry is a member. This C name should also be listed in the GUIDs section, (specified above,) where the C name is assigned to a GUID value. Specifies the 32-bit token value for this PCD Entry. The Token number must be unique to the Token Space that declares the PCD. The minLength of 3 is required to handle the "0x" prefix to the hex number. A string that contains the data type of this PCD Entry. PCD data types are restricted to the following set:UINT8, UINT16, UINT32, UINT64, VOID*, BOOLEAN. A string that contains one or more PCD Item types separated by spaces. The PCD Item types are restricted to FeaturePcd, FixedPcd, PatchPcd, Pcd and/or PcdEx. This is a recommended maximum data size for VOID* data types, the actual value should be defined by the Platform Integrator. It is not required for the other data types. The minLength of 3 is required to handle the "0x" prefix to the hex number. Valid Error messages that may be implemented in a module for the PCD Entry. Only One Error Number per PcdError, (multiple ErrorMessage entries are permitted) and multiple PcdError elements are permitted. One of the following types of comparisons, which must be able to evaluate to either true or false. The PCD Value must be space separated list of values. Values are restricted to the data type of this PCD. The PCD must be within a specifed range of numeric values. Restricted to C style Relational, Equality and Logicial Operators and parenthesis are valid. Only the CName for this PCD is permitted in the ValidValueRange expression. All other values must be numeric. LValue (op RValue)+ A in-fix logical expression using C style logical operators. A hexadecimal value for the error message as defined by specifications. The minLength of 3 is required to handle the "0x" prefix to the hex number. This string should be defined by specifications. There are pre-defined error number ranges in the UEFI/PI specificaiton. This section is used to describe any PCD interdependencies or relationships. This entry must used TokenSpaceGuidCName.PcdCname for every named PCD. Restricted to Relational, Equality and Logical Operators (NOT, AND, OR, GT, GE, EQ, LE, LT and XOR) and parenthesis are valid. Only the TokenSpaceGuidCName.PcdCname us permitted to name PCDs in the expression. All other values must be numeric. LValue (op RValue)+ This section contains files that are not part of the code distributed with this package. Only required if different from the Package Copyright. Only required if different from the Package License. A one line description of this section's content. A complete description of the files in this section. This is the PackagePath relative path and filename location within the ZIP file. If true, used by installation tools to ensure that a file that must be executable has the correct properties to permit execution. This section is used for any processing instructions that may be custom to the content provided by this package that are common to this package. This is a single word identifier for grouping similar content that does not fit into previously defined sections or other sections of the Distribution. This can be used to differentiate multiple sections with a grouping. For example, a PRE_PROCESS Identifier might indicate specific steps and tools required before processing module content, while a different UserExtensions section with a POST_PROCESS Identifier might describe steps that need to be executed after operations on the modules in this package. Each module is uniquely identified by it's GUID and Version number. Backward compatible releases of a module need only change the version number, while non-backward compatible changes require the GUID to change (resetting the version number to 1.0 is optional.) This is the User Interface Name for this Module. This is a single word BaseName that will be used to create a module meta-data file. This name should also be used to create output file names and directories. This GUID and the Version attribute uniquely identify a given Module. This value, along with the GUID, is used to uniquely identify this object. Backward compatible changes must make sure this number is incremented from the most recent version. Non-backward compatible changes require a new GUID, and the version can be reset. This is only required if the Copyright is different from either the Package or Distribution copyright. Multiple copyright lines are permitted within this section. This is only required if the license is different from either the Package or Distribution license. Multiple licenses are permitted within this section. A brief text description of the module. A complete description of the module contents and/or features including a description of the updates since the previous module release. List general information about a module, including the Supported Architectures, this module's type, specifications the module is coded against, and other informational content. One of the Enumerated module types that limit the use of a module. For stand-alone modules that are NOT part of any package, this is the path to the root of the module as listed in the ZIP file. For modules included in a package, this is the location, relative to the root of the package (PackagePath) this module belongs to. This element is only required for the PEIM that produces the PCD PPI or the DXE Driver that produces the PCD Protocol. This is a list of other specifications that this module is written against. These entries can be used in #define statements (depending on the build system implementation, they may be autogenerated.) Different firmware execution paths may be taken based on a given state of the hardware, firmware, or through feature settings. A BootMode may be declared (PRODUCES) or discovered (CONSUMES) based on these states and feature settings. If the usage is UNDEFINE, it implies that a Boot Mode is used, but the package creator does not know how it is used. The supported boot modes map to the PI specification Boot Modes. The boot modes listed with Recovery are to indicate that the BootMode is valid during a recovery boot. The module always supports the given boot modes. The module may support a given mode on some execution paths. The module will change the boot mode. The module will change the boot mode on some exection paths. The package creator does not know how the boot mode is used. The functions that make up the Event, Timer, and Task Priority Services are used during preboot to create, close, signal, and wait for events; to set timers; and to raise and restore task priority levels as defined in the UEFI specification. GUIDed events should be listed in the Guids section. The module will register a notification function and calls the function when it is signaled. The module will register a notification function and calls the function when it is signaled on some execution paths. The module will signal all events in an event group. The module will signal all events in an event group under some execution paths. The package creator does not know how an event is used. This is a list of non-GUIDed Hand Off Blocks (HOBs) produced or consumed by this module. A HOB must be present in the system. If present, the HOB will be used. The HOB is always produced by the module. The HOB may be produced by the module under some execution paths. The package creator knows that a HOB is used, but does not know how it is used. This section may be included for Modules that are copied from a different module. This GUID and the Version attribute uniquely identify the Module that this Module was copied from. This value, along with the GUID, is used to uniquely identify this object. A list of the different Library Classes consumed by a driver, core and/or application module, or produced by a Library module. Used by tools to identify different instances of libraries that provide the library class. This keyword identifies the library class this module needs to be linked against. This GUID and the Version attribute uniquely identify the recommended Library Instance for this module . This value, along with the GUID, is used to uniquely identify this object. Library instances can provide code for a library class, or may require other library instances themselves. Since different execution paths in a library (or module) may need different library classes based on some setting, library classes may not alway be required. A FeatureFlag attribute must evaluate to either true or false - it may be a fixed value of true or false, a C name or an in-fix expression. This is the module relative (ModuleProperties.Path) path and filename location within the ZIP file. The Family attribute is used to restrict usage to a given family of compilers, such as GCC or MSFT. Since not all code processing tools use the same syntax, especially for assembly, this field can be used to identify different syntax. This is the module relative (ModuleProperties.Path) path and filename location within the ZIP file. Binary file distribution is limited to UEFI/PI FFS leaf section file types. A UEFI/PI FFS Leaf section file type, not a raw PE32 file. This section contains information about how the module was coded, such as Compiler Tools, Flags, PCDs (only PatchPcd and/or PcdEx) and Library Class Instances used to build the binary. The element is the Patchable PCD Value that was used during the build. The minLength of 3 is required to handle the "0x" prefix to the hex number. This field is required if the Pcd Datum Type is VOID* The minLength of 3 is required to handle the "0x" prefix to the hex number. The minLength of 3 is required to handle the "0x" prefix to the hex number. Error information implemented by the module. The minLength of 3 is required to handle the "0x" prefix to the hex number. The element is the DynamicEx PCD Value that was used during the build. The minLength of 3 is required to handle the "0x" prefix to the hex number. This field is required if the Pcd Datum Type is VOID* Error information implemented by the module. The minLength of 3 is required to handle the "0x" prefix to the hex number. This is the actual library instance that was used to link against the module. This GUID and the Version attribute uniquely identify the actual Library Instance linked in this module. This value, along with the GUID, is used to uniquely identify this object. Any description of OS, Tool, and flags for the individual tool can go in this section. This GUID and the Version attribute uniquely identify Package that this Module depends on. This value, along with the GUID, is used to uniquely identify this object. If the version attribute is not specified, the most recent version of the package can be used. Only valid for Variable GUID types. This can be either a Hex Array or C string in unicode format: L"string" Data. The module does not install the GUID, and the GUID must be present for the module to execute. The module does not install the GUID, however, the GUID will be used if it is present. The module always installs the GUID. The Module will install the GUID under certain execution paths. The package creator knows that a GUID is used, but does not know how it is used. A listing of protocols required or produced by this module. A listing of PPIs required or produced by this module. These elements specify additional information about the module. This area may be used by tools to generate code. This section describes how a platform is coded with respect to the platform configuration knobs. This is the PEI dependency expression for a Dependency Section. An in-fix expression, of C identifiers and TRUE, FALSE, AND, OR, NOT, BEFORE, and AFTER as well as parenthesis () in the in-fix notation. The operators are restricted to grammar defined in the PI specification. This is the DXE dependency expression for a Dependency Section. An in-fix expression, of C identifiers and TRUE, FALSE, AND, OR, NOT, BEFORE, and AFTER as well as parenthesis () in the in-fix notation. The operators are restricted to grammar defined in the PI specification. This is the SMM dependency expression for a Dependency Section. An in-fix expression, of C identifiers and TRUE, FALSE, AND, OR, NOT, BEFORE, and AFTER as well as parenthesis () in the in-fix notation. The operators are restricted to grammar defined in the PI specification. This section is used to provide comments and/or list auxiliary files, such as pdb or map files. This is the path and filename location within the ZIP file. If true, used by installation tools to ensure that a file that must be executable has the correct properties to permit execution. This section is used for any processing instructions that may be custom to the content provided by the distribution that are common to module. The content is vendor specific. The content can be plain text as well as any user-defined, properly formatted XML structure. This is a single word identifier for grouping similar content. For example, ReferenceBuild might be used to identify non-PI compliant build steps, with two different UserExtensions sections, one with an Identifier of Prebuild, and another of PostBuild. Both UserExtensions sections would use the same UserId. This can be any string used to differentiate or identify this section from other UserExtensions sections. For example, a PRE_PROCESS Identifier might indicate specific steps and tools required before processing module content, while a different UserExtensions section with a POST_PROCESS Identifier might describe steps that need to be executed after operations on this module. This attribute is used when the binaries are distributed for this module and no code generation from source files is required. If set, then the BinaryFiles section should be used, and any files listed in the SourceFiles section do not have to be built. Additionally, the AsBuilt section for each binary file must be included. This is the User Interface Name for this Tools Distribution. This is only required if the Copyright is different from the Distribution Package copyright. This is only required if the License is different from the Distribution Package license. This is only required if the Abstract is different from the Distribution Package Abstract. This is only required if the Description is different from the Distribution Package Description. This is the path and filename location within the ZIP file. This is required for tools that execute; it should not be used for configuration files. If true, used by installation tools to ensure that a file that must be executable has the correct properties to permit execution. This section contains a list of files that are not part of the code distributed with modules, packages or tools. The User interface name for this content. This is only required if the Copyright is different from the Distribution Package Copyright. This is only required if the License is different from the Distribution Package License. This is the path and filename location within the ZIP file. If true, used by installation tools to ensure that a file that must be executable has the correct properties to permit execution. This is a single word identifier for grouping similar content. For example, ReferenceBuild might be used to identify non-PI compliant build steps, with two different UserExtensions sections, one with an Identifier of Prebuild, and another of PostBuild. Both UserExtensions sections would use the same UserId. This can be any string used to differentiate or identify this section from other UserExtensions sections. For example, a PRE_PROCESS Identifier might indicate specific steps and tools required before processing distribution package content, while a different UserExtensions section with a POST_PROCESS Identifier might describe steps that need to be executed after operations on this content. Any processor architecture not listed above. The Architecture must be a target architecture of one or more compiler tool chains. Any other family of build utilities for which compiler tools exist. The following module types are defined by specifications. Module types for components and libraries defined for this distribution mechanism. Use of this module is not restricted. This module is only applicable to the DXE core. This module is only applicable to a DXE driver. This module is only applicable to a DXE runtime driver. This module is only applicable to an IPF DXE runtime driver. This module is only applicable to a DXE SMM driver. This module is only applicable to the PEI core. This module is only valid for PEI modules. This module is only applicable to Security phase. This module is only valid for UEFI drivers. This module is only valid for UEFI runtime drivers. This module is only valid for UEFI applications. This module is only applicable to the SMM core. This content is restricted to a specific implementation. This enumeration is for use in a list that where the package creator does not know the what module types are supported by a module. This pattern has been added for use in a module lists - for future expansion. The following data types are defined by the PCD specification (or PCD section of the UEFI/PI specifications.) The Feature PCD is a binary, evaluating to either true or false. This is used during build to include/exclude content. It can also be used during execution to force execution paths within drivers, or to enable/disable features within a driver for a given platform. The Fixed PCD is a #define value that is set at build time. The Patch PCD is a #define that is set at build time, and that can be modified within a binary file. Additional information, such as the offset location of the value, along with it's length may need to be provided. This PCD type has an overloaded definition. Prior to build, the platform integrator may choose to implement a PCD as Fixed, Patchable or a Dynamic PCD. If the platform integrator choose to use the PCD as dynamic, then a PCD driver is required in the platform (PEI/DXE/both) to track the PCD in some sort of 'database' of these items. For Dynamic PCDs, the PcdGet* must pass in the token space guid and the token number to retrieve data (PcdSet* also needs these values.) The PCD can only be used as Dynamic, and the platform firmware must contain a driver to maintain a 'database' of these items. For Dynamic PCDs, the PcdGet* must pass in the token space guid and the token number to retrieve data (PcdSet* also needs these values.) A GUID must contain five different Hexadecimal character sets that are separated by a dash (-) character. The EDK II build system supports workstations running one of the following supported operating systems. This is the OS for the developer's workstation, not the target platform. For Windows 2003, Windows XP and Windows Vista. For Windows 2003, Windows XP and Windows Vista. Typically, this is used for Windows Batch files. Typically use for shell scripts - valid for any Linux and Mac OS/X.