[meta-intel] [Patch v3 03/12] README: Documentation of hardware features

Tue Oct 7 11:00:41 PDT 2014

On 10/3/14, 15:14, "nitin.a.kamble at intel.com" <nitin.a.kamble at intel.com>
wrote:

>From: Nitin A Kamble <nitin.a.kamble at intel.com>

Hi Nitin,

This is looking better. A few mostly readability issues to address below.
Generally speaking the text is more verbose than it needs to be (which is
distracting to the reader and makes it harder to find the necessary
information). Specific examples below.

>
>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 | 95 
>++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 95 insertions(+)
>
>diff --git a/README b/README
>index c829fdb..66b6789 100644
>--- a/README
>+++ b/README
>@@ -83,3 +83,98 @@ 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
>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"

Git convention is that .git is for bare clones, meaning no working tree is
checked out. Suggest eliminating the .git here.

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

for the BSP to use.
Or
for use by the BSP.
Or
to the BSP.

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

An example would be good here, e.g.

MACHINE_FEATURES += "intel-ucode"

>+
>+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 second sentence is redundant and can be removed entirely.

>This feature enables microcode
>+  updating at early boot time by placing the microcode data files in the
>+  initrd image. 

Consider:

This feature runs at early boot via an initrd.

>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?

s/to//

>+  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

the need to change BIOS.

>+     is enabled, it is also possible to update the existing images with
>+     newer microcode update in the future.

with a newer

>+
>+  Q. How to bundle only specific microcodes in the target image?

I think "microcode" is fine here, "microcodes" sounds incorrect... Do you
see "microcodes" used in any of the official documentation? "code"
(without an "s") is typically used to refer to one or many lines of source
or files.

>+  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_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. If the BSP image will be run only on specific processors, then the
>+     microcode data can be filtered to take only the microcode updates
>+     relevant to the processors of interest. To define the
>+     UCODE_FILTER_PARAMETERS variable, one needs to find out the cpuid

s/find out/identify/

>+     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
>+     a microcode 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. It prints cpuid signatures for the
>+     processors in the system. These signatures can then be used in the
>+     UCODE_FILTER_PARAMETERS variable, to select the microcodes with -s
>+     parameter.

This is very verbose in general and could be cut down quite a bit. For
example, you don't need to explicitly state that it prints out the CPU IDs
as that is made obvious in the example.

>+       Example:
>+        [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 (few KB)

a small amount of space (a 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,

Space-sensitive BSPs, ...

>+     may consider not enabling this feature to save the target image
>foot print.

footprint.
Or
may consider not enabling this feature.

Thanks,

-- 
Darren Hart
Intel Open Source Technology Center