[meta-intel] [Patch v4 04/12] README: Documentation of hardware features
Kamble, Nitin A
nitin.a.kamble at intel.com
Tue Oct 21 10:07:16 PDT 2014
On 10/21/14, 9:02 AM, "Zanussi, Tom" <tom.zanussi at intel.com> wrote:
>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.
Looks ok mostly, some specific changes suggested below.
Thanks,
Nitin
>
>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.
Š which I this case will select only the specific microcode relevant to
the BSP.
>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