2_design_discussion/27_sku_support.md | 130 ++++++++++++++++++++++++---------- 1 file changed, 92 insertions(+), 38 deletions(-)
This patch update chapter 2.7's format since we found the PDF of this
section is ugly.
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 | 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 @@
## 2.7 SKU Support
The EDK II build system provides the capability of supporting multiple SKUs 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 set 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 SKU.
Additional PCDs not listed in a default PCD section may also be specified under
-a section with a SKUID modifier.
+a section with a SKUID modifier.
+
During runtime, the PCD drivers will automatically return a default SKU value
if no specific SKU value was specified after a platform driver calls SetSku().
The configuration elements, PCDs, must be accessed using either Dynamic or
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 settings
are identified by PCD section tags that have either a Default SKUID modifier
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.
+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 Flag, 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 adjust 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
+
+**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 = 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 = 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 will
-then be placed in the DEFAULT table of the PCD Database.
+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 will 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 method.
+**********
+
-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 [SkuIds]
+
+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 entry in
-the SKU_IDENTIFIER in the DSC file's [Defines] section as in the following example:
- SKU_IDENTIFIER = ScsiSku
-**Note:** A SKU_IDENTIFIER = DEFAULT | ScsiSku must be treated by tools as exactly
-the same as if just SKU_IDENTIFIER = ScsiSku had been specified.
+the `SKU_IDENTIFIER` in the DSC file's `[Defines]` section as in the following
+example:
+
+ `SKU_IDENTIFIER = ScsiSku`
+
+**********
+**Note:** A `SKU_IDENTIFIER = DEFAULT | ScsiSku` must be treated by tools as exactly
+the same as if just `SKU_IDENTIFIER = ScsiSku` had been specified.
+**********
+
If the users specifies the following option on the build command-line, only SataSku
SKUID will be included:
- -x SataSku
-The -x SKUIDENTIFIER command-line option overrides the SKU_IDENTIFIER statement 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 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 values will
then be placed in the DEFAULT table of the PCD Database. This is equivalent 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
+
+**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 = ScsiSku | SataSku
-**Note:** A SKU_IDENTIFIER = DEFAULT | ScsiSku | SataSku must be treated by tools as
-exactly the same as if this SKU_IDENTIFIER = ScsiSku | SataSku statement had been
+```
+
+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 = ScsiSku | SataSku`
+
+**********
+**Note:** A `SKU_IDENTIFIER = DEFAULT | ScsiSku | SataSku` must be treated by tools as
+exactly the same as if this `SKU_IDENTIFIER = ScsiSku | SataSku` statement had been
specified.
+**********
+
If the users specifies the following options on the build command-line, all 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 modifier 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 Database. Prior
-to a platform driver is calling SetSku(), drivers accessing the PCD database 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 in the
-specific SKU table, in which case, the value will come from the DEFAULT SKU table).
+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 Database. Prior to a platform driver
+is calling SetSku(), drivers accessing the PCD database 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 in the specific SKU table, in which case,
+the value will come from the DEFAULT SKU table).
--
2.6.1.windows.1
_______________________________________________
edk2-devel mailing list
edk2-devel@lists.01.org
https://lists.01.org/mailman/listinfo/edk2-devel
Reviewed-by: Liming Gao <liming.gao@intel.com> >-----Original Message----- >From: Zhu, Yonghong >Sent: Monday, April 02, 2018 4:47 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] Build Spec: update chapter 2.7's format > >This patch update chapter 2.7's format since we found the PDF of this >section is ugly. > >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 | 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 @@ > > ## 2.7 SKU Support > > The EDK II build system provides the capability of supporting multiple SKUs 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 set >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 SKU. > Additional PCDs not listed in a default PCD section may also be specified >under >-a section with a SKUID modifier. >+a section with a SKUID modifier. >+ > During runtime, the PCD drivers will automatically return a default SKU value > if no specific SKU value was specified after a platform driver calls SetSku(). > The configuration elements, PCDs, must be accessed using either Dynamic or > 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 settings > are identified by PCD section tags that have either a Default SKUID modifier > 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. >+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 Flag, >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 adjust >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 >+ >+**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 = 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 = 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 will >-then be placed in the DEFAULT table of the PCD Database. >+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 will 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 method. >+********** >+ > >-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 >[SkuIds] >+ >+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 entry in >-the SKU_IDENTIFIER in the DSC file's [Defines] section as in the following >example: >- SKU_IDENTIFIER = ScsiSku >-**Note:** A SKU_IDENTIFIER = DEFAULT | ScsiSku must be treated by tools >as exactly >-the same as if just SKU_IDENTIFIER = ScsiSku had been specified. >+the `SKU_IDENTIFIER` in the DSC file's `[Defines]` section as in the following >+example: >+ >+ `SKU_IDENTIFIER = ScsiSku` >+ >+********** >+**Note:** A `SKU_IDENTIFIER = DEFAULT | ScsiSku` must be treated by >tools as exactly >+the same as if just `SKU_IDENTIFIER = ScsiSku` had been specified. >+********** >+ > If the users specifies the following option on the build command-line, only >SataSku > SKUID will be included: >- -x SataSku >-The -x SKUIDENTIFIER command-line option overrides the SKU_IDENTIFIER >statement 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 >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 values >will > then be placed in the DEFAULT table of the PCD Database. This is equivalent >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 >+ >+**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 = ScsiSku | SataSku >-**Note:** A SKU_IDENTIFIER = DEFAULT | ScsiSku | SataSku must be treated >by tools as >-exactly the same as if this SKU_IDENTIFIER = ScsiSku | SataSku statement >had been >+``` >+ >+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 = ScsiSku | SataSku` >+ >+********** >+**Note:** A `SKU_IDENTIFIER = DEFAULT | ScsiSku | SataSku` must be >treated by tools as >+exactly the same as if this `SKU_IDENTIFIER = ScsiSku | SataSku` statement >had been > specified. >+********** >+ > If the users specifies the following options on the build command-line, all 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 modifier >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 Database. >Prior >-to a platform driver is calling SetSku(), drivers accessing the PCD database 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 in the >-specific SKU table, in which case, the value will come from the DEFAULT SKU >table). >+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 Database. Prior to a platform >driver >+is calling SetSku(), drivers accessing the PCD database 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 in the specific SKU table, in >which case, >+the value will come from the DEFAULT SKU table). >-- >2.6.1.windows.1 _______________________________________________ edk2-devel mailing list edk2-devel@lists.01.org https://lists.01.org/mailman/listinfo/edk2-devel
© 2016 - 2024 Red Hat, Inc.