Hi Folks,
It was pointed out that I had missed adding a section describing a DEC Special
Comment Block (and I also noted that I had missed making the PACKAGE_UNI_FILE
an optional entry. Here are the updates for these two items:
DEC Specification change updates.
Add section:
3.2.5 Special Comment Blocks
This section defines special format comment blocks that contain information
about this package. These command blocks are not required.
The UEFI Distribution Package Specification states the for a given PCD Token
Space, Error numbers must be unique. Since there may be multiple PCD that may
have identical error types, an error number with an associated error message
may be shared. The syntax described here can be used by tools to map these
error numbers by a token space GUID C name. These comment blocks must appear
before content might be used (in later sections of the DEC file).
Prototype
<ErrNoBlock> ::= <TS> "#" <EOL>
<TS> "#" <MTS> "[Error." <TSpaceGuidCName> "]" <EOL>
[<TS> "#" <MTS> <UINT32> <FS> <AsciiString> <EOL>]+
<TS> "#" <EOL>+
Example
#
# [Error.gEfiIntelFrameworkModulePkgTokenSpaceGuid]
# 0x80000001 | Invalid value provided.
# 0x80000002 | Reserved bits must be set to zero.
#
Modified EBNF in: 3.4 [Defines] Section
Prototype
<defines> ::= "[Defines]" <EOL>
<TS> "DEC_SPECIFICATION" <Eq> <SpecVer> <EOL>
<TS> "PACKAGE_NAME" <Eq> <UiNameType> <EOL>
<TS> "PACKAGE_GUID" <Eq> <RegistryFormatGUID> <EOL>
<TS> "PACKAGE_VERSION" <Eq> <DecimalVersion> <EOL>
[<TS> "PACKAGE_UNI_FILE" <Eq> <Filename> <EOL>]
<MacroDefinition>*
Cheers,
Larry
From: Hauch, Larry [mailto:larry.ha...@intel.com]
Sent: Friday, August 08, 2014 10:40 AM
To: edk2-devel@lists.sourceforge.net
Subject: Re: [edk2] INF/DEC file updates to EDK II packages
Hi Folks,
Here are the proposed changes to the INF and DEC specifications. . Added
content highlighted and italic, deleted content strike-through and highlighted.
Please see below.
Cheers
Larry
############### INF Specification changes:
Revision table
Updates:
* Change revision number of this specification from 1.22 to 1.24
* Update INF_VERSION to 0x00010017
* Added MODULE_UNI_FILE entry to the [Defines] section; this file
must end with an extension of .uni, .UNI or .Uni.
* Added reserved TianoCore user extension for "ExtraFiles"
* Allow Space and Unicode characters in the directory path
identified by the system environment variable WORKSPACE
All examples for INF_VERISION
INF_VERSION = 0x000100176
Section 2.2.4 Naming Conventions, bullet three:
* Directory names and file names within the WORKSPACE directory
tree must not contain space characters.
Section 2.4 [Defines] Section, Table 1.
Tag
Required
Value
Notes
INF_VERSION
REQUIRED
0x000100176
This identifies the INF spec. version. Tools use this value to handle parsing
of previous releases of the specification if there are incompatible changes.
...
MODULE_UNI_FILE
Optional
Filename
A UCS-2LE encoded file containing localization strings, the file path (if
present) is relative to the directory containing the INF file.
New Section, 2.16.1
2.16.1 [UserExtensions.TianoCore."ExtraFiles"] Section
The EDK II [UserExtensions.TianoCore."ExtraFiles"] section allow for
distributing extraneous files that are associated with a module. Files listed
in this section are not processed by EDK II build tools. These files must exist
in the directory or sub- directories of the directory containing the INF file.
The Intel(r) UEFI Packaging Tool will parse this section and for all files
listed in this file, add the file to the module distribution using the UEFI
Distribution Package Distribution.
The section header must be: [UserExtensions.TianoCore."ExtraFiles"]
Having data elements under the section header is not required.
The following is an example of a [UserExtensions.TianoCore."ExtraFiles"]
section:
[UserExtensions.TianoCore."ExtraFiles"]
Readme.txt
Section 3.3, Updated BinaryAbstract Parameter, Bullet 4
* The INF file will always have an English version of the Abstract.
Other localized versions of the abstract will be stored in the UCS-2LE encoded
file specified in the [Defines] section's MODULE_UNI_FILE.
Note: The MODULE_UNI_FILE permits the Intel(r) UEFI Packaging Tool to process
localized module content described in the UEFI Platform Initialization
Distribution Package Specification.
Section 3.3, Update BinaryDescription Parameter, Bullet 4
* The INF file will always have an English version of the
Description. Other localized versions of the description will be stored in the
UCS-2LE encoded file specified in the [Defines] section's MODULE_UNI_FILE.
Note: The MODULE_UNI_FILE file permits the Intel(r) UEFI Packaging Tool to
process localized module content described in the UEFI Platform Initialization
Distribution Package Specification.
Section 3.4 [Defines] Section, inserted description of the MODULE_UNI_FILE
following OptionRom paragraph and before the FixedComments paragraph.
The optional MODULE_UNI_FILE entry is used to locate an UCS-2LE format file
which can be used for localization of the module's Abstract and Description
from the header section. The content of the file can be generated by tools
during the installation of a distribution package that conforms to the UEFI
Platform Initialization Distribution Packaging Specification, or by module
developers creating new content.
Section 3.4 [Defines] Section, EBNF updates:
<DefineStatements> ::= <TS> "INF_VERSION" <Eq> "0x000100176" <EOL>
[<TS> <UefiHiiResource> <EOL>]
[<TS> "MODULE_UNI_FILE" <Eq> <Filename> <EOL>]
[<MacroDefinition>]*
Section 3.4 [Defines] Section, Filename parameter
Filenames listed in the [Defines] section must be relative to the directory the
INF file is in. Use of "..", "." and "../" in the directory path is not
permitted. Use of an absolute path is not permitted. The file name specified in
the MODULE_UNI_FILE entry must be a UCS-2LE encoded file with an extension of
.uni, .UNI or .Uni.
Section 3.4 [Defines] Section, Added parameters for PCD_IS_DRIVER and
MODULE_UNI_FILE
PCD_IS_DRIVER
This entry, if set, must be included in an "As Built" INF file generated by
tools.
MODULE_UNI_FILE
This file is used to contain localized Abstract and Description information;
the file must be UCS-2LE encoded.
Added Section 3.10.1
3.10.1 [UserExtensions.TianoCore."ExtraFiles"] Section
This is an optional section.
Defines the optional EDK II INF file [UserExtensions.TianoCore."ExtraFiles"]
section tag. The EDK II build tools must not process any files listed in this
section.
Summary
This section is used by the Intel(r) UEFI Packaging Tool, that is distributed
as part of the EDK II BaseTools, to locate files listed under this section
header and add them to the UEFI distribution package. When installing a UEFI
distribution package, these files will be installed in the module's directory
tree.
Prototype
<UserExtensions> ::= "[UserExtensions" <TcEf> "]" <EOL> <FileNames>*
<TcEf> ::= ".TianoCore." <DblQuote> "ExtraFiles" <DblQuote>
<FileNames> ::= <TS> [<RelativePath>] <File> <EOL>
Parameters
FileNames
Paths listed in the filename elements of the this section must be relative to
the directory the INF file resides in. Use of "..", "." and "../" in the
directory path is not permitted.
Example
[UserExtensions.TianoCore."ExtraFiles"]
Readme.txt
############### DEC Specification Changes:
All examples for DEC_SPECIFICATION
DEC_SPECIFICATION = 0x000100176
Revision table
Updates:
* Change revision number of this specification from 1.22 to 1.24
* Update DEC_ SPECIFICATION to 0x00010017
* Added additional parameter definitions for clarification of comment
content for PCDs
* Added the PACKAGE_UNI_FILE entry to the [Defines] section
* Added reserved TianoCore user extension for "ExtraFiles"
Section 2.4 [Defines] Section
The [Defines] section is used to track the package's GUID and version, which
allows multiple copies of the same package with different versions to exist
within a single workspace. Architectural modifiers are not permitted in the
[Defines] section. If major changes to a package occur, the GUID value of the
package must also change. Additionally, the package's version major number may
change. Minor changes require incrementing the package's version minor number.
The PACKAGE_UNI_FILE entry points to a UCS-2LE encoded file containing
localization strings. The file path (if present) is relative to the directory
containing the INF file.
This section will use only one section header:
[Defines]
The format for entries in this section is:
Name = Value
The following is an example of this section.
[Defines]
DEC_SPECIFICATION = 0x000100050x00010017
PACKAGE_NAME = MdePkg
PACKAGE_GUID = 1E73767F-8F52-4603-AEB4-F29B510B6766
PACKAGE_VERSION = 1.02
PACKAGE_UNI_FILE = MdePkg.uni
Added 2.11.1 [UserExtensions.TianoCore."ExtraFiles"] Section
The EDK II [UserExtensions.TianoCore."ExtraFiles"] section allow for
distributing extraneous files that are associated with a package. Files listed
in this section are not processed by EDK II build tools. These files must exist
in the directory or sub- directories of the directory containing the DEC file.
The Intel(r) UEFI Packaging Tool will parse this section and for all files
listed in this file, add the file to the package distribution using the UEFI
Distribution Package Distribution.
The section header must be: [UserExtensions.TianoCore."ExtraFiles"]
Having data elements under the section header is not required.
The following is an example of a [UserExtensions.TianoCore."ExtraFiles"]
section:
[UserExtensions.TianoCore."ExtraFiles"]
Readme.txt
UserManual.pdf
Modified EBNF in: 3.4 [Defines] Section
Prototype
<defines> ::= "[Defines]" <EOL>
<TS> "DEC_SPECIFICATION" <Eq> <SpecVer> <EOL>
<TS> "PACKAGE_NAME" <Eq> <UiNameType> <EOL>
<TS> "PACKAGE_GUID" <Eq> <RegistryFormatGUID> <EOL>
<TS> "PACKAGE_VERSION" <Eq> <DecimalVersion> <EOL>
<TS> "PACKAGE_UNI_FILE" <Eq> <Filename> <EOL>
<MacroDefinition>*
<UiNameType> ::= <Word>
<SpecVer> ::= "0x000100050x00010017"
Added Filename to Parameters in section 3.4:
Filename
Filenames listed in the [Defines] section must be relative to the directory the
INF file is in. Use of "..", "." and "../" in the directory path is not
permitted. Use of an absolute path is not permitted. The file name specified in
the PACKAGE_UNI_FILE entry must be a UCS-2LE encoded file with an extension of
.uni, .UNI or .Uni.
Appended the following to the Example in section 3.4:
PACKAGE_UNI_FILE = MdePkg.uni
Added the following parameters to section 3.10 PCD Sections
HexDigit
This value, if specified corresponds to the ErrorNumber of an Error Message
defined in a UEFI PI Distribution Package. Each error number is related to a
single error message (translations of message text are not considered as
separate error messages), with the text of error messages included in the
Unicode file specified in the PACKAGE_UNI_FILE element in the [Defines] section.
TokenNumber
Each PCD declared within a token space (defined by the Token Space GUID) must
be assigned a unique 32-bit value. This token number and an optional token
space GUID are used in code for accessing a PCD's value.
Added 3.11.1 [UserExtensions.TianoCore."ExtraFiles"] Section
This is an optional section.
Defines the optional EDK II DEC file [UserExtensions.TianoCore."ExtraFiles"]
section tag. The EDK II build tools must not process any files listed in this
section.
Summary
This section is used by the Intel(r) UEFI Packaging Tool that is distributed as
part of the EDK II BaseTools, to locate files listed under this section header
and add them to the UEFI distribution package. When installing a UEFI
distribution package, these files will be installed in the package's directory
tree.
Prototype
<UserExtensions> ::= "[UserExtensions" <TcEf> "]" <EOL> <FileNames>*
<TcEf> ::= ".TianoCore." <DblQuote> "ExtraFiles" <DblQuote>
<FileNames> ::= <TS> [<RelativePath>] <File> <EOL>
Parameters
FileNames
Paths listed in the filename elements of the this section must be relative to
the directory the DEC file resides in. Use of "..", "." and "../" in the
directory path is not permitted.
Example
[UserExtensions.TianoCore."ExtraFiles"]
Readme.txt
From: Felix Poludov [mailto:fel...@ami.com]
Sent: Thursday, August 07, 2014 8:57 AM
To: edk2-devel@lists.sourceforge.net<mailto:edk2-devel@lists.sourceforge.net>
Subject: Re: [edk2] INF/DEC file updates to EDK II packages
Mike,
Why localized module name and localized module abstract/description are in two
separate UNI files?
Thanks
Felix
From: Kinney, Michael D [mailto:michael.d.kin...@intel.com]
Sent: Wednesday, August 06, 2014 9:22 PM
To: edk2-devel@lists.sourceforge.net<mailto:edk2-devel@lists.sourceforge.net>
Subject: Re: [edk2] INF/DEC file updates to EDK II packages
Tim,
I should have put it in the original email. The spec changes will be shared
too. We welcome review comments on all spec changes and patches.
Thanks,
Mike
From: Tim Lewis [mailto:tim.le...@insyde.com]
Sent: Wednesday, August 06, 2014 2:58 PM
To: edk2-devel@lists.sourceforge.net<mailto:edk2-devel@lists.sourceforge.net>
Subject: Re: [edk2] INF/DEC file updates to EDK II packages
Mike --
Since there are dozens of tools in the industry that consume these files, don't
you think its better to put the specification changes out where the consumers
can read, evaluate and comment on them? I realize that "UserDefined" sections
should be skipped by tools (agreed) but that doesn't mean that other module
creators might have made similar or related extensions or want to understand
how these changes play into their tools.
Regards,
Tim
________________________________
From: Kinney, Michael D [michael.d.kin...@intel.com]
Sent: Wednesday, August 06, 2014 2:31 PM
To: edk2-devel@lists.sourceforge.net<mailto:edk2-devel@lists.sourceforge.net>
Subject: [edk2] INF/DEC file updates to EDK II packages
Hello,
I wanted to let everyone know about a number of patch reviews for EDK II
packages that will be sent out over the next couple of weeks. These patches
impact the order of content in INF/DEC files and comment blocks in INF/DEC
files, and should not have any build or functionality impacts. These patches
will address the following issues:
1) Usage information in INF file comment blocks are either incomplete or
incorrect. This includes usage information for
Protocols/PPIs/GUIDs/PCDs/HOBs/Events/BootModes. The syntax for usage
information in comment blocks is defined in the EDK II Module Information (INF)
Specification
2) Add MODULE_UNI_FILE to INF [Defines] section along with UNI file that
contains the localized Abstract and Description of a module.
a. Addresses an information gap between INF files and the UEFI
Distribution Packaging Specification XML schema
b. There will be an associated update to UPT in BaseTools to consume
MODULE_UNI_FILE and associated UNI file during UDP creation that performs the
INF -> XML conversion.
c. There will be an associated update to UPT in BaseTools to produce
MODULE_UNI_FILE and associated UNI file during UDP installation that performs
the XML -> INF conversion.
3) Add [UserExtensions.TianoCore."ExtraFiles"] section to INF files along
with associated UNI file that provides the localized Name of a module.
a. [UserExtensions.TianoCore."ExtraFiles"] provides an easy method for a
module to specify extra files not listed in [Sources] or [Binaries] sections to
be added to a UDP without having to list the files in the UPT package
information data file.
b. There will be an associated update to UPT in BaseTools to package up
files listed in [UserExtensions.TianoCore."ExtraFiles"] during UDP creation.
c. UNI file contains localized name of a module to go along with the
localized Abstract and Description from the MODULE_UNI_FILE.
4) PCD information in DEC file comment blocks are either incomplete or
incorrect. This includes detailed description, @Prompt, @ValidRange,
@ValidList, @Expression, and [Error.<TokenSpaceGuid>] validation error messages
5) Add PACKAGE_UNI_FILE to DEC [Defines] section along with UNI file that
contains the localized Abstract and Description of a package and localized
strings associated with PCDs.
a. Addresses an information gap between DEC files and the UEFI
Distribution Packaging Specification XML schema
b. There will be an associated update to UPT in BaseTools to consume
PACKAGE_UNI_FILE and associated UNI file during UDP creation that performs the
DEC -> XML conversion.
c. There will be an associated update to UPT in BaseTools to produce
PACKAGE_UNI_FILE and associated UNI file during UDP installation that performs
the XML -> DEC conversion.
6) Add [UserExtensions.TianoCore."ExtraFiles"] section to DEC files along
with associated UNI file that provides the localized Name of a package.
a. [UserExtensions.TianoCore."ExtraFiles"] provides an easy method for a
package to specify extra files to be added to a UDP without having to list the
files in the UPT package information data file.
b. There will be an associated update to UPT in BaseTools to package up
files listed in [UserExtensions.TianoCore."ExtraFiles"] during UDP creation.
c. UNI file contains localized name of a package to go along with the
localized Abstract and Description from the PACKAGE_UNI_FILE.
7) Make sure order of DEC/INF content matches the order that UPT generates
in the XML -> INF conversion
a. This allows UDP packages installed by UPT to be compared against EDK II
trunk/branches using standard diff utilities.
Patches for the following EDK II packages are being prepared
1) MdePkg
2) MdeModulePkg
3) IntelFrameworkPkg
4) IntelFrameworkModulePkg
5) FatPkg
6) ShellPkg
7) PcAtChipsetPkg
8) UefiCpuPkg
9) SourceLevelDebugPkg
10) CryptoPkg
11) SecurityPkg
12) NetworkPkg
Best regards,
Mike
The information contained in this message may be confidential and proprietary
to American Megatrends, Inc. This communication is intended to be read only by
the individual or entity to whom it is addressed or by their designee. If the
reader of this message is not the intended recipient, you are on notice that
any distribution of this message, in any form, is strictly prohibited. Please
promptly notify the sender by reply e-mail or by telephone at 770-246-8600, and
then delete or destroy all copies of the transmission.
------------------------------------------------------------------------------
Want fast and easy access to all the code in your enterprise? Index and
search up to 200,000 lines of code with a free copy of Black Duck
Code Sight - the same software that powers the world's largest code
search on Ohloh, the Black Duck Open Hub! Try it now.
http://p.sf.net/sfu/bds
_______________________________________________
edk2-devel mailing list
edk2-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/edk2-devel
