From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: 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 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.37,247,1488873600"; d="scan'208";a="93697960" 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 From: Michael Kinney To: edk2-devel@lists.01.org Cc: Liming Gao , Yonghong Zhu , Kevin W Shaw 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-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: , X-List-Received-Date: Tue, 25 Apr 2017 01:10:11 -0000 https://bugzilla.tianocore.org/show_bug.cgi?id=482 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. For example, `[Includes.common, Includes.IA32.Private]` is prohibited. +It is NOT permissible for the same include directory to be listed in section +tags with and without the `Private` modifier. If this condition is detected, +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 ```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. For example, `[Guids.common, Guids.IA32.Private]` is prohibited. +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 tools +must terminate with an error message. + +For example, the following is prohibited because the GUID named `MyPrivateGuid` +is listed in a tag with and without a `Private` modifier. + +``` +[Guids] + MyPrivateGuid = { 0x1e96808b, 0xfa93, 0x4230, { 0xb5, 0x6b, 0x96, 0xc5, 0x95, 0x9b, 0xd1, 0xd2 }} + +[Guids.common.Private] + MyPrivateGuid = { 0x1e96808b, 0xfa93, 0x4230, { 0xb5, 0x6b, 0x96, 0xc5, 0x95, 0x9b, 0xd1, 0xd2 }} +``` + #### Example ```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. For example, `[Protocols.common, Protocols.IA32.Private]` is prohibited. +It is NOT permissible for the same protocol to be listed in section tags with +and without the `Private` modifier. If this condition is detected, the build +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` modifier. + +``` +[Protocols] + MyPrivateProtocol = { 0xc7c4a20f, 0xd1d1, 0x427a, { 0xb0, 0x82, 0xa8, 0xb6, 0x24, 0xf7, 0x69, 0x4f }} + +[Protocols.common.Private] + MyPrivateProtocol = { 0xc7c4a20f, 0xd1d1, 0x427a, { 0xb0, 0x82, 0xa8, 0xb6, 0x24, 0xf7, 0x69, 0x4f }} +``` + #### Example ```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. For example, `[Ppis.common, Ppis.IA32.Private]` is prohibited. +It is NOT permissible for the same PPI to be listed in section tags with and +without the `Private` modifier. If this condition is detected, the build tools +must terminate with an error message. + +For example, the following is prohibited because the PPI named `MyPrivatePpi` +is listed in a tag with and without a `Private` modifier. + +``` +[Ppis] + MyPrivatePpi = { 0x10ed6a18, 0xbbf7, 0x4051, { 0xba, 0xb8, 0xb4, 0x90, 0x1a, 0x65, 0xa2, 0xc5 }} + +[Ppis.common.Private] + MyPrivatePpi = { 0x10ed6a18, 0xbbf7, 0x4051, { 0xba, 0xb8, 0xb4, 0x90, 0x1a, 0x65, 0xa2, 0xc5 }} +``` + #### Example ```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. ### Revision History -| 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 release 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 Macros section | | -| | Specifically state where `` can be used, and where 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 be replaced by a MACROVAL | | -| | Clarify that C data arrays must be byte arrays for PCD value 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 also 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], [LibraryClasses] and PCD sections to allow an empty section | | -| | Updated the format for ``, `` and `` | | -| | 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 numbers 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 Errata 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 code from numeric values | | -| | Added AsBuilt entries for Abstract and Description | | -| | Clarified that the file must use the DOS end-of-line character 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 of common with any other architecture. | | -| | Ensure that wording specifically states that the architecture 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 the PCD | | -| | Added reference to the EDK II Build Specification for PCD processing 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]` section | | -| | Added reserved TianoCore user extension, for | | -| | `"ExtraFiles"` | | -| | Added PCD comment type for # [Error] which is used to map an 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 specifying it as a decimal, i.e., 1.24. | | -| | Updated specification dates and added two new specifications 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 file 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 (refer 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=465) 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 release 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 Macros section | | +| | Specifically state where `` can be used, and where 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 be replaced by a MACROVAL | | +| | Clarify that C data arrays must be byte arrays for PCD value 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 also 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], [LibraryClasses] and PCD sections to allow an empty section | | +| | Updated the format for ``, `` and `` | | +| | 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 numbers 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 Errata 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 code from numeric values | | +| | Added AsBuilt entries for Abstract and Description | | +| | Clarified that the file must use the DOS end-of-line character 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 of common with any other architecture. | | +| | Ensure that wording specifically states that the architecture 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 the PCD | | +| | Added reference to the EDK II Build Specification for PCD processing 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]` section | | +| | Added reserved TianoCore user extension, for | | +| | `"ExtraFiles"` | | +| | Added PCD comment type for # [Error] which is used to map an 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 specifying it as a decimal, i.e., 1.24. | | +| | Updated specification dates and added two new specifications 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 file 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 (refer 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=465) DEC spec: document private definitions | | +| | [#482](https://bugzilla.tianocore.org/show_bug.cgi?id=482) DEC Spec: add clarification for [Ppis], [Guids], [Protocols], [Includes] Private support | | -- 2.6.3.windows.1