[meta-intel] [Patch v4 04/12] README: Documentation of hardware features

[nitin.a.kamble at intel.com]

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>
---
 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.
-- 
1.8.1.4