From nobody Mon Apr 29 15:30:52 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: Received: from ml01.01.org (ml01.01.org [198.145.21.10]) by mx.zohomail.com with SMTPS id 1522658836992624.4154249064682; Mon, 2 Apr 2018 01:47:16 -0700 (PDT) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id 2E23D221467C2; Mon, 2 Apr 2018 01:47:15 -0700 (PDT) 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 32CDD21F85E8A for ; Mon, 2 Apr 2018 01:47:08 -0700 (PDT) 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 01:46:59 -0700 Received: from shwdeopenpsi168.ccr.corp.intel.com ([10.239.158.129]) by fmsmga002.fm.intel.com with ESMTP; 02 Apr 2018 01:46:57 -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.65; helo=mga03.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,394,1517904000"; d="scan'208";a="33451677" From: Yonghong Zhu To: edk2-devel@lists.01.org Date: Mon, 2 Apr 2018 16:46:55 +0800 Message-Id: <1522658815-10616-1-git-send-email-yonghong.zhu@intel.com> X-Mailer: git-send-email 2.6.1.windows.1 Subject: [edk2] [Patch] Build Spec: update chapter 2.7's format X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.26 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Michael Kinney , Kevin W Shaw , Liming Gao MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Errors-To: edk2-devel-bounces@lists.01.org Sender: "edk2-devel" X-ZohoMail: RSF_4 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" This patch update chapter 2.7's format since we found the PDF of this section is ugly. Cc: Liming Gao Cc: Michael Kinney Cc: Kevin W Shaw Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Yonghong Zhu Reviewed-by: Liming Gao --- 2_design_discussion/27_sku_support.md | 130 ++++++++++++++++++++++++------= ---- 1 file changed, 92 insertions(+), 38 deletions(-) diff --git a/2_design_discussion/27_sku_support.md b/2_design_discussion/27= _sku_support.md index 891fc93..83f9f87 100644 --- a/2_design_discussion/27_sku_support.md +++ b/2_design_discussion/27_sku_support.md @@ -31,115 +31,169 @@ =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. 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 +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.=20 +a section with a SKUID modifier. + 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's SKU_ID= ENTIFIER -element or through setting one or more -x SKUID command-line options to th= e build -command. +either through setting the list in the DSC file `[Defines]` section's=20 +`SKU_IDENTIFIER` element or through setting one or more -x SKUID command-l= ine +options to the 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. =20 +********** **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 'D= EFAULT' SKU will be the only SKU available when built by this method. +********** =20 The following examples show the three types of builds. -DEFAULT SKUID Build + +**DEFAULT SKUID Build** One or more SKUID | SKUIDENTIFIER entries may appear in the DSC file's [Sk= uIds] 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 exa= mple: - SKU_IDENTIFIER =3D DEFAULT +``` + +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 + + `-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. +the default PCD sections.=20 + +Dynamic and DynamicEx PCD values from the default PCD sections (sections t= hat +do not contain a SkuId modifier in the section tag or that contain a SkuId +modifier of DEFAULT) must be used. These values will 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 'DEFAULT' SKU will be the only SKU available when built by this method. +********** + =20 -Single SKUID Build +**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 [S= kuIds] + +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 entr= y in -the SKU_IDENTIFIER in the DSC file's [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. +the `SKU_IDENTIFIER` in the DSC file's `[Defines]` section as in the follo= wing +example: + + `SKU_IDENTIFIER =3D ScsiSku` + +********** +**Note:** A `SKU_IDENTIFIER =3D DEFAULT | ScsiSku` must be treated by tool= s 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 -x SKUIDENTIFIER command-line option overrides the SKU_IDENTIFIER stat= ement in -the [Defines] section. + + `-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 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 'DEFAULT' SKU will be the only SKU available when built by this met= hod. +********** =20 -Multiple SKUID Build + +**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's = [SkuIds] + +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 statemen= t had been +``` + +Only two of the possible SKUs will be built as identified by a list of `SK= U_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 treat= ed by tools as +exactly the same as if this `SKU_IDENTIFIER =3D ScsiSku | SataSku` statem= ent 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 + + `-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). +included in the build. + +Dynamic and DynamicEx PCD values from the DEFAULT SKU as well as values fr= om the +specified SKUs will be put into tables in the PCD Database. Prior to a pla= tform driver +is calling SetSku(), drivers accessing the PCD database will get values fr= om the DEFAULT +SKU. Once a platform driver calls SetSku(), the values for the specific SK= U 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 SKU table). --=20 2.6.1.windows.1 _______________________________________________ edk2-devel mailing list edk2-devel@lists.01.org https://lists.01.org/mailman/listinfo/edk2-devel