From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <liming.gao@intel.com>
Received-SPF: Pass (sender SPF authorized) identity=mailfrom;
 client-ip=134.134.136.65; helo=mga03.intel.com;
 envelope-from=liming.gao@intel.com; receiver=edk2-devel@lists.01.org 
Received: from mga03.intel.com (mga03.intel.com [134.134.136.65])
 (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 ADAB2225F31F5
 for <edk2-devel@lists.01.org>; Mon,  2 Apr 2018 02:02:21 -0700 (PDT)
X-Amp-Result: SKIPPED(no attachment in message)
X-Amp-File-Uploaded: False
Received: from fmsmga002.fm.intel.com ([10.253.24.26])
 by orsmga103.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384;
 02 Apr 2018 02:02:07 -0700
X-ExtLoop1: 1
X-IronPort-AV: E=Sophos;i="5.48,395,1517904000"; d="scan'208";a="33454103"
Received: from fmsmsx103.amr.corp.intel.com ([10.18.124.201])
 by fmsmga002.fm.intel.com with ESMTP; 02 Apr 2018 02:02:06 -0700
Received: from shsmsx102.ccr.corp.intel.com (10.239.4.154) by
 FMSMSX103.amr.corp.intel.com (10.18.124.201) with Microsoft SMTP Server (TLS)
 id 14.3.319.2; Mon, 2 Apr 2018 02:02:06 -0700
Received: from shsmsx104.ccr.corp.intel.com ([169.254.5.226]) by
 shsmsx102.ccr.corp.intel.com ([169.254.2.80]) with mapi id 14.03.0319.002;
 Mon, 2 Apr 2018 17:02:00 +0800
From: "Gao, Liming" <liming.gao@intel.com>
To: "Zhu, Yonghong" <yonghong.zhu@intel.com>, "edk2-devel@lists.01.org"
 <edk2-devel@lists.01.org>
CC: "Kinney, Michael D" <michael.d.kinney@intel.com>, "Shaw, Kevin W"
 <kevin.w.shaw@intel.com>
Thread-Topic: [Patch] Build spec: Add some clarification and clean up for
 build report
Thread-Index: AQHTyjLaL4tNU0vge0KTUKMAN5QFrqPtLhpg
Date: Mon, 2 Apr 2018 09:02:00 +0000
Message-ID: <4A89E2EF3DFEDB4C8BFDE51014F606A14E1F0D82@SHSMSX104.ccr.corp.intel.com>
References: <1522639779-23096-1-git-send-email-yonghong.zhu@intel.com>
In-Reply-To: <1522639779-23096-1-git-send-email-yonghong.zhu@intel.com>
Accept-Language: en-US
X-MS-Has-Attach: 
X-MS-TNEF-Correlator: 
x-originating-ip: [10.239.127.40]
MIME-Version: 1.0
Subject: Re: [Patch] Build spec: Add some clarification and clean up for build report
X-BeenThere: edk2-devel@lists.01.org
X-Mailman-Version: 2.1.26
Precedence: list
List-Id: EDK II Development  <edk2-devel.lists.01.org>
List-Unsubscribe: <https://lists.01.org/mailman/options/edk2-devel>,
 <mailto:edk2-devel-request@lists.01.org?subject=unsubscribe>
List-Archive: <http://lists.01.org/pipermail/edk2-devel/>
List-Post: <mailto:edk2-devel@lists.01.org>
List-Help: <mailto:edk2-devel-request@lists.01.org?subject=help>
List-Subscribe: <https://lists.01.org/mailman/listinfo/edk2-devel>,
 <mailto:edk2-devel-request@lists.01.org?subject=subscribe>
X-List-Received-Date: Mon, 02 Apr 2018 09:02:23 -0000
Content-Language: en-US
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable

Reviewed-by: Liming Gao <liming.gao@intel.com>

>-----Original Message-----
>From: Zhu, Yonghong
>Sent: Monday, April 02, 2018 11:30 AM
>To: edk2-devel@lists.01.org
>Cc: Gao, Liming <liming.gao@intel.com>; Kinney, Michael D
><michael.d.kinney@intel.com>; Shaw, Kevin W <kevin.w.shaw@intel.com>
>Subject: [Patch] Build spec: Add some clarification and clean up for build
>report
>
>Add some clarification and clean up for build report section.
>
>Cc: Liming Gao <liming.gao@intel.com>
>Cc: Michael Kinney <michael.d.kinney@intel.com>
>Cc: Kevin W Shaw <kevin.w.shaw@intel.com>
>Contributed-under: TianoCore Contribution Agreement 1.1
>Signed-off-by: Yonghong Zhu <yonghong.zhu@intel.com>
>---
> 13_build_reports/134_platform_summary.md   | 44 +++++++++++-------------
>------
> 13_build_reports/136_global_pcd_section.md |  7 +++--
> 13_build_reports/138_module_section.md     | 11 +++++---
> 3 files changed, 27 insertions(+), 35 deletions(-)
>
>diff --git a/13_build_reports/134_platform_summary.md
>b/13_build_reports/134_platform_summary.md
>index 09b8db6..23964af 100644
>--- a/13_build_reports/134_platform_summary.md
>+++ b/13_build_reports/134_platform_summary.md
>@@ -1,9 +1,9 @@
> <!--- @file
>   13.4 Platform Summary
>
>-  Copyright (c) 2008-2017, Intel Corporation. All rights reserved.<BR>
>+  Copyright (c) 2008-2018, Intel Corporation. All rights reserved.<BR>
>
>   Redistribution and use in source (original document form) and 'compiled=
'
>   forms (converted to PDF, epub, HTML and other formats) with or without
>   modification, are permitted provided that the following conditions are =
met:
>
>@@ -72,35 +72,14 @@ Report Contents:    PCD, LIBRARY, BUILD_FLAGS,
>DEPEX, FLASH, FIXED_ADDRESS
> **********
> **Note:** Platform Summary is always present and appears at the beginning
>of
> report.
> **********
>
>-If the DSC or FDF file contains conditional directive statements (`!if`,
>-`!elseif`, `!ifdef` or `!ifndef`) or the value of PCD is not used by a mo=
dule is
>-set in the DSC file (PCD Sections) or the FDF file (`SET` statements for
>-example), the following sub-section is generated.
>-
>-```
>-
>=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
>=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D<
>-Conditional Directives used by the build system
>-
>=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
>=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
>-```
>-
>-If the DSC or FDF file define values for PCDs that are not used by any mo=
dule
>-and are not used in conditional directive statements, the following sub-
>section
>-is generated.
>-
>-```
>-
>=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
>=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D<
>-PCDs not used by modules or in conditional directives
>-
>=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
>=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
>-```
>-
> ### 13.4.1 PCDs in Conditional Directives
>
>-If a PCD is used in a conditional directive statement, the PCD section is
>-generated.
>+If a PCD is used in a conditional directive statement in DSC or FDF file,=
 this
>+PCD section is generated. This is optional section.
>
> PCD values derived from expressions or other PCDs are not differentiated =
in
>the
> report. Only the final value is displayed.
>
> The first line is required:
>@@ -108,11 +87,15 @@ The first line is required:
> `[*P|*F|*B] <PcdCName>: <PcdType> (<DatumType>) =3D <PcdValue>`
>
> * `*P` means the Pcd's value was obtained from the DSC file
> * `*F` means the PCD's value was obtained from the FDF file.
> * `*B` means the PCD's value set by a build option.
>-**Note:** If the Pcd is a Structure PCD, <DatumType> is the Struct Name.
>+* If no `*P`, `*F` or `*B` is shown, the PCD's value comes from DEC file.=
 If the
>+  value obtained from either a build option, the DSC or FDF is the same a=
s the
>+  value in the DEC, then `*B`, `*P` or `*F` will not be shown in the repo=
rt.
>+
>+**Note: ** If the Pcd is a Structure PCD, `<DatumType>` is the Struct Nam=
e.
>
> Additional lines may be displayed showing default values when the value i=
s
>not a
> default value.
>
> ### Example
>@@ -132,12 +115,13 @@ gMyTokenSpaceGuid
> >=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D
>=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D<
> ```
>
> ### 13.4.2 PCDs not used
>
>-If a PCD is not used in a conditional directive statement or by a module,=
 the
>-not used PCD section is generated.
>+If a PCD defined in DSC or FDF file, but the PCD is not used in a conditi=
onal
>+directive statement and not used by any module, the not used PCD section =
is
>+generated. This is optional section.
>
> PCD values derived from expressions or other PCDs are not differentiated =
in
>the
> report. Only the final value is displayed.
>
> The first line is required:
>@@ -145,11 +129,15 @@ The first line is required:
> `[*P|*F|*B] <PcdCName>: <PcdType> (<DatumType>)
>[(<SKUID>)][(<DefaultStore>)] =3D <PcdValue>`
>
> * `*P` means the Pcd's value was obtained from the DSC file
> * `*F` means the PCD's value was obtained from the FDF file.
> * `*B` means the PCD's value set by a build option.
>-**Note:** If the Pcd is a Structure PCD, <DatumType> is the Struct Name.
>+* If no `*P`, `*F` or `*B` is shown, the PCD's value comes from DEC file.=
 If the
>+  value obtained from either a build option, the DSC or FDF is the same a=
s the
>+  value in the DEC, then `*B`, `*P` or `*F` will not be shown in the repo=
rt.
>+
>+**Note: ** If the Pcd is a Structure PCD, `<DatumType>` is the Struct Nam=
e.
>
> Additional lines may be displayed showing default values when the value i=
s
>not a
> default value.
>
> Since the PCDs in this section are not used by any module, the PCD value =
is
>not
>diff --git a/13_build_reports/136_global_pcd_section.md
>b/13_build_reports/136_global_pcd_section.md
>index a9661b6..2a5b682 100644
>--- a/13_build_reports/136_global_pcd_section.md
>+++ b/13_build_reports/136_global_pcd_section.md
>@@ -1,9 +1,9 @@
> <!--- @file
>   13.6 Global PCD Section
>
>-  Copyright (c) 2008-2017, Intel Corporation. All rights reserved.<BR>
>+  Copyright (c) 2008-2018, Intel Corporation. All rights reserved.<BR>
>
>   Redistribution and use in source (original document form) and 'compiled=
'
>   forms (converted to PDF, epub, HTML and other formats) with or without
>   modification, are permitted provided that the following conditions are =
met:
>
>@@ -60,11 +60,12 @@ The first line is required:
> * `*F` means the PCD's value was obtained from the FDF file.
> * `*B` means the PCD's value was obtained from a build option.
> * If no `*P`, `*F` or `*B` is shown, the PCD's value comes from DEC file.=
 If the
>   value obtained from either a build option, the DSC or FDF is the same a=
s the
>   value in the DEC, then `*B`, `*P` or `*F` will not be shown in the repo=
rt.
>-**Note:** If the Pcd is a Structure PCD, <DatumType> is the Struct Name.
>+
>+**Note: ** If the Pcd is a Structure PCD, `<DatumType>` is the Struct Nam=
e.
>
> #### Examples
>
> ```
> *P PcdWinNtFirmwareVolume               : FIXED   (VOID*) =3D L"..\\Fv\\N=
t32.fd"
>@@ -109,11 +110,11 @@ gTokenSpaceGuid
> #### 13.6.2.2 Default (optional) line
>
> The second optional line is present if the value from the DSC was overrid=
den
> by build option. It is formatted as follows:
>
>-`DSC DEFAULT =3D <Value in PCD SectionSection in DSC>`
>+`DSC DEFAULT =3D <Value in PCD Section in DSC>`
>
> The third optional line is present if the value from the DEC was overridd=
en.
> It is formatted as follows:
>
> `DEC DEFAULT =3D <Value in DEC>`
>diff --git a/13_build_reports/138_module_section.md
>b/13_build_reports/138_module_section.md
>index fb2417d..88e9ac2 100644
>--- a/13_build_reports/138_module_section.md
>+++ b/13_build_reports/138_module_section.md
>@@ -1,9 +1,9 @@
> <!--- @file
>   13.8 Module Section
>
>-  Copyright (c) 2008-2017, Intel Corporation. All rights reserved.<BR>
>+  Copyright (c) 2008-2018, Intel Corporation. All rights reserved.<BR>
>
>   Redistribution and use in source (original document form) and 'compiled=
'
>   forms (converted to PDF, epub, HTML and other formats) with or without
>   modification, are permitted provided that the following conditions are =
met:
>
>@@ -238,18 +238,21 @@ gEfiMdeModulePkgTokenSpaceGuid
> ```
>
> Each PCD may contain up to four lines:
>
> 1. The first line is a mandatory line with the following format:
>-   `[*P|*F|*B] <PcdCName>: <PcdType> (<DatumType>)
>[(<SKUID>)][(<DefaultStore>)] =3D <PcdValue>`
>-   **Note:** If the Pcd is a Structure PCD, <DatumType> is the Struct Nam=
e.
>+   `[*P|*F|*B|*M] <PcdCName>: <PcdType> (<DatumType>)
>[(<SKUID>)][(<DefaultStore>)] =3D <PcdValue>`
>+
>+   **Note: ** If the Pcd is a Structure PCD, `<DatumType>` is the Struct =
Name.
>+
>    - \*P means the Pcd's value is the platform default (listed in DSC PCD
>common
>      section or inherited from Module INF file).
>    - \*M means the PCD's value in module INF was obtained from the
>`[Components]`
>      section of the DSC file.
>    - \*F means the PCD's value is override in FDF file.
>-   - If no \*P or \*F, mean the PCD's value comes from DEC file.
>+   - \*B means the PCD's value is override in build option.
>+   - If no \*P or \*F or \*B or \*M, mean the PCD's value comes from DEC =
file.
>    - For example:
>      ```
>      *P PcdWinNtFirmwareVolume : FIXED (VOID*) =3D L"..\\Fv\\Nt32.fd"
>      ```
>
>--
>2.6.1.windows.1