Re: [Patch] Build Spec: update chapter 2.7's format

["Gao, Liming" <liming.gao@intel.com>]

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