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 E61BB2195408B for ; Mon, 24 Apr 2017 18:10:10 -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:10 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.37,247,1488873600"; d="scan'208";a="93697957" 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:05 -0700 Message-Id: <1493082606-9348-4-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 3/4] Add support for Private declarations in a package 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=465 Add new syntax to the DEC file for specifying information that can only be used by modules within the package. When modules outside the packages attempt to use this content, the EDK II build system must break with an error regarding content not found. The four sections, Includes, Ppis, Guids and Protocols headers will be modified with a keyword, Private following the architecture modifier. If Private is not present, then the content is usable by modules outside the package. Cc: Liming Gao Cc: Yonghong Zhu Cc: Kevin W Shaw Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Michael Kinney --- 2_dec_file_overview/25_[includes]_usage.md | 24 +++++++++++++++++++++- 2_dec_file_overview/26_[guids]_usage.md | 22 ++++++++++++++++++-- 2_dec_file_overview/27_[protocols]_usage.md | 24 +++++++++++++++++++++- 2_dec_file_overview/28_[ppis]_usage.md | 24 +++++++++++++++++++++- 3_edk_ii_dec_file_format/35_[includes]_sections.md | 14 ++++++++++++- 3_edk_ii_dec_file_format/36_[guids]_sections.md | 14 ++++++++++++- .../37_[protocols]_sections.md | 14 ++++++++++++- 3_edk_ii_dec_file_format/38_[ppis]_sections.md | 14 ++++++++++++- README.md | 1 + 9 files changed, 142 insertions(+), 9 deletions(-) diff --git a/2_dec_file_overview/25_[includes]_usage.md b/2_dec_file_overview/25_[includes]_usage.md index b61eb98..17feb57 100644 --- a/2_dec_file_overview/25_[includes]_usage.md +++ b/2_dec_file_overview/25_[includes]_usage.md @@ -48,23 +48,45 @@ Also included in this section are the directories containing headers that may be required for individual EDK II module types. Refer to Appendix, "EDK II Module Types", for a list of the valid types. +The section tag modifier, `Private`, is used to restrict the EDK II build +system by preventing references to content in these sections from being used by +modules outside of the package. + Refer to the `[Includes]` definition later in this document for a complete description of this section and its contents. The `[Includes]` section uses one of the following section definitions: ```ini +[Includes] + [Includes.common] +[Includes.common.Private] + [Includes.IA32] +[Includes.IA32.Private] + [Includes.X64] +[Includes.X64.Private] + [Includes.IPF] +[Includes.IPF.Private] + [includes.EBC] -[Includes] +[includes.EBC.Private] +``` + +Architectural sections may also be combined, as in: + +```ini +[Includes.IA32, Includes.X64] + +[Includes.IA32.Private, Includes.X64.Private] ``` The format for entries in this section is one field, with an optional comment diff --git a/2_dec_file_overview/26_[guids]_usage.md b/2_dec_file_overview/26_[guids]_usage.md index 98459cf..f9addf5 100644 --- a/2_dec_file_overview/26_[guids]_usage.md +++ b/2_dec_file_overview/26_[guids]_usage.md @@ -35,24 +35,42 @@ This is an optional section. This section is used to define the GUID Value for Guid C Names. +The section tag modifier, `Private`, is used to restrict the EDK II build +system by preventing references to content in these sections from being used by +modules outside of the package. + This section uses one of the following section definitions: ```ini [Guids] +[Guids.common] + +[Guids.common.Private] + [Guids.IA32] +[Guids.IA32.Private] + [Guids.X64] +[Guids.X64.Private] + [Guids.IPF] +[Guids.IPF.Private] + [Guids.EBC] -[Guids.common] +[Guids.EBC.Private] +``` +Architectural sections may also be combined, as in: + +```ini [Guids.IA32, Guids.X64] -[Guids.X64, Guids.IPF] +[Guids.IA32.Private, Guids.X64.Private] ``` Format for the entries in this section is two fields with an equal "=" diff --git a/2_dec_file_overview/27_[protocols]_usage.md b/2_dec_file_overview/27_[protocols]_usage.md index fb539b2..9f89524 100644 --- a/2_dec_file_overview/27_[protocols]_usage.md +++ b/2_dec_file_overview/27_[protocols]_usage.md @@ -35,20 +35,42 @@ This is an optional section. This section is used to define the GUID Value for Protocol C Names. +The section tag modifier, `Private`, is used to restrict the EDK II build +system by preventing references to content in these sections from being used by +modules outside of the package. + This section use ones of the following section definitions: ```ini [Protocols] +[Protocols.common] + +[Protocols.common.Private] + [Protocols.IA32] +[Protocols.IA32.Private] + [Protocols.X64] +[Protocols.X64.Private] + [Protocols.IPF] +[Protocols.IPF.Private] + [Protocols.EBC] -[Protocols.common] +[Protocols.EBC.Private] +``` + +Architectural sections may also be combined, as in: + +```ini +[Protocols.IA32, Protocols.X64] + +[Protocols.IA32.Private, Protocols.X64.Private] ``` Format for the entries in this section is two fields with an equal "=" diff --git a/2_dec_file_overview/28_[ppis]_usage.md b/2_dec_file_overview/28_[ppis]_usage.md index 578be72..35db7b0 100644 --- a/2_dec_file_overview/28_[ppis]_usage.md +++ b/2_dec_file_overview/28_[ppis]_usage.md @@ -35,20 +35,42 @@ This is an optional section. This section is used to define the GUID Value for PPI C Names. +The section tag modifier, `Private`, is used to restrict the EDK II build +system by preventing references to content in these sections from being used by +modules outside of the package. + This section use ones of the following section definitions: ```ini [Ppis] +[Ppis.common] + +[Ppis.common.Private] + [Ppis.IA32] +[Ppis.IA32.Private] + [Ppis.X64] +[Ppis.X64.Private] + [Ppis.IPF] +[Ppis.IPF.Private] + [Ppis.EBC] -[Ppis.common] +[Ppis.EBC.Private] +``` + +Architectural sections may also be combined, as in: + +```ini +[Ppis.IA32, Ppis.X64] + +[Ppis.IA32.Private, Ppis.X64.Private] ``` Format for the entries in this section is two fields with an equal "=" 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 939a175..6fa083c 100644 --- a/3_edk_ii_dec_file_format/35_[includes]_sections.md +++ b/3_edk_ii_dec_file_format/35_[includes]_sections.md @@ -58,9 +58,13 @@ other architecture type modifiers; doing so will result in a build break. ```c ::= "[Includes" [] "]" * - ::= {".common"} {} + ::= {} {} + ::= {".common"} {} + ::= {".common.Private"} {} ::= ["," "Includes" ]* ::= "." + ::= ["," "includes" ]* + ::= "." ".Private" ::= {} {} ::= * @@ -84,6 +88,14 @@ specific architecture. It is permissible to specify include directory entries under all architectures except `"common`" if different include directories are required for different architectures. +It is NOT permissible to mix section tags without the `Private` modifier with +section tags with the `Private` modifier. If this condition is detected, the +build tools must terminate with an error message. + +For example, `[Includes.common, Includes.IA32.Private]` is prohibited. + +#### Example + ```ini # Include section - list of Include Paths relative to the DEC file that # are provided by this package. 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 6422300..1d00c9a 100644 --- a/3_edk_ii_dec_file_format/36_[guids]_sections.md +++ b/3_edk_ii_dec_file_format/36_[guids]_sections.md @@ -51,9 +51,13 @@ Each GUID entry must be listed only once per section. ```c ::= "[Guids" [] "]" * - ::= {".common"} {} + ::= {} {} + ::= {".common"} {} + ::= {".common.Private"} {} ::= ["," "Guids" ]* ::= "." + ::= ["," "Guids" ]* + ::= "." ".Private" ::= [] {} {} ::= [] @@ -81,6 +85,14 @@ architecture. It is permissible to specify GUID entries under all architectures except `"common`" if different GUID values may be required for different architectures. +It is NOT permissible to mix section tags without the `Private` modifier with +section tags with the `Private` modifier. If this condition is detected, the +build tools must terminate with an error message. + +For example, `[Guids.common, Guids.IA32.Private]` is prohibited. + +#### Example + ```ini # Global Guid Definition section - list of Global Guid C Name # Data Structures that are provided by 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 445939f..a43260c 100644 --- a/3_edk_ii_dec_file_format/37_[protocols]_sections.md +++ b/3_edk_ii_dec_file_format/37_[protocols]_sections.md @@ -51,9 +51,13 @@ Each Protocol entry must be listed only once per section. ```c ::= "[Protocols" [] "]" * - ::= {".common"} {} + ::= {} {} + ::= {".common"} {} + ::= {".common.Private"} {} ::= ["," "Protocols" ]8 ::= "." + ::= ["," "Protocols" ]* + ::= "." ".Private" ::= [] {} {} ::= [] @@ -80,6 +84,14 @@ specific architecture. It is permissible to specify Protocol entries under all architectures except `"common`" if different Guid values may be required for different architectures. +It is NOT permissible to mix section tags without the `Private` modifier with +section tags with the `Private` modifier. If this condition is detected, the +build tools must terminate with an error message. + +For example, `[Protocols.common, Protocols.IA32.Private]` is prohibited. + +#### Example + ```ini # Global Protocols Definition section - list of Global Protocols C Name # Data Structures that are provided by 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 9b571c8..87c5f0d 100644 --- a/3_edk_ii_dec_file_format/38_[ppis]_sections.md +++ b/3_edk_ii_dec_file_format/38_[ppis]_sections.md @@ -52,9 +52,13 @@ Each PPI entry must be listed only once per section. ```c ::= "[Ppis" [] "]" * - ::= {".common"} {} + ::= {} {} + ::= {".common"} {} + ::= {".common.Private"} {} ::= ["," "Ppis" ]* ::= "." + ::= ["," "Ppis" ]* + ::= "." ".Private" ::= [] {} {} ::= [] @@ -81,6 +85,14 @@ architecture. It is permissible to specify PPI entries under all architectures except `"common`" if different Guid values may be required for different architectures. +It is NOT permissible to mix section tags without the `Private` modifier with +section tags with the `Private` modifier. If this condition is detected, the +build tools must terminate with an error message. + +For example, `[Ppis.common, Ppis.IA32.Private]` is prohibited. + +#### Example + ```ini # Global Ppis Definition section - list of Global Ppis C Name # Data Structures that are provided by diff --git a/README.md b/README.md index b489cb1..372ef19 100644 --- a/README.md +++ b/README.md @@ -166,3 +166,4 @@ Copyright (c) 2007-2017, Intel Corporation. All rights reserved. | | 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 | | -- 2.6.3.windows.1