Mike -
Yes, but until you said it in this e-mail it isn't clear that these are tied
together or separate.
I suggest that the .DEC and .INF file documentation start calling these things
out as attributes of objects. The object is the module. The attributes are the
"Abstract" the "Description" the "Module Format Version" Same with PCDs. Then
you can describe how they can be set. And the grammar items then refer back to
the attribute. An example of this (not great, I admit) are in chapter 29 of the
UEFI spec where the different object types (Forms, Questions, Statements,
Expressions) are listed out with their attributes.
Another example that needs to be cleared up: what is DynamicEx, or FixedAtBuild
or FeatureFlag. It is obviously an attribute of individual PCDs, but it is
never given a clear, uniformly-used name. It isn't type (that normally is used
to refer to the UINT8, VOID* sort of information). We've started using the term
"Storage Type" to describe it to customers. Not great, but at least I can say
"The storage type of the PCD can be set to Dynamic or FixedAtBuild since these
are both listed in the section header in the .DEC file."
As for the font info in the strings, we can have that discussion separately
(actually, we probably have had it at one point). My point was: the formatting
codes can be embedded using escape sequences today, since they are characters,
but I think you might want to specify what can or may not be used in the meta
data.
Tim
From: Kinney, Michael D [mailto:michael.d.kin...@intel.com]
Sent: Friday, August 08, 2014 2:26 PM
To: edk2-devel@lists.sourceforge.net
Subject: Re: [edk2] INF/DEC file updates to EDK II packages
Tim,
The EDK II Module Information (INF) File Specification 1.22 Errata D Section
3.3 on tianocore.org defines the following format for an INF header that
includes support for the ASCII versions of the Abstract and Description. The
optional UNI file associated with an INF can provide localized versions of the
Abstract and Description using the string token names of STR_MODULE_ABSTRACT
and STR_MODULE_DESCRIPTION.
Summary
This section contains Copyright and License notices for the INF file in
comments that start the file. This section is optional using a format of:
## @file
# Abstract
#
# Description
#
# Copyright
#
# License
#
##
Here is the example from the MdeModulePkg/Universal/Disk/DiskIoDxe module with
an associated UNI file.
DiskIoDxe.inf
============
## @file
# Module that lays Disk I/O protocol on every Block I/O protocol.
#
# This module produces Disk I/O protocol to abstract the block accesses
# of the Block I/O protocol to a more general offset-length protocol
# to provide byte-oriented access to block media. It adds this protocol
# to any Block I/O interface that appears in the system that does not
# already have a Disk I/O protocol. File systems and other disk access
# code utilize the Disk I/O protocol.
#
# Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR>
# This program and the accompanying materials
# are licensed and made available under the terms and conditions of the BSD
License
# which accompanies this distribution. The full text of the license may be
found at
# http://opensource.org/licenses/bsd-license.php
#
# THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
# WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
#
##
[Defines]
. . .
MODULE_UNI_FILE = DiskIoDxe.uni
. . .
DiskIoDxe.uni
===========
#string STR_MODULE_ABSTRACT #language en-US "Lays Disk I/O protocol
on every Block I/O protocol"
#string STR_MODULE_DESCRIPTION #language en-US "This module produces
Disk I/O protocol to abstract the block accesses "
"of the
Block I/O protocol to a more general offset-length protocol "
"to
provide byte-oriented access to block media. It adds this protocol "
"to any
Block I/O interface that appears in the system that does not "
"already have a Disk
I/O protocol. File systems and other disk access "
"code
utilize the Disk I/O protocol."
We have considered the case where strings are provided in the ASCII formatted
INF/DEC files and the same strings (with potentially different string contents)
are provided in an associated UNI file. We are proposing that the UPT tool
that is responsible for the INF/DEC/UNI -> XML and XML -> INF/DEC/UNI
translations assume that strings in the ASCII formatted INF/DEC have an RFC
1766 language code of en-US. If the same string is also declared in a UNI file
with the same language code of en-US, then there is a potential conflict. We
prefer that content that a developer chose to put into the INF/DEC/UNI files
are preserved across the XML translations. Our proposal is to store both
versions of the en-US strings in XML. This is accomplished by introducing an
extended language code following the format defined by RFC 1766 of
en-x-tianocore. This language code is used to store the INF/DEC strings that
potentially conflict with UNI file string so the XML carries both of them.
When converting from XML back to INF/DEC, the INF/DEC file will get the strings
contents from the en-x-tianocor strings if they are present, and en-US strings
if en-x-tianocore strings are not present. When converting from XML to UNI,
the strings with the extended language code of en-x-tianocore are ignored, so
the original UNI file contents are preserved.
Best regards,
Mike
From: Tim Lewis [mailto:tim.le...@insyde.com]
Sent: Friday, August 08, 2014 1:44 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 -
Can you show how the module abstract could be encoded purely in the .inf? I can
see how PCDs work. Are you saying these .uni strings would replace that which
appears in the .inf header?
Tim
From: Kinney, Michael D [mailto:michael.d.kin...@intel.com]
Sent: Friday, August 08, 2014 1:34 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 think we are in agreement here. Detailed responses embedded below in [Mike].
I have provided more details on proposed syntax below along with some sample
UNI file content. The EDK II specifications require updates to define the
string token naming conventions for the UNI files associated with Packages and
Modules.
Thanks,
Mike
From: Tim Lewis [mailto:tim.le...@insyde.com]
Sent: Friday, August 08, 2014 11:58 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 -
Let me propose an alternative which simplifies the 99% of module development:
put the strings that you want in the .dec/.inf file directly with an option to
extend it through .uni files.
[Mike] I agree with your proposal. Strings can be put in ASCII formatted DEC
files using @Prompt. The UNI files being proposed here are always optional.
The EDK II Package Declaration (DEC) File Format Specification 1.22 Errata C
Section 3.10 posted under the EDK II project on tianocore.org defines syntax
for tags associated with PCDs for @Prompt, @ValidRange, @ValidList,
@Expression. We want to maximize the use of these tags. The UNI files provide
a method to carry strings that cannot be encoded in ASCII. We are providing
the UNI file too for these patches, so the strings can be translated to other
languages as needed.
You already mentioned @Prompt (which, by the way, might have been better than
UserDefined and made it more consistent) There are hundreds of files that
follow the existing meta-data format as defined in the .dec spec. I can already
provide non-localized content there and any use of these .uni files will have
to find some way to attach to the related PCD through naming convention. In
order to support existing files, your tools will already need to process this
information. So you will always have a mix of meta-data descriptive text IN the
.inf/.dec and out of the .inf/.dec because of this. You can give the .uni file
priority where there is an overlap in order to allow vendors with
multi-language meta-data display tools support it.
[Mike] I agree. If a string for same language is present in both INF/DEC and
UNI file, the UNI file should have higher priority.
Separating the .uni files defeats some of your re-use arguments below. Make it
easier on the developer. Make the tools do the heavy lifting. Solve the problem
rather than passing it on.
[Mike] Each developer for a package/module can decide what content they
provide. If they only want to do ASCII English strings, then those can be
provided in INF/DEC with no UNI file. If they want to provide more than just
English, then a UNI file can be provided. It is also possible for tools to
extract strings from INF/DEC and generate a UNI file with English strings for
translations services. Many options here and developers can opt-in to levels
of support.
Speaking of naming and content conventions:
1) There is no mention of what will be done with font-related
information. Will bold escape characters work? While EDK2 has never really
supported these, you might consider explicitly limiting to no font-information
or ???
[Mike] You are correct that the EDK II ASCII/UNI meta-data formats for strings
do not provide font information today. If you think this is a gap or a
valuable addition to the EDK II, then please provide some proposals.
2) You mention @Prompt related .uni, but Larry's update does not give the
contents of these files. Let's be explicit about this up-front and say that
strings in these files must have the name X_Y_Z in order to be correctly
associated with some specific meaning.
[Mike] Here is some sample content for MdePkg.dec and its optionally associated
MdePkg.uni file. A UNI file can be optionally declared in PACKAGE_UNI_FILE
listed in [Defines] section of DEC file. In the UNI file, the string token
names of STR_PACKAGE_ABSTACT and STR_PACKAGE_DESCRIPTION are used to store
additional localized strings in the UDP XML package header. In the DEC file
for a PCD, the comment block contents without @ tags are the detailed help text
that can be converted to additional UDP PCD HelpText XML. The DEC file
contents with @ tags in the PCD comment block are also converted to associated
XML sections. In the UNI file, the string token name formats of
STR_<PcdTokenSpaceGuidName>_<PcdTokenName>_PROMPT and
STR_<PcdTokenSpaceGuid>_<PcdTokenName>_HELP are used to store additional
localized strings in the UDP XML for PCDs. The string token name format of
STR_<PcdTokenSpaceGuidName>_ERR_<ErrorCode> is used to store additional
localized error message strings in the UDP XML for PCD error codes. Is string
for same language is present in both DEC and UNI, then the UNI one
MdePkg.dec
==========
[Defines]
. . .
PACKAGE_UNI_FILE = MdePkg.uni
. . .
#
# [Error.gEfiMdePkgTokenSpaceGuid]
# 0x80000001 | Invalid value provided.
#
. . .
[PcdsFixedAtBuild, PcdsPatchableInModule, PcdsDynamic, PcdsDynamicEx]
. . .
## Indicates the default baud rate of UART.
# @Prompt Default UART Baud Rate.
# @ValidList 0x80000001 | 115200, 57600, 38400, 19200, 9600, 7200, 4800,
3600, 2400, 2000, 1800, 1200, 600, 300, 150, 134, 110, 75, 50
gEfiMdePkgTokenSpaceGuid.PcdUartDefaultBaudRate|115200|UINT64|0x00000020
MdePkg.uni
==========
#string STR_PACKAGE_ABSTRACT
#language en-US
"Package providing all definitions, library classes and libraries instances"
#string STR_PACKAGE_DESCRIPTION
#language en-US
"It also provides the definitions(including PPIs/PROTOCOLs/GUIDs) of "
"EFI1.10/UEFI2.3.1/PI1.2 and some Industry Standards."
#string STR_gEfiMdePkgTokenSpaceGuid_ERR_80000001
#language en-US
"Invalid value provided."
#string STR_gEfiMdePkgTokenSpaceGuid_PcdUartDefaultBaudRate_PROMPT
#language en-US
"Default UART Baud Rate"
#string STR_gEfiMdePkgTokenSpaceGuid_PcdUartDefaultBaudRate_HELP
#language en-US
"Indicates the default baud rate of UART. "
From: Kinney, Michael D [mailto:michael.d.kin...@intel.com]
Sent: Friday, August 08, 2014 11:10 AM
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 agree that UTF-8 formatted files can support localized string, but INF/DEC
files are current defined to be ASCII.
We are attempting to find a balance that works for both developers and tools.
We are re-using the .UNI file format on purpose so developers who are already
using .UNI files will not have to learn a new method to implement localizes
strings. This reduces the number of file formats for the same type of content.
Also, the PCD related information such as PROMPT, HELP, and ERROR messages can
be captured in a .UNI file associated with a DEC file, and that content can be
reused in HII content "as is" for PCDs that may be mapped to HII string packs
associated with HII setup questions. This reduces translations between
different file formats.
Also, translation services for localized strings may already support .UNI files
associated with HII, and those services will not have to be updated to support
more file formats if we simple reuse .UNI file format.
Thanks,
Mike
From: Tim Lewis [mailto:tim.le...@insyde.com]
Sent: Friday, August 08, 2014 10:47 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 -
Perhaps developer complexity should be the metric used for these choices, not
tool complexity. Tool complexity is dealt with once, developer complexity is an
on-going effort.
It is not clear why .uni files are used at all. These are not consumed by
drivers, are they? Nor are they installed in the HII database. This overrides
the .uni purpose and definition without giving the convenience of even
combining them together. Why not just add it to the [UserDefined] section of
the .dec directly? UTF-8 can handle the language text necessary, and is not
difficult to add to current processing tools. This essentially requires
packages to go from 1 to 2 files and modules to go from 1 to 2 (I know they are
optional, but we are talking about "well-constructed")
Tim
From: Kinney, Michael D [mailto:michael.d.kin...@intel.com]
Sent: Friday, August 08, 2014 10:33 AM
To: edk2-devel@lists.sourceforge.net<mailto:edk2-devel@lists.sourceforge.net>
Subject: Re: [edk2] INF/DEC file updates to EDK II packages
Felix,
This is a very good question.
The UEFI Distribution Packaging Specification 1.0 (Errata B) available from
uefi.org and its associated XML schema has support to store localized Abstract
and localized Description. However, there is no XML schema support to store
the localized Module Name. We think it may be a good idea to separate the
content that is formally supported by the XML schema from the content that is
not formally supported by the XML schema, so the UPT tool that converts EDK II
Meta-Data files to XML and from XML back to EDK II Meta-Data files will be
straight forward. We were very concerned about the complexity of the UPT tool
if there was a single EDK II UNI file that contains some strings that would be
translated into XML and other strings that needed to be packaged up as pass
through. Then during package installation UTP would have to generate some UNI
strings from XML and mix those back together with the pass through content.
Thanks,
Mike
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 it's 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
