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.126; helo=mga18.intel.com;
 envelope-from=liming.gao@intel.com; receiver=edk2-devel@lists.01.org 
Received: from mga18.intel.com (mga18.intel.com [134.134.136.126])
 (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 B895122551B91
 for <edk2-devel@lists.01.org>; Wed, 21 Mar 2018 23:24:15 -0700 (PDT)
X-Amp-Result: SKIPPED(no attachment in message)
X-Amp-File-Uploaded: False
Received: from fmsmga007.fm.intel.com ([10.253.24.52])
 by orsmga106.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384;
 21 Mar 2018 23:30:42 -0700
X-ExtLoop1: 1
X-IronPort-AV: E=Sophos;i="5.48,343,1517904000"; d="scan'208";a="26038720"
Received: from fmsmsx105.amr.corp.intel.com ([10.18.124.203])
 by fmsmga007.fm.intel.com with ESMTP; 21 Mar 2018 23:30:42 -0700
Received: from fmsmsx102.amr.corp.intel.com (10.18.124.200) by
 FMSMSX105.amr.corp.intel.com (10.18.124.203) with Microsoft SMTP Server (TLS)
 id 14.3.319.2; Wed, 21 Mar 2018 23:30:42 -0700
Received: from shsmsx102.ccr.corp.intel.com (10.239.4.154) by
 FMSMSX102.amr.corp.intel.com (10.18.124.200) with Microsoft SMTP Server (TLS)
 id 14.3.319.2; Wed, 21 Mar 2018 23:30:41 -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;
 Thu, 22 Mar 2018 14:30:39 +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 V2] Build spec: update description for build handles
 PCDs for SKU support
Thread-Index: AQHTwEPlyXJXgogTik2bB3NQaMmsMqPbzf5Q
Date: Thu, 22 Mar 2018 06:30:39 +0000
Message-ID: <4A89E2EF3DFEDB4C8BFDE51014F606A14E1EB5FA@SHSMSX104.ccr.corp.intel.com>
References: <1521547589-6740-1-git-send-email-yonghong.zhu@intel.com>
In-Reply-To: <1521547589-6740-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 V2] Build spec: update description for build handles PCDs for SKU support
X-BeenThere: edk2-devel@lists.01.org
X-Mailman-Version: 2.1.23
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: Thu, 22 Mar 2018 06:24:16 -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: Tuesday, March 20, 2018 8:06 PM
>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 V2] Build spec: update description for build handles PCDs =
for
>SKU support
>
>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>
>---
> 2_design_discussion/27_sku_support.md | 129
>+++++++++++++++++++++++++++++-----
> 1 file changed, 111 insertions(+), 18 deletions(-)
>
>diff --git a/2_design_discussion/27_sku_support.md
>b/2_design_discussion/27_sku_support.md
>index 18d40b7..891fc93 100644
>--- a/2_design_discussion/27_sku_support.md
>+++ b/2_design_discussion/27_sku_support.md
>@@ -1,9 +1,9 @@
> <!--- @file
>   2.7 SKU Support
>
>-  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:
>
>@@ -31,22 +31,115 @@
>
> ## 2.7 SKU Support
>
> The EDK II build system provides the capability of supporting multiple SK=
Us in
> a single firmware image. SKU selection is a runtime option that can be se=
t
>from
>-a platform driver. During runtime, the configuration elements, PCDs, must=
 be
>-accessed using either Dynamic or DynamicEx PCD access methods. When
>building
>-for multiple SKU support, the FeatureFlag, FixedAtBuild and
>PatchableInModule
>-access methods will only use the default SKU configuration settings. The =
set
>of
>-SKUs that can be included is configurable either through setting the list=
 in
>-the DSC file or through setting commandline options to the build command.
>-
>-The SKU enabled PCD sections are a sparsely populated set of configuratio=
n
>-settings; the PCD drivers will automatically return a default SKU value i=
f no
>-specific SKU value was specified.
>-
>-The build system also supports building a specific SKU. In this mode, it =
is
>-possible to use SKU specific FeatureFlag, FixedAtBuild and
>PatchableInModule
>-access method configuration elements along with the Dynamic and
>DynamicEx PCD
>-for the specific SKU. The build tools will automatically adjust the SKU
>-specific Dynamic and DynamicEx PCD values overriding the default values.
>This
>-is equivalent of running SetSku() immediately on reset.
>+a platform driver. The build system also supports building a specific SKU=
. The
>+SKU enabled PCD sections (defined by a PCD section tag in the DSC file th=
at
>+contains a SKUID modifier that is not DEFAULT) are a sparsely populated s=
et
>of
>+configuration settings. The platform developer may specify one or more
>PCDs that
>+will have different values than the PCD values specified by the default S=
KU.
>+Additional PCDs not listed in a default PCD section may also be specified
>under
>+a section with a SKUID modifier.
>+During runtime, the PCD drivers will automatically return a default SKU v=
alue
>+if no specific SKU value was specified after a platform driver calls SetS=
ku().
>+The configuration elements, PCDs, must be accessed using either Dynamic o=
r
>+DynamicEx PCD access methods. When building and image that supports
>multiple
>+SKUs, the Feature Flag, Fixed At Build and Patchable In Module PCDs will =
only
>+use the default SKU configuration settings. The default configuration set=
tings
>+are identified by PCD section tags that have either a Default SKUID modif=
ier
>+or have not SKUID modifier. The set of SKUs that can be included is
>configurable
>+either through setting the list in the DSC file [Defines] section's
>SKU_IDENTIFIER
>+element or through setting one or more -x SKUID command-line options to
>the build
>+command.
>+When building a single SKU, it is possible to use SKU specific Feature Fl=
ag,
>Fixed
>+At Build and Patchable In Module configuration elements along with the
>Dynamic and
>+DynamicEx PCD for the specific SKU. The build tools will automatically ad=
just
>the
>+SKU specific Dynamic and DynamicEx PCD values overriding the default
>values. This
>+is equivalent of running SetSku immediately on reset.
>+
>+**Note:** If there are no PcdsDynamic or PcdsDynamicEx section tags that
>use a
>+SkuId modifier, then only the DEFAULT values will be placed into the PCD
>Database.
>+The platform drivers must not call SetSku() for this single SKU, as the
>'DEFAULT'
>+SKU will be the only SKU available when built by this method.
>+
>+The following examples show the three types of builds.
>+DEFAULT SKUID Build
>+One or more SKUID | SKUIDENTIFIER entries may appear in the DSC file's
>[SkuIds]
>+section as in the following example:
>+[SkuIds]
>+  0 | DEFAULT
>+  1 | ScsiSku
>+  2 | SataSku
>+  3 | iScsiSku
>+Only the DEFAULT SKU will be built as identified by a single entry in the
>+SKU_IDENTIFIER in the DSC file's [Defines] section as in the following
>example:
>+  SKU_IDENTIFIER =3D DEFAULT
>+The user is not required to specify:
>+  -x DEFAULT
>+FeatureFlag, PatchableInModule and FixedAtBuild PCD values from the
>values in
>+the default PCD sections. Dynamic and DynamicEx PCD values from the
>default
>+PCD sections (sections that do not contain a SkuId modifier in the sectio=
n tag
>+or that contain a SkuId modifier of DEFAULT) must be used. These values w=
ill
>+then be placed in the DEFAULT table of the PCD Database.
>+**WARNING:** The platform drivers must not call SetSku() for this single
>SKU, as
>+the 'DEFAULT' SKU will be the only SKU available when built by this metho=
d.
>+
>+Single SKUID Build
>+This method is useful for debugging as well as for size-optimization.
>+More than one SKUID | SKUIDENTIFIER entry must appear in the DSC file's
>[SkuIds]
>+section as in the following example:
>+[SkuIds]
>+  0 | DEFAULT
>+  1 | ScsiSku
>+  2 | SataSku
>+  3 | iScsiSku
>+Only one of the possible SKUs will be built as identified by a single ent=
ry in
>+the SKU_IDENTIFIER in the DSC file's [Defines] section as in the followin=
g
>example:
>+  SKU_IDENTIFIER =3D ScsiSku
>+**Note:** A SKU_IDENTIFIER =3D DEFAULT | ScsiSku must be treated by tools
>as exactly
>+the same as if just SKU_IDENTIFIER =3D ScsiSku had been specified.
>+If the users specifies the following option on the build command-line, on=
ly
>SataSku
>+SKUID will be included:
>+  -x SataSku
>+The -x SKUIDENTIFIER command-line option overrides the SKU_IDENTIFIER
>statement in
>+the [Defines] section.
>+FeatureFlag, PatchableInModule and FixedAtBuild PCD values from the PCD
>section
>+that contains the matching SKUID modifier will override the values in the
>default
>+PCD sections.
>+Dynamic and DynamicEx PCD values from PCD sections that contain the
>matching SKUID
>+modifier will override the values from the default PCD section. These val=
ues
>will
>+then be placed in the DEFAULT table of the PCD Database. This is equivale=
nt
>of
>+executing a SetSku() immediately on reset/power-on.
>+**WARNING:** The platform drivers must not call SetSku() for this single
>SKU build,
>+as the 'DEFAULT' SKU will be the only SKU available when built by this
>method.
>+
>+Multiple SKUID Build
>+The DEFAULT SKU is always included in a multi-SKU platform build as these
>are the
>+default values returned by PcdGet statements until such time as a platfor=
m
>driver
>+executes a SetSku() call.
>+More than two SKUID | SKUIDENTIFIER entries must appear in the DSC file's
>[SkuIds]
>+section as in the following example:
>+[SkuIds]
>+  0 | DEFAULT
>+  1 | ScsiSku
>+  2 | SataSku
>+  3 | iScsiSku
>+Only two of the possible SKUs will be built as identified by a list of
>SKU_IDENTIFIER
>+in the DSC file's [Defines] section as in the following example:
>+  SKU_IDENTIFIER =3D ScsiSku | SataSku
>+**Note:** A SKU_IDENTIFIER =3D DEFAULT | ScsiSku | SataSku must be
>treated by tools as
>+exactly the same as if this SKU_IDENTIFIER =3D ScsiSku | SataSku  stateme=
nt
>had been
>+specified.
>+If the users specifies the following options on the build command-line, a=
ll of
>the
>+SKUIDs will be included (DEFAULT is always included):
>+  -x ScsiSku -x SataSku -x iScsiSku
>+FeatureFlag, PatchableInModule and FixedAtBuild PCD values must come
>from the default
>+PCD sections; PCD sections for these access types that have a SKUID modif=
ier
>must be
>+ignored by the Build Tools. If a PCD listed in a PCD section with a SKUID
>modifier
>+is NOT listed in the default PCD section, the PCD cannot be used by any
>module
>+included in the build.Dynamic and DynamicEx PCD values from the DEFAULT
>SKU as well
>+as values from the specified SKUs will be put into tables in the PCD Data=
base.
>Prior
>+to a platform driver is calling SetSku(), drivers accessing the PCD datab=
ase will
>get
>+values from the DEFAULT SKU. Once a platform driver calls SetSku(), the
>values for
>+the specific SKU will be returned (unless there is no entry for the PCD i=
n the
>+specific SKU table, in which case, the value will come from the DEFAULT S=
KU
>table).
>--
>2.6.1.windows.1