[ edk2-DecSpecification PATCH 3/4] Add support for Private declarations in a package

[Michael Kinney <michael.d.kinney@intel.com>]

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 <liming.gao@intel.com>
Cc: Yonghong Zhu <yonghong.zhu@intel.com>
Cc: Kevin W Shaw <kevin.w.shaw@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Michael Kinney <michael.d.kinney@intel.com>
---
 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
 <Include>      ::= "[Includes" [<com_attribs>] "]" <EOL> <IncEntries>*
-<com_attribs>  ::= {".common"} {<attribs>}
+<com_attribs>  ::= {<Public>} {<Hidden>}
+<Public>       ::= {".common"} {<attribs>}
+<Hidden>       ::= {".common.Private"} {<hattribs>}
 <attribs>      ::= <attrs> ["," <TS> "Includes" <attrs>]*
 <attrs>        ::= "." <arch>
+<hattribs>     ::= <hattrs> ["," <TS> "includes" <hattrs>]*
+<hattrs>       ::= "." <arch> ".Private"
 <IncEntries>   ::= {<MacroDefinition>} {<HdrFile>}
 <HdrFile>      ::= <CommentBlock>*
                    <TS> <PATH>
@@ -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>          ::= "[Guids" [<com_attribs>] "]" <EOL> <GuidEntries>*
-<com_attribs>    ::= {".common"} {<attribs>}
+<com_attribs>    ::= {<Public>} {<Hidden>}
+<Public>         ::= {".common"} {<attribs>}
+<Hidden>         ::= {".common.Private"} {<hattribs>}
 <attribs>        ::= <attrs> ["," <TS> "Guids" <attrs>]*
 <attrs>          ::= "." <arch>
+<hattribs>       ::= <hattrs> ["," <TS> "Guids" <hattrs>]*
+<hattrs>         ::= "." <arch> ".Private"
 <GuidEntries>    ::= [<GuidComment>]
                      <TS> <CName> <Eq> <CFormatGUID> {<CommentBlock>} {<EOL>}
 <GuidComment>    ::= [<Description>]
@@ -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>       ::= "[Protocols" [<com_attribs>] "]" <EOL> <ProtocolEntries>*
-<com_attribs>     ::= {".common"} {<attribs>}
+<com_attribs>     ::= {<Public>} {<Hidden>}
+<Public>          ::= {".common"} {<attribs>}
+<Hidden>          ::= {".common.Private"} {<hattribs>}
 <attribs>         ::= <attrs> ["," <TS> "Protocols" <attrs>]8
 <attrs>           ::= "." <arch>
+<hattribs>        ::= <hattrs> ["," <TS> "Protocols" <hattrs>]*
+<hattrs>          ::= "." <arch> ".Private"
 <ProtocolEntries> ::= [<ProtocolComment>]
                       <TS> <CName> <Eq> <CFormatGUID> {<CommentBlock>} {<EOL>}
 <ProtocolComment> ::= [<Description>]
@@ -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>          ::= "[Ppis" [<com_attribs>] "]" <EOL> <PpiEntries>*
-<com_attribs>   ::= {".common"} {<attribs>}
+<com_attribs>   ::= {<Public>} {<Hidden>}
+<Public>        ::= {".common"} {<attribs>}
+<Hidden>        ::= {".common.Private"} {<hattribs>}
 <attribs>       ::= <attrs> ["," <TS> "Ppis" <attrs>]*
 <attrs>         ::= "." <arch>
+<hattribs>      ::= <hattrs> ["," <TS> "Ppis" <hattrs>]*
+<hattrs>        ::= "." <arch> ".Private"
 <PpiEntries>    ::= [<PpiComment>]
                     <TS> <CName> <Eq> <CFormatGUID> {<CommentBlock>} {<EOL>}
 <PpiComment>    ::= [<Description>]
@@ -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