From nobody Sat Nov 2 10:21:29 2024 Delivered-To: importer@patchew.org Received-SPF: none (zoho.com: 198.145.21.10 is neither permitted nor denied by domain of lists.01.org) client-ip=198.145.21.10; envelope-from=edk2-devel-bounces@lists.01.org; helo=ml01.01.org; Authentication-Results: mx.zoho.com; spf=none (zoho.com: 198.145.21.10 is neither permitted nor denied by domain of lists.01.org) smtp.mailfrom=edk2-devel-bounces@lists.01.org; Return-Path: Received: from ml01.01.org (ml01.01.org [198.145.21.10]) by mx.zohomail.com with SMTPS id 1493082623898508.5328390867277; Mon, 24 Apr 2017 18:10:23 -0700 (PDT) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id 8488A20D770D2; Mon, 24 Apr 2017 18:10:12 -0700 (PDT) Received: from mga14.intel.com (mga14.intel.com [192.55.52.115]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id 3BB6921954084 for ; Mon, 24 Apr 2017 18:10:11 -0700 (PDT) Received: from fmsmga006.fm.intel.com ([10.253.24.20]) by fmsmga103.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 24 Apr 2017 18:10:11 -0700 Received: from mdkinney-mobl.amr.corp.intel.com ([10.241.98.36]) by fmsmga006.fm.intel.com with ESMTP; 24 Apr 2017 18:10:10 -0700 X-Original-To: edk2-devel@lists.01.org X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.37,247,1488873600"; d="scan'208";a="93697960" From: Michael Kinney To: edk2-devel@lists.01.org Date: Mon, 24 Apr 2017 18:10:06 -0700 Message-Id: <1493082606-9348-5-git-send-email-michael.d.kinney@intel.com> X-Mailer: git-send-email 2.6.3.windows.1 In-Reply-To: <1493082606-9348-1-git-send-email-michael.d.kinney@intel.com> References: <1493082606-9348-1-git-send-email-michael.d.kinney@intel.com> Subject: [edk2] [ edk2-DecSpecification PATCH 4/4] Declarations not allowed to be both public and private X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.22 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Kevin W Shaw , Liming Gao MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Errors-To: edk2-devel-bounces@lists.01.org Sender: "edk2-devel" X-ZohoMail: RSF_4 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" https://bugzilla.tianocore.org/show_bug.cgi?id=3D482 Clarify that Includes, Protocols, PPIs, and GUIDs declared in and a DEC file are now allowed to be both public and private. If this condition is detected the build tools must terminate with an error. Cc: Liming Gao Cc: Yonghong Zhu Cc: Kevin W Shaw Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Michael Kinney --- 3_edk_ii_dec_file_format/35_[includes]_sections.md | 16 ++ 3_edk_ii_dec_file_format/36_[guids]_sections.md | 15 ++ .../37_[protocols]_sections.md | 15 ++ 3_edk_ii_dec_file_format/38_[ppis]_sections.md | 15 ++ README.md | 183 +++++++++++------= ---- 5 files changed, 153 insertions(+), 91 deletions(-) diff --git a/3_edk_ii_dec_file_format/35_[includes]_sections.md b/3_edk_ii_= dec_file_format/35_[includes]_sections.md index 6fa083c..ed5acea 100644 --- a/3_edk_ii_dec_file_format/35_[includes]_sections.md +++ b/3_edk_ii_dec_file_format/35_[includes]_sections.md @@ -94,6 +94,22 @@ build tools must terminate with an error message. =20 For example, `[Includes.common, Includes.IA32.Private]` is prohibited. =20 +It is NOT permissible for the same include directory to be listed in secti= on +tags with and without the `Private` modifier. If this condition is detecte= d, +the build tools must terminate with an error message. + +For example, the following is prohibited because the same directory called +`MyPrivateIncludePath` is listed in a tag with and without a `Private` +modifier. + +``` +[Includes] + MyPrivateIncludePath + +[Includes.common.Private] + MyPrivateIncludePath +``` + #### Example =20 ```ini diff --git a/3_edk_ii_dec_file_format/36_[guids]_sections.md b/3_edk_ii_dec= _file_format/36_[guids]_sections.md index 1d00c9a..6a398ea 100644 --- a/3_edk_ii_dec_file_format/36_[guids]_sections.md +++ b/3_edk_ii_dec_file_format/36_[guids]_sections.md @@ -91,6 +91,21 @@ build tools must terminate with an error message. =20 For example, `[Guids.common, Guids.IA32.Private]` is prohibited. =20 +It is NOT permissible for the same GUID to be listed in section tags with = and +without the `Private` modifier. If this condition is detected, the build t= ools +must terminate with an error message. + +For example, the following is prohibited because the GUID named `MyPrivate= Guid` +is listed in a tag with and without a `Private` modifier. + +``` +[Guids] + MyPrivateGuid =3D { 0x1e96808b, 0xfa93, 0x4230, { 0xb5, 0x6b, 0x96, 0xc5= , 0x95, 0x9b, 0xd1, 0xd2 }} + +[Guids.common.Private] + MyPrivateGuid =3D { 0x1e96808b, 0xfa93, 0x4230, { 0xb5, 0x6b, 0x96, 0xc5= , 0x95, 0x9b, 0xd1, 0xd2 }} +``` + #### Example =20 ```ini diff --git a/3_edk_ii_dec_file_format/37_[protocols]_sections.md b/3_edk_ii= _dec_file_format/37_[protocols]_sections.md index a43260c..c1d7daf 100644 --- a/3_edk_ii_dec_file_format/37_[protocols]_sections.md +++ b/3_edk_ii_dec_file_format/37_[protocols]_sections.md @@ -90,6 +90,21 @@ build tools must terminate with an error message. =20 For example, `[Protocols.common, Protocols.IA32.Private]` is prohibited. =20 +It is NOT permissible for the same protocol to be listed in section tags w= ith +and without the `Private` modifier. If this condition is detected, the bui= ld +tools must terminate with an error message. + +For example, the following is prohibited because the protocol named +`MyPrivateProtocol` is listed in a tag with and without a `Private` modifi= er. + +``` +[Protocols] + MyPrivateProtocol =3D { 0xc7c4a20f, 0xd1d1, 0x427a, { 0xb0, 0x82, 0xa8, = 0xb6, 0x24, 0xf7, 0x69, 0x4f }} + +[Protocols.common.Private] + MyPrivateProtocol =3D { 0xc7c4a20f, 0xd1d1, 0x427a, { 0xb0, 0x82, 0xa8, = 0xb6, 0x24, 0xf7, 0x69, 0x4f }} +``` + #### Example =20 ```ini diff --git a/3_edk_ii_dec_file_format/38_[ppis]_sections.md b/3_edk_ii_dec_= file_format/38_[ppis]_sections.md index 87c5f0d..db83fc4 100644 --- a/3_edk_ii_dec_file_format/38_[ppis]_sections.md +++ b/3_edk_ii_dec_file_format/38_[ppis]_sections.md @@ -91,6 +91,21 @@ build tools must terminate with an error message. =20 For example, `[Ppis.common, Ppis.IA32.Private]` is prohibited. =20 +It is NOT permissible for the same PPI to be listed in section tags with a= nd +without the `Private` modifier. If this condition is detected, the build t= ools +must terminate with an error message. + +For example, the following is prohibited because the PPI named `MyPrivateP= pi` +is listed in a tag with and without a `Private` modifier. + +``` +[Ppis] + MyPrivatePpi =3D { 0x10ed6a18, 0xbbf7, 0x4051, { 0xba, 0xb8, 0xb4, 0x90,= 0x1a, 0x65, 0xa2, 0xc5 }} + +[Ppis.common.Private] + MyPrivatePpi =3D { 0x10ed6a18, 0xbbf7, 0x4051, { 0xba, 0xb8, 0xb4, 0x90,= 0x1a, 0x65, 0xa2, 0xc5 }} +``` + #### Example =20 ```ini diff --git a/README.md b/README.md index 372ef19..5eea1ad 100644 --- a/README.md +++ b/README.md @@ -76,94 +76,95 @@ Copyright (c) 2007-2017, Intel Corporation. All rights = reserved. =20 ### Revision History =20 -| Revision | Revision History = | Date = | -| ---------- | -----------------------------------------------------------= -------------------------------------------------------------- | ----------= ----- | -| 1.0 | Initial release. = | December 2= 007 | -| 1.1 | Updated based on errata = | August 200= 8 | -| 1.2 | Updated based on enhancement requests = | June 2009 = | -| 1.21 | Updated based on errata and for enhancement requests = | January 20= 10 | -| | Standardized the format for common content. = | = | -| | Added support for @Keyword Doxygen tag = | = | -| | Added support for @ModuleType Doxygen tags = | = | -| | Added support for @ValidList, @DefaultValue and @ValidRange= Doxygen tags for PCDs | = | -| | Added PKG_UNI_FILE element to [defines] section = | = | -| 1.22 | Errata and grammatical editing = | April 2010= | -| 1.22 w/ | Updates: = | December 2= 011 | -| Errata A | Updated to support UEFI version 2.3.1 and updated spec rele= ase dates in Introduction | = | -| | Clarify UEFI's PI Distribution Package Specification = | = | -| | Standardize Common data definitions for all specifications = | = | -| | Grammatical, formatting and spelling changes = | = | -| | Replaced "should" with wording saying that it is = | = | -| | "recommended" = | = | -| | Added EBNF for `` = | = | -| | Added scoping rules for Macros, clarified MACRO summary = | = | -| | Added an example of a binary only DEC file = | = | -| | Removed references to system environment variables in the M= acros section | = | -| | Specifically state where `` can be used, and wher= e it is prohibited; | = | -| | specifically state that MACROVAL entries are expanded where= they are used; | = | -| | clarify that MACROS are only expanded, not evaluated during= initial parsing of the DEC file | = | -| | Added table that shows that every part of a path name can b= e replaced by a MACROVAL | = | -| | Clarify that C data arrays must be byte arrays for PCD valu= e fields; prohibit C format and | = | -| | Registry Format GUID structures in VOID* PCD value fields = | = | -| | Update non-zero number is True, only 0 is consideered False= | = | -| | Prohibit specifying items as architecturally specific and a= lso common | = | -| | Changed `` to `` in = | = | -| | 3.4 = | = | -| | Defined `` as a `` for this release= (need to allow registry format in a future release) | = | -| | Update the [Includes], [Guids], [Protocols], [PPIs], [Libra= ryClasses] and PCD sections to allow an empty section | = | -| | Updated the format for ``, `` and `<= UnicodeString>` | = | -| | Update PATH related EBNF = | = | -| | Add `` to [Defines], [Includes] and = | = | -| | `[LibraryClasses] sections` = | = | -| | Provide rules in 2.2.6 for how macros can be shared between= different subsections | = | -| 1.22 w/ | Updates: = | June 2012 = | -| Errata B | Added a + after `` in the DoxComment definition of= PCDs, as more than one expression can be | = | -| | specified in the UEFI PI Distribution Package Specification= . | = | -| | Added text describing the use of `` for error num= bers as well as how they are scoped. | = | -| 1.22 w/ | Updates: = | June 2012 = | -| Errata B | Updated UEFI/PI Spec version in chapter 1.3 to include Erra= ta letters. | = | -| (cont.) | In Section 3.10 modified the optional error number in = | = | -| | DoxComment definitions for PCDs from ``+ to = | = | -| | and defined to be of type ; | = | -| | also added a "\|" after the value to separate the error cod= e from numeric values | = | -| | Added AsBuilt entries for Abstract and Description = | = | -| | Clarified that the file must use the DOS end-of-line charac= ter sequence, `0x0D 0x0A` | = | -| 1.22 w/ | Updates: = | August 201= 3 | -| Errata C | Updated UEFI/PI Specification version support in chapter 1 = | = | -| | Modified examples to correct previous errors = | = | -| | Removed errors from text = | = | -| | Updated examples = | = | -| | Modified EBNF to prevent using the architectural modifier o= f common with any other architecture. | = | -| | Ensure that wording specifically states that the architectu= re modifiers are not case sensitive. | = | -| | Add description of PCD processing rules in section 3.10 = | = | -| | Allow registry format GUID values in GUIDs, Protocols, = | = | -| | PPIs sections instead of requiring C format GUID values = | = | -| | (which will continue to be allowed) = | = | -| | The error codes are scoped to the TokenSpaceGUID, not to th= e PCD | = | -| | Added reference to the EDK II Build Specification for PCD p= rocessing rules. | = | -| 1.24 | `Updates;` = | August 201= 4 | -| | Change revision number of this specification from 1.22 to = | = | -| | 1.24 = | = | -| | Updated `DEC_SPECIFICATION` to `0x00010017` = | = | -| | Added additional parameter definitions for clarification of= the comment content for PCDs | = | -| | Added the `PACKAGE_UNI_FILE` entry to the `[Defines]` secti= on | = | -| | Added reserved TianoCore user extension, for = | = | -| | `"ExtraFiles"` = | = | -| | Added PCD comment type for # [Error] which is used to map a= n error code for a given token space to a specific string. | = | -| 1.24 w/ | Updates: = | December 2= 014 | -| Errata A | Changed DEC_SPECIFICATION to 0x00010018 and allow specifyin= g it as a decimal, i.e., 1.24. | = | -| | Updated specification dates and added two new specification= s in section 1.2 | = | -| | Removed expression EBNF as it has been replaced by the EDK = II Expression Syntax Specification. | = | -| 1.24 w/ | Updates: = | March 2015= | -| Errata B | - Update link to the EDK II Specifications, fixed the name = of the Multi-String .UNI File Format Specification | = | -| 1.24 w/ | Updates: = | August 201= 5 | -| Errata C | Clarify that #include statements are not permitted in UNI f= ile specified in the PACKAGE_UNI_FILE entry | = | -| 1.25 | Updates: = | January 20= 15 | -| | Specification revision to 1.25 = | = | -| | Revised WORKSPACE wording for updated build system that can= handle | = | -| | packages located outside of the WORKSPACE directory tree (r= efer to | = | -| | the TianoCore.org EDKII website for additional instructions= on setting | = | -| | up a development environment). = | = | -| 1.26 | Reformat for GitBook = | April 2017= | -| | Updated `DEC_SPECIFICATION` to `0x0001001A` or `1.26` = | = | -| | [#465](https://bugzilla.tianocore.org/show_bug.cgi?id=3D465= ) DEC spec: document private definitions | = | +| Revision | Revision History = = | Date | +| ---------- | -----------------------------------------------------------= ---------------------------------------------------------------------------= ------------- | --------------- | +| 1.0 | Initial release. = = | December 2007 | +| 1.1 | Updated based on errata = = | August 2008 | +| 1.2 | Updated based on enhancement requests = = | June 2009 | +| 1.21 | Updated based on errata and for enhancement requests = = | January 2010 | +| | Standardized the format for common content. = = | | +| | Added support for @Keyword Doxygen tag = = | | +| | Added support for @ModuleType Doxygen tags = = | | +| | Added support for @ValidList, @DefaultValue and @ValidRange= Doxygen tags for PCDs = | | +| | Added PKG_UNI_FILE element to [defines] section = = | | +| 1.22 | Errata and grammatical editing = = | April 2010 | +| 1.22 w/ | Updates: = = | December 2011 | +| Errata A | Updated to support UEFI version 2.3.1 and updated spec rele= ase dates in Introduction = | | +| | Clarify UEFI's PI Distribution Package Specification = = | | +| | Standardize Common data definitions for all specifications = = | | +| | Grammatical, formatting and spelling changes = = | | +| | Replaced "should" with wording saying that it is = = | | +| | "recommended" = = | | +| | Added EBNF for `` = = | | +| | Added scoping rules for Macros, clarified MACRO summary = = | | +| | Added an example of a binary only DEC file = = | | +| | Removed references to system environment variables in the M= acros section = | | +| | Specifically state where `` can be used, and wher= e it is prohibited; = | | +| | specifically state that MACROVAL entries are expanded where= they are used; = | | +| | clarify that MACROS are only expanded, not evaluated during= initial parsing of the DEC file = | | +| | Added table that shows that every part of a path name can b= e replaced by a MACROVAL = | | +| | Clarify that C data arrays must be byte arrays for PCD valu= e fields; prohibit C format and = | | +| | Registry Format GUID structures in VOID* PCD value fields = = | | +| | Update non-zero number is True, only 0 is consideered False= = | | +| | Prohibit specifying items as architecturally specific and a= lso common = | | +| | Changed `` to `` in = = | | +| | 3.4 = = | | +| | Defined `` as a `` for this release= (need to allow registry format in a future release) = | | +| | Update the [Includes], [Guids], [Protocols], [PPIs], [Libra= ryClasses] and PCD sections to allow an empty section = | | +| | Updated the format for ``, `` and `<= UnicodeString>` = | | +| | Update PATH related EBNF = = | | +| | Add `` to [Defines], [Includes] and = = | | +| | `[LibraryClasses] sections` = = | | +| | Provide rules in 2.2.6 for how macros can be shared between= different subsections = | | +| 1.22 w/ | Updates: = = | June 2012 | +| Errata B | Added a + after `` in the DoxComment definition of= PCDs, as more than one expression can be = | | +| | specified in the UEFI PI Distribution Package Specification= . = | | +| | Added text describing the use of `` for error num= bers as well as how they are scoped. = | | +| 1.22 w/ | Updates: = = | June 2012 | +| Errata B | Updated UEFI/PI Spec version in chapter 1.3 to include Erra= ta letters. = | | +| (cont.) | In Section 3.10 modified the optional error number in = = | | +| | DoxComment definitions for PCDs from ``+ to = = | | +| | and defined to be of type ; = | | +| | also added a "\|" after the value to separate the error cod= e from numeric values = | | +| | Added AsBuilt entries for Abstract and Description = = | | +| | Clarified that the file must use the DOS end-of-line charac= ter sequence, `0x0D 0x0A` = | | +| 1.22 w/ | Updates: = = | August 2013 | +| Errata C | Updated UEFI/PI Specification version support in chapter 1 = = | | +| | Modified examples to correct previous errors = = | | +| | Removed errors from text = = | | +| | Updated examples = = | | +| | Modified EBNF to prevent using the architectural modifier o= f common with any other architecture. = | | +| | Ensure that wording specifically states that the architectu= re modifiers are not case sensitive. = | | +| | Add description of PCD processing rules in section 3.10 = = | | +| | Allow registry format GUID values in GUIDs, Protocols, = = | | +| | PPIs sections instead of requiring C format GUID values = = | | +| | (which will continue to be allowed) = = | | +| | The error codes are scoped to the TokenSpaceGUID, not to th= e PCD = | | +| | Added reference to the EDK II Build Specification for PCD p= rocessing rules. = | | +| 1.24 | `Updates;` = = | August 2014 | +| | Change revision number of this specification from 1.22 to = = | | +| | 1.24 = = | | +| | Updated `DEC_SPECIFICATION` to `0x00010017` = = | | +| | Added additional parameter definitions for clarification of= the comment content for PCDs = | | +| | Added the `PACKAGE_UNI_FILE` entry to the `[Defines]` secti= on = | | +| | Added reserved TianoCore user extension, for = = | | +| | `"ExtraFiles"` = = | | +| | Added PCD comment type for # [Error] which is used to map a= n error code for a given token space to a specific string. = | | +| 1.24 w/ | Updates: = = | December 2014 | +| Errata A | Changed DEC_SPECIFICATION to 0x00010018 and allow specifyin= g it as a decimal, i.e., 1.24. = | | +| | Updated specification dates and added two new specification= s in section 1.2 = | | +| | Removed expression EBNF as it has been replaced by the EDK = II Expression Syntax Specification. = | | +| 1.24 w/ | Updates: = = | March 2015 | +| Errata B | - Update link to the EDK II Specifications, fixed the name = of the Multi-String .UNI File Format Specification = | | +| 1.24 w/ | Updates: = = | August 2015 | +| Errata C | Clarify that #include statements are not permitted in UNI f= ile specified in the PACKAGE_UNI_FILE entry = | | +| 1.25 | Updates: = = | January 2015 | +| | Specification revision to 1.25 = = | | +| | Revised WORKSPACE wording for updated build system that can= handle = | | +| | packages located outside of the WORKSPACE directory tree (r= efer to = | | +| | the TianoCore.org EDKII website for additional instructions= on setting = | | +| | up a development environment). = = | | +| 1.26 | Reformat for GitBook = = | April 2017 | +| | Updated `DEC_SPECIFICATION` to `0x0001001A` or `1.26` = = | | +| | [#465](https://bugzilla.tianocore.org/show_bug.cgi?id=3D465= ) DEC spec: document private definitions = | | +| | [#482](https://bugzilla.tianocore.org/show_bug.cgi?id=3D482= ) DEC Spec: add clarification for [Ppis], [Guids], [Protocols], [Includes] = Private support | | --=20 2.6.3.windows.1 _______________________________________________ edk2-devel mailing list edk2-devel@lists.01.org https://lists.01.org/mailman/listinfo/edk2-devel