From nobody Sat Nov 2 10:24:26 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 149308262090747.2726151474958; Mon, 24 Apr 2017 18:10:20 -0700 (PDT) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id 55AEA20D770D6; 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 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 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="93697957" From: Michael Kinney To: edk2-devel@lists.01.org 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] [ 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: , 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=3D465 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_overvi= ew/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 conta= ining 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. =20 +The section tag modifier, `Private`, is used to restrict the EDK II build +system by preventing references to content in these sections from being us= ed 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. =20 The `[Includes]` section uses one of the following section definitions: =20 ```ini +[Includes] + [Includes.common] =20 +[Includes.common.Private] + [Includes.IA32] =20 +[Includes.IA32.Private] + [Includes.X64] =20 +[Includes.X64.Private] + [Includes.IPF] =20 +[Includes.IPF.Private] + [includes.EBC] =20 -[Includes] +[includes.EBC.Private] +``` + +Architectural sections may also be combined, as in: + +```ini +[Includes.IA32, Includes.X64] + +[Includes.IA32.Private, Includes.X64.Private] ``` =20 The format for entries in this section is one field, with an optional comm= ent 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. =20 This section is used to define the GUID Value for Guid C Names. =20 +The section tag modifier, `Private`, is used to restrict the EDK II build +system by preventing references to content in these sections from being us= ed by +modules outside of the package. + This section uses one of the following section definitions: =20 ```ini [Guids] =20 +[Guids.common] + +[Guids.common.Private] + [Guids.IA32] =20 +[Guids.IA32.Private] + [Guids.X64] =20 +[Guids.X64.Private] + [Guids.IPF] =20 +[Guids.IPF.Private] + [Guids.EBC] =20 -[Guids.common] +[Guids.EBC.Private] +``` =20 +Architectural sections may also be combined, as in: + +```ini [Guids.IA32, Guids.X64] =20 -[Guids.X64, Guids.IPF] +[Guids.IA32.Private, Guids.X64.Private] ``` =20 Format for the entries in this section is two fields with an equal "=3D" diff --git a/2_dec_file_overview/27_[protocols]_usage.md b/2_dec_file_overv= iew/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. =20 This section is used to define the GUID Value for Protocol C Names. =20 +The section tag modifier, `Private`, is used to restrict the EDK II build +system by preventing references to content in these sections from being us= ed by +modules outside of the package. + This section use ones of the following section definitions: =20 ```ini [Protocols] =20 +[Protocols.common] + +[Protocols.common.Private] + [Protocols.IA32] =20 +[Protocols.IA32.Private] + [Protocols.X64] =20 +[Protocols.X64.Private] + [Protocols.IPF] =20 +[Protocols.IPF.Private] + [Protocols.EBC] =20 -[Protocols.common] +[Protocols.EBC.Private] +``` + +Architectural sections may also be combined, as in: + +```ini +[Protocols.IA32, Protocols.X64] + +[Protocols.IA32.Private, Protocols.X64.Private] ``` =20 Format for the entries in this section is two fields with an equal "=3D" diff --git a/2_dec_file_overview/28_[ppis]_usage.md b/2_dec_file_overview/2= 8_[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. =20 This section is used to define the GUID Value for PPI C Names. =20 +The section tag modifier, `Private`, is used to restrict the EDK II build +system by preventing references to content in these sections from being us= ed by +modules outside of the package. + This section use ones of the following section definitions: =20 ```ini [Ppis] =20 +[Ppis.common] + +[Ppis.common.Private] + [Ppis.IA32] =20 +[Ppis.IA32.Private] + [Ppis.X64] =20 +[Ppis.X64.Private] + [Ppis.IPF] =20 +[Ppis.IPF.Private] + [Ppis.EBC] =20 -[Ppis.common] +[Ppis.EBC.Private] +``` + +Architectural sections may also be combined, as in: + +```ini +[Ppis.IA32, Ppis.X64] + +[Ppis.IA32.Private, Ppis.X64.Private] ``` =20 Format for the entries in this section is two fields with an equal "=3D" 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. =20 ```c ::=3D "[Includes" [] "]" * - ::=3D {".common"} {} + ::=3D {} {} + ::=3D {".common"} {} + ::=3D {".common.Private"} {} ::=3D ["," "Includes" ]* ::=3D "." + ::=3D ["," "includes" ]* + ::=3D "." ".Private" ::=3D {} {} ::=3D * @@ -84,6 +88,14 @@ specific architecture. It is permissible to specify incl= ude directory entries under all architectures except `"common`" if different include directories= are required for different architectures. =20 +It is NOT permissible to mix section tags without the `Private` modifier w= ith +section tags with the `Private` modifier. If this condition is detected, t= he +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. =20 ```c ::=3D "[Guids" [] "]" * - ::=3D {".common"} {} + ::=3D {} {} + ::=3D {".common"} {} + ::=3D {".common.Private"} {} ::=3D ["," "Guids" ]* ::=3D "." + ::=3D ["," "Guids" ]* + ::=3D "." ".Private" ::=3D [] {} {} ::=3D [] @@ -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. =20 +It is NOT permissible to mix section tags without the `Private` modifier w= ith +section tags with the `Private` modifier. If this condition is detected, t= he +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. =20 ```c ::=3D "[Protocols" [] "]" * - ::=3D {".common"} {} + ::=3D {} {} + ::=3D {".common"} {} + ::=3D {".common.Private"} {} ::=3D ["," "Protocols" ]8 ::=3D "." + ::=3D ["," "Protocols" ]* + ::=3D "." ".Private" ::=3D [] {} {} ::=3D [] @@ -80,6 +84,14 @@ specific architecture. It is permissible to specify Prot= ocol entries under all architectures except `"common`" if different Guid values may be required f= or different architectures. =20 +It is NOT permissible to mix section tags without the `Private` modifier w= ith +section tags with the `Private` modifier. If this condition is detected, t= he +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. =20 ```c ::=3D "[Ppis" [] "]" * - ::=3D {".common"} {} + ::=3D {} {} + ::=3D {".common"} {} + ::=3D {".common.Private"} {} ::=3D ["," "Ppis" ]* ::=3D "." + ::=3D ["," "Ppis" ]* + ::=3D "." ".Private" ::=3D [] {} {} ::=3D [] @@ -81,6 +85,14 @@ architecture. It is permissible to specify PPI entries u= nder all architectures except `"common`" if different Guid values may be required for different architectures. =20 +It is NOT permissible to mix section tags without the `Private` modifier w= ith +section tags with the `Private` modifier. If this condition is detected, t= he +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=3D465= ) DEC spec: document private definitions | = | --=20 2.6.3.windows.1 _______________________________________________ edk2-devel mailing list edk2-devel@lists.01.org https://lists.01.org/mailman/listinfo/edk2-devel