From nobody Mon May  6 04:31:11 2024
Delivered-To: importer@patchew.org
Authentication-Results: mx.zohomail.com;
	spf=none (zoho.com: 198.145.21.10 is neither permitted nor denied by domain
 of lists.01.org)  smtp.mailfrom=edk2-devel-bounces@lists.01.org
Return-Path: <edk2-devel-bounces@lists.01.org>
Received: from ml01.01.org (ml01.01.org [198.145.21.10]) by mx.zohomail.com
	with SMTPS id 1521535130565624.4831533287069;
 Tue, 20 Mar 2018 01:38:50 -0700 (PDT)
Received: from [127.0.0.1] (localhost [IPv6:::1])
	by ml01.01.org (Postfix) with ESMTP id 8D74D22489C8B;
	Tue, 20 Mar 2018 01:32:19 -0700 (PDT)
Received: from mga06.intel.com (mga06.intel.com [134.134.136.31])
 (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 40478222630CD
 for <edk2-devel@lists.01.org>; Tue, 20 Mar 2018 01:32:17 -0700 (PDT)
Received: from orsmga001.jf.intel.com ([10.7.209.18])
 by orsmga104.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384;
 20 Mar 2018 01:38:47 -0700
Received: from shwdeopenpsi168.ccr.corp.intel.com ([10.239.158.129])
 by orsmga001.jf.intel.com with ESMTP; 20 Mar 2018 01:38:45 -0700
X-Original-To: edk2-devel@lists.01.org
Received-SPF: none (zoho.com: 198.145.21.10 is neither permitted nor denied by
 domain of lists.01.org) client-ip=198.145.21.10;
 envelope-from=edk2-devel-bounces@lists.01.org; helo=ml01.01.org;
Received-SPF: Pass (sender SPF authorized) identity=mailfrom;
 client-ip=134.134.136.31; helo=mga06.intel.com;
 envelope-from=yonghong.zhu@intel.com; receiver=edk2-devel@lists.01.org
X-Amp-Result: SKIPPED(no attachment in message)
X-Amp-File-Uploaded: False
X-ExtLoop1: 1
X-IronPort-AV: E=Sophos;i="5.48,334,1517904000"; d="scan'208";a="40495464"
From: Yonghong Zhu <yonghong.zhu@intel.com>
To: edk2-devel@lists.01.org
Date: Tue, 20 Mar 2018 16:38:42 +0800
Message-Id: <1521535122-8720-1-git-send-email-yonghong.zhu@intel.com>
X-Mailer: git-send-email 2.6.1.windows.1
MIME-Version: 1.0
Subject: [edk2] [Patch] 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>
Cc: Michael Kinney <michael.d.kinney@intel.com>,
 Kevin W Shaw <kevin.w.shaw@intel.com>, Liming Gao <liming.gao@intel.com>
Content-Type: multipart/mixed; boundary="===============4930735649715236973=="
Errors-To: edk2-devel-bounces@lists.01.org
Sender: "edk2-devel" <edk2-devel-bounces@lists.01.org>
X-ZohoMail: RSF_4  Z_629925259 SPT_0

--===============4930735649715236973==
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"

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 | 132 +++++++++++++++++++++++++++++-=
----
 1 file changed, 114 insertions(+), 18 deletions(-)

diff --git a/2_design_discussion/27_sku_support.md b/2_design_discussion/27=
_sku_support.md
index 18d40b7..fb153a8 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
=20
-  Copyright (c) 2008-2017, Intel Corporation. All rights reserved.<BR>
+  Copyright (c) 2008-2018, Intel Corporation. All rights reserved.<BR>
=20
   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 m=
et:
=20
@@ -31,22 +31,118 @@
=20
 ## 2.7 SKU Support
=20
 The EDK II build system provides the capability of supporting multiple SKU=
s in
 a single firmware image. SKU selection is a runtime option that can be set=
 from
-a platform driver. During runtime, the configuration elements, PCDs, must =
be
-accessed using either Dynamic or DynamicEx PCD access methods. When buildi=
ng
-for multiple SKU support, the FeatureFlag, FixedAtBuild and PatchableInMod=
ule
-access methods will only use the default SKU configuration settings. The s=
et 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 configuration
-settings; the PCD drivers will automatically return a default SKU value if=
 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 PatchableInModu=
le
-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. T=
his
-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 that
+contains a SKUID modifier that is not DEFAULT) are a sparsely populated se=
t of
+configuration settings. The platform developer may specify one or more PCD=
s that
+will have different values than the PCD values specified by the default SK=
U.
+Additional PCDs not listed in a default PCD section may also be specified =
under
+a section with a SKUID modifier. It is possible to specify different PCD a=
ccess
+methods for a PCD in sections with SKUID modifiers; a PCD is permitted to =
use
+the PcdsDynamicDefault access method for one SKU and PcdsDynamicVpd for a
+different SKU.
+During runtime, the PCD drivers will automatically return a default SKU va=
lue
+if no specific SKU value was specified after a platform driver calls SetSk=
u().
+The configuration elements, PCDs, must be accessed using either Dynamic or
+DynamicEx PCD access methods. When building and image that supports multip=
le
+SKUs, the Feature Flag, Fixed At Build and Patchable In Module PCDs will o=
nly
+use the default SKU configuration settings. The default configuration sett=
ings
+are identified by PCD section tags that have either a Default SKUID modifi=
er
+or have not SKUID modifier. The set of SKUs that can be included is config=
urable
+either through setting the list in the DSC file [Defines] section=EF=BF=BD=
=EF=BF=BDs SKU_IDENTIFIER
+element or through setting one or more -x SKUID command-line options to th=
e build
+command.
+When building a single SKU, it is possible to use SKU specific Feature Fla=
g, Fixed
+At Build and Patchable In Module configuration elements along with the Dyn=
amic and
+DynamicEx PCD for the specific SKU. The build tools will automatically adj=
ust the
+SKU specific Dynamic and DynamicEx PCD values overriding the default value=
s. This
+is equivalent of running SetSku immediately on reset.
+
+**Note:** If there are no PcdsDynamic or PcdsDynamicEx section tags that u=
se a
+SkuId modifier, then only the DEFAULT values will be placed into the PCD D=
atabase.
+The platform drivers must not call SetSku() for this single SKU, as the =
=EF=BF=BD=EF=BF=BDDEFAULT=EF=BF=BD=EF=BF=BD
+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=EF=BF=
=BD=EF=BF=BDs [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=EF=BF=BD=EF=BF=BDs [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 section=
 tag
+or that contain a SkuId modifier of DEFAULT) must be used. These values wi=
ll
+then be placed in the DEFAULT table of the PCD Database.
+**WARNING:** The platform drivers must not call SetSku() for this single S=
KU, as
+the =EF=BF=BD=EF=BF=BDDEFAULT=EF=BF=BD=EF=BF=BD SKU will be the only SKU a=
vailable when built by this method.
+
+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=EF=
=BF=BD=EF=BF=BDs [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 entr=
y in
+the SKU_IDENTIFIER in the DSC file=EF=BF=BD=EF=BF=BDs [Defines] section as=
 in the following 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, onl=
y SataSku
+SKUID will be included:
+  -x SataSku
+The =EF=BF=BDCx SKUIDENTIFIER command-line option overrides the SKU_IDENTI=
FIER statement in
+the [Defines] section.
+FeatureFlag, PatchableInModule and FixedAtBuild PCD values from the PCD se=
ction
+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 matchi=
ng SKUID
+modifier will override the values from the default PCD section. These valu=
es will
+then be placed in the DEFAULT table of the PCD Database. This is equivalen=
t of
+executing a SetSku() immediately on reset/power-on.
+**WARNING:** The platform drivers must not call SetSku() for this single S=
KU build,
+as the =EF=BF=BD=EF=BF=BDDEFAULT=EF=BF=BD=EF=BF=BD SKU will be the only SK=
U 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 platform=
 driver
+executes a SetSku() call.
+More than two SKUID | SKUIDENTIFIER entries must appear in the DSC file=EF=
=BF=BD=EF=BF=BDs [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=EF=BF=BD=EF=BF=BDs [Defines] section as in the following e=
xample:
+  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  statemen=
t had been
+specified.
+If the users specifies the following options on the build command-line, al=
l 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 modifi=
er 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 mo=
dule
+included in the build.Dynamic and DynamicEx PCD values from the DEFAULT SK=
U as well
+as values from the specified SKUs will be put into tables in the PCD Datab=
ase. Prior
+to a platform driver is calling SetSku(), drivers accessing the PCD databa=
se will get
+values from the DEFAULT SKU. Once a platform driver calls SetSku(), the va=
lues for
+the specific SKU will be returned (unless there is no entry for the PCD in=
 the
+specific SKU table, in which case, the value will come from the DEFAULT SK=
U table).
--=20
2.6.1.windows.1

--===============4930735649715236973==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

_______________________________________________
edk2-devel mailing list
edk2-devel@lists.01.org
https://lists.01.org/mailman/listinfo/edk2-devel

--===============4930735649715236973==--