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

["Zhu, Yonghong" <yonghong.zhu@intel.com>]

Yes, I think we should remove it as part of #480. Thanks.

Best Regards,
Zhu Yonghong


-----Original Message-----
From: Kinney, Michael D 
Sent: Tuesday, April 25, 2017 10:36 AM
To: Zhu, Yonghong <yonghong.zhu@intel.com>; edk2-devel@lists.01.org; Kinney, Michael D <michael.d.kinney@intel.com>
Cc: Gao, Liming <liming.gao@intel.com>; Shaw, Kevin W <kevin.w.shaw@intel.com>
Subject: RE: [ edk2-BuildSpecification PATCH] Add support for Private declarations in a package

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