Jaben - There were three pieces of this (which were all geared towards making the grammar easier to read by humans without losing specified behavior)
1) Removed some items out of the grammar. This included all conditionals. In many case the generic "identifier" was substituted and the valid values were listed (with a description!) in a table along with specific values in the individual grammar sections. There are other items, like file names with specific file extensions in the grammar. This greatly reduced the number of terminals. 2) Broke down some sections further. This allowed the grammar to be digested more easily. (see the FV section in the FDF spec (3.6) where each of the statements became a sub-section). This is similar to what the VFR specification tried to do. Since in #1 we'd moved many keywords out, this is where we'd put the tables to list valid identifier values and a description, showing what it means or which opcode/specification data structure it is tied to. 3) Made the formatting easier to read. I know that the current format is related to the one fed into the tools, but with a little work it in formatting helps. There were three major pieces of this: a. first, replace <X> with X (italics) b. second, removal of the <TS> terminal. Moved the whitespace rules into the introductory information where comments are described. This allowed some other rules to be simplified, since "X" <Eq> "Y" could become "=" c. Replace simple terminals with their literals. EX: Why <FieldSeparator> when you can use "|"? I replaced CRLF with <EOL> Hope this helps, Tim From: Carsey, Jaben [mailto:[email protected]] Sent: Thursday, August 14, 2014 8:39 AM To: [email protected]; Hauch, Larry Subject: Re: [edk2] EDK II UNI Unicode File Specification Update Tim, Can you elaborate on your rewrite? What needed to be done... What do you think of having a shared "EBNF Document" that stores all the shared EBNF items? -Jaben From: Tim Lewis [mailto:[email protected]] Sent: Tuesday, August 12, 2014 3:46 PM To: Hauch, Larry Cc: [email protected]<mailto:[email protected]> Subject: Re: [edk2] EDK II UNI Unicode File Specification Update Larry - As a tools developer and a QA team, we (Insyde) can tell you that the existing EBNF is hard to manage. We have rewritten it to be readable by tools and by humans. When you start having conditions in the grammar (see the INF spec, section 3.2), you know you've definitely crossed the line. I think the core items, like Expressions and PCDs can be defined in the EDK2 Build Specification. I think that the Expression syntax could be there also, in an appendix. The PCD syntax is not shared, so we'd parcel that out to the relevant .fdf/.inf/.dsc/.dec specifications but refer back to the Build spec for definition for common terms. Tim From: Hauch, Larry [mailto:[email protected]] Sent: Tuesday, August 12, 2014 3:22 PM To: Tim Lewis Cc: [email protected]<mailto:[email protected]> Subject: RE: EDK II UNI Unicode File Specification Update Hi Tim, I agree that the EBNF is getting cumbersome and we should really look at reducing this. I need to work with my internal development and validation teams (who keep asking for more EBNF) to figure out a better method. Our validation team has expressed the desire to have everything in one place so that they can only look at the EBNF and not have to look at anything else. I agree that we would be better served if we could centralize some of the documentation so that we update the PCD document to contain all of the relevant information to a PCD document and then have the other specs refer to appropriate chapters in the other documents. (I was attempting to do that with the EDK II Meta-Data Expression Spec document which I hope to publish shortly - newer versions of the EDK II INF/DEC/DSC/FDF specs will have the expression EBNF removed and a reference to the Expression Spec.). Cheers, Larry From: Tim Lewis [mailto:[email protected]] Sent: Monday, August 11, 2014 3:03 PM To: [email protected]<mailto:[email protected]> Subject: Re: [edk2] EDK II UNI Unicode File Specification Update It is about using EBNF for specific string-token name patterns. In cases where the basic pattern is X = Y (as described in the overview portions of the same spec) the grammar is much simpler and easier to ready if it says <TS> Identifier <TS> "=" <TS> Value. The question: "which X is valid" and "which Y is valid for which X" is easily taken care of in the sections. Again, this is speaking as another company has worked valiantly to create tools compatible with the EDK2 toolset, and to teach the grammar to new engineers. On the other topic, we would be willing to contribute changes on specific documents, such as the Build Specification. Do you think it is better to describe such topics as PCDs where they are defined (.DEC spec) or as a general build concept (Build spec)? Tim From: Kinney, Michael D [mailto:[email protected]] Sent: Monday, August 11, 2014 12:27 PM To: [email protected]<mailto:[email protected]> Subject: Re: [edk2] EDK II UNI Unicode File Specification Update Hi Tim, Thanks for the feedback on this topic. We have had similar discussions over the last couple of days for where this content should be listed. These updates do reserve specific string token name patterns. Whenever we have used specific keywords in syntax in the other EDK II related documents, the keywords have been added as part of the grammar using an EBNF description. This provides clear direction for tool development and tool validation. Is your feedback about the location of this content, or the use of EBNF to for the string token name patterns? Thanks, Mike From: Tim Lewis [mailto:[email protected]] Sent: Monday, August 11, 2014 11:23 AM To: [email protected]<mailto:[email protected]> Subject: Re: [edk2] EDK II UNI Unicode File Specification Update Larry - I would recommend that these sort of changes not be added to the grammar, but rather in the specification text related to the [UserDefined] or DEFINES section of the .inf or .dec specification. Tim From: Hauch, Larry [mailto:[email protected]] Sent: Monday, August 11, 2014 10:56 AM To: [email protected]<mailto:[email protected]> Subject: [edk2] EDK II UNI Unicode File Specification Update Hi Folks, The following is content we would like to add to the EDK II UNI Unicode File Specification to support the changes we have proposed for supporting localization in EDK II that can be consumed by the packaging to when creating a UEFI PI Distribution Package (and when installing a UEFI PI Distribution Package using the EDK II upt tool). Please respond with feedback the end of this week. Thanks, Larry 3 UNI File Common Content This section defines the common tag syntax for content in a Unicode file specified in the following Module and Package UNI sections. Prototype <US> ::= L" " <MS> ::= <US>+ <ME> ::= {<MS>} {<EOL>} <CR> ::= 0x000D <LF> ::= 0x000A <EOL> ::= <CR><LF> <BlankLine> ::= <EOL> <PChars> ::= (0x0020-0xF6FF) <LangCode> ::= <RFC4646> <RFC4646> ::= (\ua-\uz\uA-\uZ){2,8} [L"-" (\ua-\uz\uA-\uZ\u0-\u9){2,8}] <UDblQuote> ::= 0x0022 <String> ::= <UDblQuote> <PChars>* <UDblQuote> <Header> ::= L"// /** @file" <EOL> [<Abstract> <EOL>]? [L"//" <EOL>]+ [<Description> <EOL>]* [L"//" <EOL>] [<Copyright> <EOL>]+ [L"//" <EOL>]* [<License> <EOL>]+ [L"//" <EOL>]* L"// **/" <EOL>+ <Abstract> ::= L"//" <MS> <PChars>+ <Description> ::= L"//" <MS> <PChars>+ <Copyright> ::= L"//" <MS> "Copyright (c)" <MS> <Date> <Date> ::= {<Year>} {<YearRange>} {<YearList>} L"," <US> <Comp> <Year> ::= (\u2-\u9) (\u0-\u9){3} <YearRange> ::= <Year> <US> L"-" <US> <Year> <YearList> ::= <Year> ["," <US> <Year>]+ <Comp> ::= <PChars>* L"." <MS> L"All rights reserved.<BR>" <License> ::= L"//" <MS> <PChars>* <LangEntry> ::= L"#language" <MS> <LangCode> <ME> [<String> <ME>]+ 4 MODULE_UNI_FILE Content This section defines the tag syntax for content in a Unicode file specified in the MODULE_UNI_FILE entry of an INF file's [Defines] section. Prototype <InfUnicodeFile> ::= <Header> <BlankLine>* <AbstractTag>? <BlankLine>* <DescriptionTag>? <BlankLine>* <AbstractTag> ::= L"#string" <MS> L"STR_MODULE_ABSTRACT" <ME> <LangEntry>+ <DescriptionTag> ::= L"#string" <MS> L"STR_MODULE_DESCRIPTION" <ME> <LangEntry>+ Example // /** @file // TerminalDxe Module Localized Abstract and Description Content // // Copyright (c) 2012 - 2014, 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. // // **/ #string STR_MODULE_ABSTRACT #language en-US "Terminal module installs Simple Text Input(ex)/Out protocols for serial " "devices." #string STR_MODULE_DESCRIPTION #language en-US "This module will install Simple Text Input (Ex) protocol and Simple Test " "Output protocols based on Serial I/O protocol for serial devices including " "hotplug serial devices." 5 Module Extra File Content This section defines the tag syntax for content in a Unicode file specified in an extra file specified in a [UserExtensions.TianoCore."ExtraFiles"] section of an INF file. Prototype <InfUnicodeFile> ::= <Header> <BlankLine>* <PropertyName>? <BlankLine>* <PropertyName> ::= L"#string" <MS> L"STR_PROPERTIES_MODULE_NAME" <ME> <LangEntry>+ Example // /** @file // TerminalDxe Localized Strings and Content // // Copyright (c) 2013, 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. // // **/ #string STR_PROPERTIES_MODULE_NAME #language en-US "Terminal DXE Driver" 6 PACKAGE_UNI_FILE Content This section defines the tag syntax for content in a Unicode file specified in the PACKAGE_UNI_FILE entry of a DEC file's [Defines] section. Prototype <DecUnicodeFile> ::= <Header> <BlankLine>* <AbstractTag>? <BlankLine>* <DescriptionTag>? <BlankLine>* <PcdErrorTags>* <BlankLine>* <PcdHelpTags>* <BlankLine>* <PcdPromptTags>* <BlankLine>* <AbstractTag> ::= L"#string" <MS> L"STR_PACKAGE_ABSTRACT" <ME> <LangEntry>+ <DescriptionTag> ::= L"#string" <MS> L"STR_PACKAGE_DESCRIPTION" <ME> <LangEntry>+ <ENO> ::= (\u0-\u9\ua-\uf\uA-\uF){8} <PcdErrorTags> ::= L"#string" <MS> L"STR_" <Tsp> L"_ERR_" <ENO> <ME> <LangEntry>+ <Tsp> ::= <TokenSpaceGuidCName> <PcdName ::= <CName> <TokenSpaceGuidCName> ::= <CName> <PCD> ::= <TokenSpaceGuidCName> L"_" <PcdName> <CName> ::= (\ua-\uz\uA-\uZ) (\ua-\uz\uA-\uZ\u0-\u9)* <PcdHelpTags> ::= L"#string" <MS> L"STR_" <PCD> L"_HELP" <ME> <LangEntry>+ <PcdPromptTags> ::= L"#string" <MS> L"STR_" <PCD> L"_PROMPT" <ME> <LangEntry>+ Example // /** @file // Package help, error and prompt strings. // // Copyright (c) 2013 - 2014, 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. // // **/ #string STR_PACKAGE_ABSTRACT #language en-US "This package provides network modules that conform to UEFI 2.2 specification." #string STR_PACKAGE_DESCRIPTION #language en-US "This package provides network modules that conform to UEFI 2.2 specification." #string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecCertificateEnabled_PROMPT #language en-US "Enable IPsec IKEv2 Certificate Authentication." #string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecCertificateEnabled_HELP #language en-US "Indicates if the IPsec IKEv2 Certificate Authentication feature is enabled or not.<BR><BR>" "TRUE - Certificate Authentication feature is enabled.<BR>" "FALSE - Does not support Certificate Authentication.<BR>" #string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCaFile_PROMPT #language en-US "CA file." #string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCaFile_HELP #language en-US "CA certificate used by IPsec." #string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCaFileSize_PROMPT #language en-US "CA file's size." #string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCaFileSize_HELP #language en-US "CA certificate file's size." #string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCertificate_PROMPT #language en-US "Pubic Key for remote peer." #string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCertificate_HELP #language en-US "X509 certificate as Public Key which is used by IPsec (DER format)" #string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCertificateSize_PROMPT #language en-US "Pubic Key's size." #string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCertificateSize_HELP #language en-US "X509 certificate as Public Key's size." #string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCertificateKey_PROMPT #language en-US "Private Key." #string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCertificateKey_HELP #language en-US "Private Key used by IPsec (PEM format)." #string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCertificateKeySize_PROMPT #language en-US "Private Key's size." #string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCertificateKeySize_HELP #language en-US "Private Key's size." 7 Package Extra File Content This section defines the tag syntax for content in a Unicode file specified in the entry of a DEC file's [UserExtensions.TianoCore. "ExtraFiles"] section. Prototype <DecUnicodeFile> ::= <Header> <BlankLine>* <PropertyName>? <PropertyName> ::= L"#string" <MS> L"STR_PROPERTIES_PACKAGE_NAME" <ME> <LangEntry>+ Example // /** @file // Network Package Localized Strings and Content. // // Copyright (c) 2013 - 2014, 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. // // **/ #string STR_PROPERTIES_PACKAGE_NAME #language en-US "Network package" Larry Hauch Intel Corporation SSG, STO, Platform Software Infrastructure 2800 Center Dr. DuPont, WA 98327 Work: (253) 371-8550
------------------------------------------------------------------------------
_______________________________________________ edk2-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/edk2-devel
