[meta-intel] [Patch v4 04/12] README: Documentation of hardware features
Tom Zanussi
tom.zanussi at intel.com
Tue Oct 21 09:02:21 PDT 2014
On Thu, 2014-10-16 at 19:03 -0700, nitin.a.kamble at intel.com wrote:
> From: Nitin A Kamble <nitin.a.kamble at intel.com>
>
> Starting a new documentation section to describe the layer specific hardware
> features. At this point the intel-ucode machine feature is described here.
> In the future more such features will be described in this section.
>
> Signed-off-by: Nitin A Kamble <nitin.a.kamble at intel.com>
I went through and made a bunch of changes to this, nothing substantive,
but rather than enumerating every change in-line, I'm just posting the
diff.
Please review and see if it looks ok.
Tom
diff --git a/README b/README
index 5b8217d..60811b1 100644
--- a/README
+++ b/README
@@ -85,93 +85,113 @@ larger and/or more involved patches and patchsets, the review process
may take longer.
-Machine Features in the meta-intel layer
-========================================
+Intel-specific machine features
+===============================
-Many machine features are available in the oecore/poky layer for BSP use.
-The meta-intel layer makes some additional machine features available to BSPs
-using the meta-intel layer.
+The meta-intel layer makes some additional machine features available
+to BSPs. These machine features can be used in a BSP layer in the
+same way that machine features are used in other layers based on
+oe-core, via the MACHINE_FEATURES variable.
Requirements
------------
-The additional machine features are only available when the meta-intel layer
-is included in the build config, and the meta-intel.inc file is included in
-the machine configuration of the interested BSP.
+The meta-intel-specific machine features are only available to a BSP
+when the meta-intel layer is included in the build configuration, and
+the meta-intel.inc file is included in the machine configuration of
+that BSP.
To make these features available for your machine, you will need to:
-1. have a configuration line as seen below in the bblayers.conf
+ 1. include a configuration line such as the below in bblayers.conf
BBLAYERS += "<local path>/meta-intel"
-2. have the following line in the machine configuration
+ 2. include the following line in the machine configuration file
require conf/machine/include/meta-intel.inc
-Once the above requirements are met, then the machine features provided by
+Once the above requirements are met, the machine features provided by
the meta-intel layer will be available for the BSP to use.
-Available Machine Features
+Available machine features
--------------------------
-As of now the meta-intel layer provides the following list of machine features.
-In the future, more machine features may be available in this list.
+Currently, the meta-intel layer makes the following set of
+Intel-specific machine features available:
-* intel-ucode
+ * intel-ucode
+
+These machine features can be included by listing them in the
+MACHINE_FEATURES variable in the machine configuration file. For
+example:
-These machine features can be included by listing them in the MACHINE_FEATURES
-variable in the machine configuration file.
-For example:
MACHINE_FEATURES += "intel-ucode"
-Details of the Machine Features
--------------------------------
-
-* intel-ucode: This feature provides microcode updating support for Intel
- processors. This feature runs at early boot and uses the microcode data
- file from initrd. It also puts the user land microcode updating tool
- iucode_tool and the microcode data file in the target images.
-
- Q. Why enable this microcode feature?
- A. Intel releases microcode updates to correct processor behavior as
- documented in the respective processor specification updates. While
- the regular approach to getting this microcode update is via a BIOS
- upgrade, this can be an administrative hassle and not always possible
- in the field. The intel-ucode feature enables the microcode update
- capability from the Linux OS. It provides an easy path for upgrading
- processor microcode without the need to change BIOS. Once the feature
- is enabled, it is also possible to update the existing images with
- a newer microcode update in the future.
-
- Q. How to bundle only specific microcode in the target image?
- A. The Intel microcode data file released by Intel contains microcode
- updates for multiple processors. If the BSP image will be running only
- on a certain kind of processors, then the number of microcode bundled in
- the target image can be filtered by specifying the UCODE_FILTER_PARAMETERS
- variable. A sequence of iucode-tool parameters are listed in the
- UCODE_FILTER_PARAMETERS variable to filter the microcodes from the
- microcode data file. For more information on these parameters refer to
- the iucode-tool manual page, which can be seen over here:
+Machine feature details
+-----------------------
+
+ * intel-ucode
+
+ This feature provides support for microcode updates to Intel
+ processors. The intel-ucode feature runs at early boot and uses
+ the microcode data file added by the feature into the BSP's
+ initrd. It also puts the userland microcode-updating tool,
+ iucode_tool, into the target images along with the microcode data
+ file.
+
+ Q. Why might a user want to enable the intel-ucode feature?
+
+ A. Intel releases microcode updates to correct processor behavior
+ as documented in the respective processor specification
+ updates. While the normal approach to getting such microcode
+ updates is via a BIOS upgrade, this can be an administrative
+ hassle and not always possible in the field. The intel-ucode
+ feature enables the microcode update capability present in the
+ Linux kernel. It provides an easy path for upgrading processor
+ microcode without the need to change the BIOS. If the feature
+ is enabled, it is also possible to update the existing target
+ images with a newer microcode update in the future.
+
+ Q. How would a user bundle only target-specific microcode in the
+ target image?
+
+ A. The Intel microcode data file released by Intel contains
+ microcode updates for multiple processors. If the BSP image is
+ meant to run on only a certain subset of processor types, a
+ processor-specific subset of microcode can be bundled into the
+ target image via the UCODE_FILTER_PARAMETERS variable. This
+ works by listing a sequence of iucode-tool parameters in the
+ UCODE_FILTER_PARAMETERS variable, which in this case will
+ remove any microcode other than that specified by the
+ parameters listed in the variable. For more information on the
+ underlying parameters refer to the iucode-tool manual page at
http://manned.org/iucode-tool
- Q. How to define the UCODE_FILTER_PARAMETERS variable for a BSP?
- A. To define the UCODE_FILTER_PARAMETERS variable, one needs to identify
- the cpuid signatures of all the processors the BSP can run on. An easy
- way to find the cpuid signature of the board processors is to build
- and run an intel-ucode feature enabled image on the target hardware,
- without first assigning any value to the UCODE_FILTER_PARAMETERS
- variable. Once the image is booted, then run the "ucode_tool -S"
- command to scan the system for processor signatures. These signatures
- can then be used in the UCODE_FILTER_PARAMETERS variable, to select
- the microcodes with -s parameter.
- For example for FRI2 BSP:
- [root at fri2 ~]# iucode_tool -S
- iucode_tool: system has processor(s) with signature 0x00020661
-
- Define UCODE_FILTER_PARAMETERS in the machine configuration as:
- UCODE_FILTER_PARAMETERS = "-s 0x00020661"
-
- Q. When to not enable this microcode feature?
- A. The microcode datafile and the associated tools take small amount of
- space (a few KB) on the target image. The BSPs which are highly sensitive
- to the target image size, which are not experiencing any microcode related
- issues, may consider not enabling this feature to save the target image
- footprint.
+ To define a set of parameters for microcode-filtering via the
+ UCODE_FILTER_PARAMETERS variable, one needs to identify the
+ cpuid signatures of all the processors the BSP is meant to run
+ on. One way to determine the cpuid signature for a specific
+ processor is to build and run an intel-ucode-feature-enabled
+ image on the target hardware, without first assigning any value
+ to the UCODE_FILTER_PARAMETERS variable, and then once the
+ image is booted, run the "ucode_tool -S" command to have the
+ ucode tool scan the system for processor signatures. These
+ signatures can then be used in the UCODE_FILTER_PARAMETERS
+ variable in conjunction with -s parameter. For example, for
+ the fri2 BSP, the cpuid can be determined as such:
+
+ [root at fri2 ~]# iucode_tool -S
+ iucode_tool: system has processor(s) with signature 0x00020661
+
+ Given that output, a suitable UCODE_FILTER_PARAMETERS variable
+ definition could be specified in the machine configuration as
+ such:
+
+ UCODE_FILTER_PARAMETERS = "-s 0x00020661"
+
+ Q. Are there any reasons a user might want to disable the
+ intel-ucode feature?
+
+ A. The microcode data file and associated tools occupy a small
+ amount of space (a few KB) on the target image. BSPs which are
+ highly sensitive to target image size and which are not
+ experiencing microcode-related issues might consider not
+ enabling this feature.
> ---
> README | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 92 insertions(+)
>
> diff --git a/README b/README
> index c829fdb..5b8217d 100644
> --- a/README
> +++ b/README
> @@ -83,3 +83,95 @@ The meta-intel maintainers will do their best to review and/or pull in
> a patch or patchset within 24 hours of the time it was posted. For
> larger and/or more involved patches and patchsets, the review process
> may take longer.
> +
> +
> +Machine Features in the meta-intel layer
> +========================================
> +
> +Many machine features are available in the oecore/poky layer for BSP use.
> +The meta-intel layer makes some additional machine features available to BSPs
> +using the meta-intel layer.
> +
> +Requirements
> +------------
> +
> +The additional machine features are only available when the meta-intel layer
> +is included in the build config, and the meta-intel.inc file is included in
> +the machine configuration of the interested BSP.
> +
> +To make these features available for your machine, you will need to:
> +
> +1. have a configuration line as seen below in the bblayers.conf
> + BBLAYERS += "<local path>/meta-intel"
> +2. have the following line in the machine configuration
> + require conf/machine/include/meta-intel.inc
> +
> +Once the above requirements are met, then the machine features provided by
> +the meta-intel layer will be available for the BSP to use.
> +
> +Available Machine Features
> +--------------------------
> +
> +As of now the meta-intel layer provides the following list of machine features.
> +In the future, more machine features may be available in this list.
> +
> +* intel-ucode
> +
> +These machine features can be included by listing them in the MACHINE_FEATURES
> +variable in the machine configuration file.
> +For example:
> + MACHINE_FEATURES += "intel-ucode"
> +
> +Details of the Machine Features
> +-------------------------------
> +
> +* intel-ucode: This feature provides microcode updating support for Intel
> + processors. This feature runs at early boot and uses the microcode data
> + file from initrd. It also puts the user land microcode updating tool
> + iucode_tool and the microcode data file in the target images.
> +
> + Q. Why enable this microcode feature?
> + A. Intel releases microcode updates to correct processor behavior as
> + documented in the respective processor specification updates. While
> + the regular approach to getting this microcode update is via a BIOS
> + upgrade, this can be an administrative hassle and not always possible
> + in the field. The intel-ucode feature enables the microcode update
> + capability from the Linux OS. It provides an easy path for upgrading
> + processor microcode without the need to change BIOS. Once the feature
> + is enabled, it is also possible to update the existing images with
> + a newer microcode update in the future.
> +
> + Q. How to bundle only specific microcode in the target image?
> + A. The Intel microcode data file released by Intel contains microcode
> + updates for multiple processors. If the BSP image will be running only
> + on a certain kind of processors, then the number of microcode bundled in
> + the target image can be filtered by specifying the UCODE_FILTER_PARAMETERS
> + variable. A sequence of iucode-tool parameters are listed in the
> + UCODE_FILTER_PARAMETERS variable to filter the microcodes from the
> + microcode data file. For more information on these parameters refer to
> + the iucode-tool manual page, which can be seen over here:
> + http://manned.org/iucode-tool
> +
> + Q. How to define the UCODE_FILTER_PARAMETERS variable for a BSP?
> + A. To define the UCODE_FILTER_PARAMETERS variable, one needs to identify
> + the cpuid signatures of all the processors the BSP can run on. An easy
> + way to find the cpuid signature of the board processors is to build
> + and run an intel-ucode feature enabled image on the target hardware,
> + without first assigning any value to the UCODE_FILTER_PARAMETERS
> + variable. Once the image is booted, then run the "ucode_tool -S"
> + command to scan the system for processor signatures. These signatures
> + can then be used in the UCODE_FILTER_PARAMETERS variable, to select
> + the microcodes with -s parameter.
> + For example for FRI2 BSP:
> + [root at fri2 ~]# iucode_tool -S
> + iucode_tool: system has processor(s) with signature 0x00020661
> +
> + Define UCODE_FILTER_PARAMETERS in the machine configuration as:
> + UCODE_FILTER_PARAMETERS = "-s 0x00020661"
> +
> + Q. When to not enable this microcode feature?
> + A. The microcode datafile and the associated tools take small amount of
> + space (a few KB) on the target image. The BSPs which are highly sensitive
> + to the target image size, which are not experiencing any microcode related
> + issues, may consider not enabling this feature to save the target image
> + footprint.
More information about the meta-intel
mailing list