1IUCODE_TOOL(8) iucode_tool manual IUCODE_TOOL(8)
2
6 iucode_tool - Tool to manipulate Intel® IA‐32/X86‐64 microcode bundles
7
9 iucode_tool [options] [[-ttype] filename|dirname] ...
10
12 iucode_tool is an utility that can load Intel® processor microcode data
13 from files in both text and binary microcode bundle formats.
14 It can output a list of the microcodes in these files, merge them,
16 upload them to the kernel (to upgrade the microcode in the system pro‐
17 cessor cores) or write some of them out to a file in binary format for
18 later use.
19 iucode_tool will load all microcodes in the specified files and direc‐
21 tories to memory, in order to process them. Duplicated and outdated
22 microcodes will be discarded. It can read microcode data from standard
23 input (stdin), by specifying a file name of “-” (minus sign).
24 Microcode data files are assumed to be in .dat text format if they have
26 a .dat suffix, and to be in binary format otherwise. Standard input
27 (stdin) is assumed to be in .dat text format. The -t option can be
28 used to change the type of the files specified after it, including for
29 stdin.
30 If a directory is specified, all files whose names do not begin with a
32 dot will be loaded, in unspecified order. Nested directories are
33 skipped.
34 Empty files and directories are ignored, and will be skipped.
36 You can select which microcodes should be written out, listed or
38 uploaded to the kernel using the -S, -s, --date-before and --date-after
39 options. Should none of those options be specified, all microcodes
40 will be selected.
41 You can upload the selected microcodes to the kernel, write them out to
43 a file (in binary format), to a Linux early initramfs archive, to per‐
44 processor‐signature files in a directory, or to per‐microcode files in
45 a directory using the -w, --write-earlyfw, -k, -K, and -W options.
46 iucode_tool will identify microcodes in its output and error messages
48 using a “n/k” notation, where “n” is the bundle number, and “k” is the
49 microcode number within that bundle. The output of the --list-all
50 option when processing multiple input files is the best example of how
51 it works.
52 For more information about Intel processor microcodes, please read the
55 included documentation and the Intel manuals listed in the SEE ALSO
56 section.
57
60 iucode_tool accepts the following options:
61 -q, --quiet
64 Inhibit usual output.
65 -v, --verbose
67 Print more information. Use more than once for added verbosity.
68 -h, -?, --help
70 List all available options and their meanings.
71 --usage
73 Show summary of options.
74 -V, --version
76 Show version of program.
77 -t type
80 Sets the file type of the following files. type can be:
81 b binary format. This is the same format used by the ker‐
83 nel driver and the BIOS/EFI, which is described in detail
84 by the Intel 64 and IA‐32 Architectures Software Devel‐
85 oper's Manual, Volume 3A, section 9.11.
86 d Intel microcode .dat text format. This is the format
88 normally used by Intel to distribute microcode data
89 files.
90 r recover microcode in binary format. Search uncompressed
92 generic binary files for microcodes in Intel microcode
93 binary format to recover. Note: It can find microcode
94 that will not pass strict checks, and thus cause
95 iucode_tool to exit if the --no-strict-checks or
96 --ignore-broken options are not in effect.
97 a (default) iucode_tool will use the suffix of the file
99 name to select the file type: .dat text format for files
100 that have a .dat suffix, and binary type otherwise. Note
101 that for stdin, .dat text format is assumed.
102 --downgrade
105 When multiple versions of the microcode for a specific processor
106 are available from different files, keep the one from the file
107 loaded last, regardless of revision levels. Files are always
108 loaded in the order they were specified in the command line.
109 This option has no effect when just one file has been loaded.
110 --no-downgrade
113 When multiple versions of the microcode for a specific processor
114 are available from different files, keep the one with the high‐
115 est revision level. This is the default mode of operation.
116 --strict-checks
119 Perform strict checks on the microcode data. It will refuse to
120 load microcodes and microcode data files with unexpected size
121 and metadata. It will also refuse to load microcode entries
122 that have the same metadata, but different payload. This is the
123 default mode of operation.
124 --no-strict-checks
127 Perform less strict checks on the microcode data. Use only if
128 you happen to come across a microcode data file that has
129 microcodes with weird sizes or incorrect non‐critical metadata
130 (such as invalid dates), which you want to retain. If you just
131 want to skip those, use the --ignore-broken option.
132 --ignore-broken
135 Skip broken microcode entries when loading a microcode data
136 file, instead of aborting program execution. If the microcode
137 entry has an unsupported format or had its header severely cor‐
138 rupted, all remaining data in the file will have to be ignored.
139 In that case, using a file type of recover microcode in binary
140 format (-tr option) is recommended, as it can skip over badly
141 mangled microcode data.
142 --no-ignore-broken
145 Abort program execution if a broken microcode is found while
146 loading a microcode data file. This is the default mode of
147 operation.
148 -s ! | [!]signature[,[pf_mask][,[lt:|eq:|gt:]revision]]
152 Select microcodes by the specified signature, processor flags
153 mask (pf_mask), and revision.
154 If the processor flags mask is specified, it will select only
156 microcodes that are suitable for at least one of the processor
157 flag combinations present in the mask.
158 If the revision is specified, optionally prefixed by one of the
160 “eq:”, “lt:” or “gt:” operators, it will select only microcodes
161 that have that same revision (if no operator, or if the “eq:”
162 operator is used), or microcodes that have a revision that is
163 less than (“lt:” operator), or greater than (“gt:” operator),
164 the one specified.
165 Specify more than once to select more microcodes. This option
167 can be combined with the --scan-system option to select more
168 microcodes. If signature is prefixed with a “!” (exclamation
169 mark), it will deselect microcodes instead. Ordering matters,
170 with later -s options overriding earlier ones, including
171 --scan-system.
172 When specifying signature and pf_mask, hexadecimal numbers must
174 be prefixed with “0x”, and octal numbers with “0”. Decimal num‐
175 bers must not have leading zeros, otherwise they would be inter‐
176 preted as octal numbers.
177 The special notation -s! (with no signature parameter) instructs
179 iucode_tool to require explicit inclusion of microcode signa‐
180 tures (using the non-negated form of -s, or using --scan-sys‐
181 tem).
182 -S, --scan-system[=mode]
185 Select microcodes by scanning online processors on this system
186 for their signatures.
187 This option can be used only once, and it can be combined with
189 the -s option to select more microcodes. The microcodes
190 selected by --scan-system can also be deselected by a later
191 -s !signature option.
192 The optional mode argument (accepted only by the long version of
194 the option) selects the strategy used to scan processors:
195 0 or auto
197 Currently the same as fast, but this might change in
198 future versions if Intel ever deploys multi‐signature
199 systems that go beyond mixed‐stepping. This is the
200 default mode of operation, for backwards compatibility
201 with previous versions of iucode_tool.
202 1 or fast
204 Uses the cpuid instruction to detect the signature of the
205 processor iucode_tool is running on, and selects all
206 steppings for that processor's type, family and model.
207 Supports mixed‐stepping systems.
208 2 or exact
210 Uses kernel drivers to scan the signature of every online
211 processor directly. This mode supports multi‐signature
212 systems. This scan mode will be slow on large systems
213 with many processors, and likely requires special permis‐
214 sions (such as running as the root user). Should the
215 scan fail for any reason, as a fail‐safe measure, it will
216 issue an warning and consider all possible steppings for
217 every signature it did manage to scan successfully.
218 --date-before=YYYY-MM-DD and --date-after=YYYY-MM-DD
221 Limit the selected microcodes by a date range. The date must be
222 given in ISO format, with four digits for the year and two dig‐
223 its for the month and day and “-” (minus sign) for the separa‐
224 tor. Dates are not range‐checked, so you can use
225 --date-after=2000-00-00 to select all microcodes dated since
226 January 1st, 2000.
227 --loose-date-filtering
230 When a date range is specified, all revisions of the microcode
231 will be considered for selection (ignoring just the date range,
232 all other filters still apply) should any of the microcode's
233 revisions be within the date range.
234 --strict-date-filtering
237 When a date range is specified, select only microcodes which are
238 within the date range. This is the default mode of operation.
239 -l, --list
242 List selected microcode signatures to standard output (stdout).
243 -L, --list-all
245 List all microcode signatures while they're being processed to
246 standard output (stdout).
247 -k[device], --kernel[=device]
250 Upload selected microcodes to the kernel. Optionally, the
251 device path can be specified (default: /dev/cpu/microcode).
252 This update method is deprecated: it will be removed eventually
253 from the kernel and from iucode_tool.
254 -K[directory], --write-firmware[=directory]
256 Write selected microcodes with the file names expected by the
257 Linux kernel firmware loader. Optionally, the destination
258 directory can be specified (default: /lib/firmware/intel‐ucode).
259 -wfile, --write-to=file
262 Write selected microcodes to a file in binary format.
263 --write-earlyfw=file
266 Write selected microcodes to an early initramfs archive, which
267 should be prepended to the regular initramfs to allow the kernel
268 to update processor microcode very early during system boot.
269 -Wdirectory, --write-named-to=directory
272 Write selected microcodes to the specified directory, one
273 microcode per file, in binary format. The file names reflect
274 the microcode signature, processor flags mask and revision.
275 --write-all-named-to=directory
278 Write every microcode to the specified directory, one microcode
279 per file, in binary format. The file names reflect the
280 microcode signature, processor flags mask and revision. This is
281 the only way to write out every revision of the same microcode.
282 --overwrite
285 Remove the destination file before writing, if it exists and is
286 not a directory. The destination file is not overwritten in‐
287 place. Hardlinks will be severed, and any existing access per‐
288 missions, ACLs and other extended attributes of the old destina‐
289 tion file will be lost.
290 --no-overwrite
293 Abort if the destination file already exists. This is the
294 default mode of operation. Do note that iucode_tool does not
295 follow non‐directory symlinks when writing files.
296 --mini-earlyfw
299 Optimize the early initramfs cpio container for minimal size.
300 It will change the cpio block size to 16 bytes, and remove
301 header entries for the parent directories of the microcode data
302 file. As a result, the microcode data file will not be avail‐
303 able to the regular initramfs, and tools might complain about
304 the non‐standard cpio block size.
305 This will typically reduce the early initramfs size by 736
307 bytes.
308 --normal-earlyfw
311 Optimize the early initramfs size for tool compatibility. This
312 is the default mode of operation. The microcode data file will
313 be available inside the regular initramfs as well.
314
317 iucode_tool reads all data to memory before doing any processing. It
318 enforces a sanity limit of a maximum of 1GiB worth of binary microcode
319 data per microcode data file.
320 All informational and error messages are sent to standard error
323 (stderr), while user‐requested output (such as output generated by the
324 list options) is sent to standard output (stdout).
325 iucode_tool creates files with permissions 0644 (rw-r--r--), modified
328 by the current umask.
329 iucode_tool's selected microcode listing and microcode output files are
332 sorted first by processor signature (in ascending order), and then by
333 processor flags mask (in descending order).
334 When multiple revisions of a microcode are selected, the older ones
337 will be skipped. Only the newest selected revision of a microcode (or
338 the last one in load order when the --downgrade option is active) will
339 be written to a file or uploaded to the kernel.
340 Intel microcode data files, both in binary and text formats, can be
343 concatenated to generate a bigger and still valid microcode data file.
344 iucode_tool does not follow symlinks when writing microcode data files.
347 It will either refuse to write the file and abort (default mode of
348 operation), or (when the --overwrite option is active) it will remove
349 the target symlink or file (and therefore breaking hardlinks) before
350 writing the new file.
351 iucode_tool does follow directory symlinks to locate the directory to
354 write files into.
355 Linux Notes
358 Before Linux v4.4, the microcode update driver was split in two parts:
359 the early microcode update driver (which gets microcode data from the
360 initramfs) and the late microcode update driver, which could be a mod‐
361 ule and got microcode data from the firmware subsystem. The two driv‐
362 ers were unified in Linux v4.4.
363 The microcode update driver needs to be present in the system at all
365 times to ensure microcode updates are reapplied on resume from suspend
366 and CPU hotplug. Do not unload the microcode module, unless you really
367 know better. Since Linux v4.4, the late microcode driver cannot be a
368 module anymore and will always be present in the system when enabled.
369 Updating microcode early is safer. It can only be done at boot and it
371 requires an initramfs, but it is strongly recommended: late microcode
372 updates (which read microcode data from /lib/firmware) cannot safely
373 change visible processor features.
374 Early microcode updates are available since Linux v3.9. They can
376 safely change visible processor features (such as the microcode updates
377 that disabled Intel TSX instructions on Intel Haswell cores do). They
378 require an uncompressed initramfs image with the microcode update data
379 in /kernel/x86/microcode/GenuineIntel.bin. This uncompressed initramfs
380 image must come before any compressed initramfs image(s), and it has an
381 special name: early initramfs.
382 The microcode update data inside the early initramfs image must be
384 aligned to a 16‐byte boundary due to a bug in several versions of the
385 Linux kernel early microcode update driver. This requires special
386 steps when creating the initramfs archive with the microcode data, and
387 will be handled automatically by the iucode_tool --write-earlyfw
388 option.
389 Since Linux v4.2, it is also possible to build a kernel with the
391 microcode update data as built‐in firmware, using the CON‐
392 FIG_FIRMWARE_IN_KERNEL facility. This feature is not yet mature as of
393 Linux v4.2.8, v4.4.11, v4.5.5 and v4.6, and might not work in every
394 case.
395 The /dev/cpu/microcode update interface has been deprecated and should
397 not be used. It has one special requirement: each write syscall must
398 contain whole microcode(s). It can be accessed through iucode_tool
399 --kernel.
400 Up to Linux v3.5, late microcode updates were required to be triggered
402 per‐core, by writing the number 1 to /sys/devices/sys‐
403 tem/cpu/*/microcode/reload for every cpu. Depending on kernel version,
404 you must either trigger it on every core to avoid a dangerous situation
405 where some cores are using outdated microcode, or the kernel will
406 accept the request only for the boot processor and use it to trigger an
407 update on all system processor cores.
408 Since Linux v3.6, the late microcode update driver has a new interface
410 that explicitly triggers an update for every core at once when the num‐
411 ber 1 is written to /sys/devices/system/cpu/microcode/reload.
412
415 Updating files in /lib/firmware/intel‐ucode:
416 iucode_tool -K/lib/firmware/intel‐ucode \
417 /lib/firmware/intel‐ucode \
418 /tmp/file-with-new-microcodes.bin
419 Processing several compressed files at once:
421 zcat intel-microcode*.dat.gz | iucode_tool -l -
422 zcat intel-microcode*.bin.gz | iucode_tool -l -tb -
424 Selecting microcodes and creating an early initramfs:
426 iucode_tool --scan-system \
427 --write-earlyfw=/tmp/early.cpio \
428 /lib/firmware/intel-ucode
429 iucode_tool -s 0x106a5 -s 0x106a4 -l /lib/firmware/intel-ucode
431 Using the recovery loader to load and to update microcode in an early
433 initramfs:
434 iucode_tool -L -tr /boot/intel-ucode.img
435 iucode_tool -Ll -S --write-earlyfw=/boot/intel-ucode.img.new \
437 -tr /boot/intel-ucode.img -tb /lib/firmware/intel-ucode &&
438 \
439 mv /boot/intel-ucode.img.new /boot/intel-ucode.img
440
443 Microcode with negative revision numbers is not special‐cased, and will
444 not be preferred over regular microcode.
445 The downgrade mode should be used only for microcodes with the same
448 processor flags mask. It cannot handle the corner cases where modify‐
449 ing a processor flags mask would be required to force the kernel to
450 load a lower revision of a microcode, and iucode_tool will issue an
451 warning when that happens. So far, this has not proved to be a rele‐
452 vant limitation as changes to the processor flags mask of post‐launch,
453 production microcode updates are very rare.
454 The loader version microcode metadata field is ignored by iucode_tool.
457 This shouldn't cause problems as long as the same signature never needs
458 more than a single type of loader.
459 Files are not replaced atomically: if iucode_tool is interrupted while
462 writing to a file, that file will be corrupted.
463
466 The Intel 64 and IA‐32 Architectures Software Developer's Manual, Vol‐
467 ume 3A: System Programming Guide, Part 1 (order number 253668), section
468 9.11.
469
471 Henrique de Moraes Holschuh <hmh@hmh.eng.br>
472IUCODE_TOOL 2.3.1 2018‐01‐28 IUCODE_TOOL(8)