summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorNitin A Kamble <nitin.a.kamble@intel.com>2014-09-23 17:26:23 -0700
committerTom Zanussi <tom.zanussi@linux.intel.com>2014-10-21 14:39:46 -0500
commitff7513f7fcb646425b89b7e47e6f9dcf72676d9a (patch)
tree52b2d20540da24c12ea1d51f771c1245e8a4288a
parentc64ade471ab70860604db2ade19ec6cfe9504f50 (diff)
downloadmeta-intel-ff7513f7fcb646425b89b7e47e6f9dcf72676d9a.tar.gz
README: Add documentation for Intel-specific machine features
Start a new documentation section in the top-level README to describe Intel layer-specific machine features. Te intel-ucode machine feature is described first. In the future more such features will added to this section. Signed-off-by: Nitin A Kamble <nitin.a.kamble@intel.com> Signed-off-by: Tom Zanussi <tom.zanussi@linux.intel.com>
-rw-r--r--README111
1 files changed, 111 insertions, 0 deletions
diff --git a/README b/README
index c829fdb4..75dc30e4 100644
--- a/README
+++ b/README
@@ -83,3 +83,114 @@ The meta-intel maintainers will do their best to review and/or pull in
83a patch or patchset within 24 hours of the time it was posted. For 83a patch or patchset within 24 hours of the time it was posted. For
84larger and/or more involved patches and patchsets, the review process 84larger and/or more involved patches and patchsets, the review process
85may take longer. 85may take longer.
86
87
88Intel-specific machine features
89===============================
90
91The meta-intel layer makes some additional machine features available
92to BSPs. These machine features can be used in a BSP layer in the
93same way that machine features are used in other layers based on
94oe-core, via the MACHINE_FEATURES variable.
95
96Requirements
97------------
98
99The meta-intel-specific machine features are only available to a BSP
100when the meta-intel layer is included in the build configuration, and
101the meta-intel.inc file is included in the machine configuration of
102that BSP.
103
104To make these features available for your machine, you will need to:
105
106 1. include a configuration line such as the below in bblayers.conf
107 BBLAYERS += "<local path>/meta-intel"
108 2. include the following line in the machine configuration file
109 require conf/machine/include/meta-intel.inc
110
111Once the above requirements are met, the machine features provided by
112the meta-intel layer will be available for the BSP to use.
113
114Available machine features
115--------------------------
116
117Currently, the meta-intel layer makes the following set of
118Intel-specific machine features available:
119
120 * intel-ucode
121
122These machine features can be included by listing them in the
123MACHINE_FEATURES variable in the machine configuration file. For
124example:
125
126 MACHINE_FEATURES += "intel-ucode"
127
128Machine feature details
129-----------------------
130
131 * intel-ucode
132
133 This feature provides support for microcode updates to Intel
134 processors. The intel-ucode feature runs at early boot and uses
135 the microcode data file added by the feature into the BSP's
136 initrd. It also puts the userland microcode-updating tool,
137 iucode_tool, into the target images along with the microcode data
138 file.
139
140 Q. Why might a user want to enable the intel-ucode feature?
141
142 A. Intel releases microcode updates to correct processor behavior
143 as documented in the respective processor specification
144 updates. While the normal approach to getting such microcode
145 updates is via a BIOS upgrade, this can be an administrative
146 hassle and not always possible in the field. The intel-ucode
147 feature enables the microcode update capability present in the
148 Linux kernel. It provides an easy path for upgrading processor
149 microcode without the need to change the BIOS. If the feature
150 is enabled, it is also possible to update the existing target
151 images with a newer microcode update in the future.
152
153 Q. How would a user bundle only target-specific microcode in the
154 target image?
155
156 A. The Intel microcode data file released by Intel contains
157 microcode updates for multiple processors. If the BSP image is
158 meant to run on only a certain subset of processor types, a
159 processor-specific subset of microcode can be bundled into the
160 target image via the UCODE_FILTER_PARAMETERS variable. This
161 works by listing a sequence of iucode-tool parameters in the
162 UCODE_FILTER_PARAMETERS variable, which in this case will
163 select only the specific microcode relevant to the BSP. For
164 more information on the underlying parameters refer to the
165 iucode-tool manual page at http://manned.org/iucode-tool
166
167 To define a set of parameters for microcode-filtering via the
168 UCODE_FILTER_PARAMETERS variable, one needs to identify the
169 cpuid signatures of all the processors the BSP is meant to run
170 on. One way to determine the cpuid signature for a specific
171 processor is to build and run an intel-ucode-feature-enabled
172 image on the target hardware, without first assigning any value
173 to the UCODE_FILTER_PARAMETERS variable, and then once the
174 image is booted, run the "ucode_tool -S" command to have the
175 ucode tool scan the system for processor signatures. These
176 signatures can then be used in the UCODE_FILTER_PARAMETERS
177 variable in conjunction with -s parameter. For example, for
178 the fri2 BSP, the cpuid can be determined as such:
179
180 [root@fri2 ~]# iucode_tool -S
181 iucode_tool: system has processor(s) with signature 0x00020661
182
183 Given that output, a suitable UCODE_FILTER_PARAMETERS variable
184 definition could be specified in the machine configuration as
185 such:
186
187 UCODE_FILTER_PARAMETERS = "-s 0x00020661"
188
189 Q. Are there any reasons a user might want to disable the
190 intel-ucode feature?
191
192 A. The microcode data file and associated tools occupy a small
193 amount of space (a few KB) on the target image. BSPs which are
194 highly sensitive to target image size and which are not
195 experiencing microcode-related issues might consider not
196 enabling this feature.