Re: [ edk2-BuildSpecification PATCH] Add support for Private declarations in a package

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

Yonghong,

The sentence about setting a PCD from the command line is related to

https://bugzilla.tianocore.org/show_bug.cgi?id=480

#480 Build spec: add description for Override PCD value on the command line

This will update the Build Specification to add the --pcd command line
flag to set PCD values. 

Should the following item be removed as part of #480?

" 5. Command > line cannot be used to set the PCD value."

Thanks,

Mike

> -----Original Message-----
> From: Zhu, Yonghong
> Sent: Monday, April 24, 2017 6:54 PM
> To: Kinney, Michael D <michael.d.kinney@intel.com>; edk2-devel@lists.01.org
> Cc: Gao, Liming <liming.gao@intel.com>; Shaw, Kevin W <kevin.w.shaw@intel.com>;
> Zhu, Yonghong <yonghong.zhu@intel.com>
> Subject: RE: [ edk2-BuildSpecification PATCH] Add support for Private declarations
> in a package
> 
> Hi Mike,
> 
> This patch is good to me.  Reviewed-by: Yonghong Zhu <yonghong.zhu@intel.com>
> 
> while during review this patch, I found one update we wound made for " 5. Command
> line cannot be used to set the PCD value.". It is not related with this topic, but
> we can create another patch to update this sentence. Thanks.
> 
> Best Regards,
> Zhu Yonghong
> 
> 
> -----Original Message-----
> From: Kinney, Michael D
> Sent: Tuesday, April 25, 2017 9:12 AM
> To: edk2-devel@lists.01.org
> Cc: Gao, Liming <liming.gao@intel.com>; Zhu, Yonghong <yonghong.zhu@intel.com>;
> Shaw, Kevin W <kevin.w.shaw@intel.com>
> Subject: [ edk2-BuildSpecification PATCH] Add support for Private declarations in
> a package
> 
> https://bugzilla.tianocore.org/show_bug.cgi?id=465
> 
> Process new syntax in the DEC file that specifies 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 the
> 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>
> ---
>  .../82_auto-generation_process.md                  | 35 ++++++++++++++--------
>  .../84_auto-generated_pcd_database_file.md         |  6 ++++
>  README.md                                          |  3 +-
>  3 files changed, 30 insertions(+), 14 deletions(-)
> 
> diff --git a/8_pre-build_autogen_stage/82_auto-generation_process.md b/8_pre-
> build_autogen_stage/82_auto-generation_process.md
> index 6868d62..22a8b08 100644
> --- a/8_pre-build_autogen_stage/82_auto-generation_process.md
> +++ b/8_pre-build_autogen_stage/82_auto-generation_process.md
> @@ -1034,16 +1034,25 @@ II module:
>    - DSC file's architecture specific modifier only `[LibraryClasses.arch]`
>    - The DSC file's common `[LibraryClasses]` section
> 
> -**********
> -**Note:** For modules of type **USER_DEFINED**_, if a `NULL` library class -is
> required, the library instance should be listed in the INF scoping -
> `<LibraryClasses>` section of the component.
> -**********
> +  **********
> +  **Note:** For modules of type **USER_DEFINED**_, if a `NULL` library
> + class  is required, the library instance should be listed in the INF
> + scoping  `<LibraryClasses>` section of the component.
> +  **********
> 
>  * Inherit GUIDs, Protocols and PPIs from all library instances obtained above,
>    and determine values or type of them. The value of a GUID, Protocol or PPI is
>    defined in DEC file.
> 
> +  **********
> +  **Note:** If GUID, Protocol or PPI is listed in a DEC file, where the
> + `Private` modifier is used in the section tag
> + (`[Guids.common.Private]` for  example), only modules within the
> + package are permitted to use the GUID,  Protocol or PPI. If a module
> + or library instance outside of the package  attempts to use the item,
> + the build must fail with an appropriate error  message.
> +  **********
> +
>  * Inherit PCDs from all library instances obtained above and determine values
>    and type. The value and type of a PCD are obtained from a DSC file, INF file
>    or DEC file if it cannot be found in the DSC or INF file. For each EDK II @@ -
> 1058,14 +1067,14 @@ is required, the library instance should be listed in the INF
> scoping
>    - The INF file's PCD sections
>    - The DEC file's PCD sections
> 
> -**********
> -**Note:** Values of PCDs using the FeatureFlag, PatchableInModule and -
> FixedAtBuild access methods set for this INF file are local to the INF file and -
> do not pertain to any other INF files. Dynamic and DynamicEx access method PCD -
> values are global to a platform and should not be overridden by specifying them -
> here. If, however, the dynamic PCDs are only valid for this INF, it is -
> permissible to set them here.
> -**********
> +  **********
> +  **Note:** Values of PCDs using the FeatureFlag, PatchableInModule and
> + FixedAtBuild access methods set for this INF file are local to the INF
> + file and  do not pertain to any other INF files. Dynamic and DynamicEx
> + access method PCD  values are global to a platform and should not be
> + overridden by specifying them  here. If, however, the dynamic PCDs are
> + only valid for this INF, it is  permissible to set them here.
> +  **********
> 
>  * Inherit library instance dependency (`[Depex]` sections) expressions if a
>    module does not list a separate dependency file.
> diff --git a/8_pre-build_autogen_stage/84_auto-generated_pcd_database_file.md
> b/8_pre-build_autogen_stage/84_auto-generated_pcd_database_file.md
> index d309246..fc291c5 100644
> --- a/8_pre-build_autogen_stage/84_auto-generated_pcd_database_file.md
> +++ b/8_pre-build_autogen_stage/84_auto-generated_pcd_database_file.md
> @@ -99,6 +99,12 @@ DSC, INF or DEC files.
> 
>  5. Command line cannot be used to set the PCD value.
> 
> +6. If a PCD has a Token Space GUID specified in DEC file and the `[Guids]`
> +   section tag contains the `Private` modifier (`[Guids.common.Private]` for
> +   example), the PCD may only be used by modules in the package containing the
> +   DEC file. If a module outside of that package attempts to use the PCD, the
> +   build must break with an appropriate error message.
> +
>  #### 8.4.1.2 Precedence Rules for PCDs not listed in the DSC or FDF Files:
> 
>  This subsection covers PCDs that are used by modules listed in the DSC file, diff
> --git a/README.md b/README.md index 89578d0..94b2062 100644
> --- a/README.md
> +++ b/README.md
> @@ -188,7 +188,7 @@ Copyright (c) 2008-2017, Intel Corporation. All rights
> reserved.
>  | 1.24 w/    | Updates:
> | August 2015   |
>  | Errata A   | Updated 10.4 to describe how tools add an FvNameString in the FV
> image extension header
> |               |
>  |            | Update 8.7.5 - 8.7.9 to allow the build system to update usage
> information based on feature flag evaluation during the build
> |               |
> -| 1.26       | Updates :
> | January 2016  |
> +| 1.26       | Updates :
> | January 2016  |
>  |            | Specification revision to 1.26
> |               |
>  |            | Removed data structure definitions (duplicates from PE/ COFF, PI
> Specifications and TE headers) in Chapter 3 and included references to the
> industry specifications to remove potential typographical errors and
> inconsistencies.
> |               |
>  |            | Removed Setup and Getting Started sections from Quick Start
> chapter 6 - this information is available on the TianoCore.org web-site.
> |               |
> @@ -208,3 +208,4 @@ Copyright (c) 2008-2017, Intel Corporation. All rights
> reserved.
>  |            | [#479](https://bugzilla.tianocore.org/show_bug.cgi?id=479) Build
> spec: add description for nmake long command line handling
> |               |
>  |            | [#485](https://bugzilla.tianocore.org/show_bug.cgi?id=485) Build
> spec: add support for mixed Pcd access method
> |               |
>  |            | [#476](https://bugzilla.tianocore.org/show_bug.cgi?id=476) Build
> spec: add support for HII image package
> |               |
> +|            | [#465](https://bugzilla.tianocore.org/show_bug.cgi?id=465) DEC
> spec: document private definitions
> |               |
> --
> 2.6.3.windows.1