[meta-intel] [PATCH 03/12] README.hardware: Documentation of hardware features

[Tom Zanussi]

On Thu, 2014-10-02 at 11:27 -0700, nitin.a.kamble at intel.com wrote:
> From: Nitin A Kamble <nitin.a.kamble at intel.com>
> 
> Starting a new documentation file 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 file.
> 
> Signed-off-by: Nitin A Kamble <nitin.a.kamble at intel.com>
> ---
>  README.hardware | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Cc:ing Paul, who had a review comment about this from last time: 

https://lists.yoctoproject.org/pipermail/meta-intel/2014-September/002614.html

Tom

>  1 file changed, 88 insertions(+)
>  create mode 100644 README.hardware
> 
> diff --git a/README.hardware b/README.hardware
> new file mode 100644
> index 0000000..e27fb33
> --- /dev/null
> +++ b/README.hardware
> @@ -0,0 +1,88 @@
> +                    meta-intel Layer Hardware README
> +                    ================================
> +
> +This file gives details about using the meta-intel layer with the machines
> +supported in the layer. A full list of supported reference target machines
> +can be found by looking in the following directories:
> +
> +   conf/machine/
> +   meta-*/conf/machine/
> +   meta-isg/meta-*/conf/machine/
> +
> +The information in this file is also applicable to machines such as as minnow
> +which are defined in separate layers and utilize the meta-intel layer.
> +
> +
> +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 for 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.git"
> +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 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.
> +
> +Details of the Machine Features
> +-------------------------------
> +
> +* intel-ucode: This feature provides microcode updating support for Intel
> +  processors. With the intel-ucode feature, images get complete support for
> +  updating the microcode on Intel processors. This feature enables microcode
> +  updating at early boot time by placing the microcode data files in the
> +  initrd image. It also puts the user land microcode updating tool iucode_tool
> +  and the microcode data file in the target images.
> +
> +  Q. Why to 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 need of changing BIOS. Once the feature
> +     is enabled, it is also possible to update the existing images with
> +     newer microcode update in the future.
> +
> +  Q. How to bundle only specific microcodes 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 microcodes bundled in
> +     the target image can be filtered by specifying the UCODE_FILTER_SIGNATURES
> +     variable. A sequence of iucode-tool parameters are listed in the
> +     UCODE_FILTER_SIGNATURES 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. When to not enable this microcode feature?
> +  A. The microcode datafile and the associated tools take small (few KB)
> +     space 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 foot print.
> +