IUCODE_TOOL(8) | iucode_tool manual | IUCODE_TOOL(8) |
iucode_tool - Tool to manipulate Intel® IA‐32/X86‐64 microcode bundles
iucode_tool [options] [[-ttype] filename|dirname] ...
iucode_tool is an utility that can load Intel® processor microcode data from files in both text and binary microcode bundle formats.
It can output a list of the microcodes in these files, merge them, upload them to the kernel (to upgrade the microcode in the system processor cores) or write some of them out to a file in binary format for later use.
iucode_tool will load all microcodes in the specified files and directories to memory, in order to process them. Duplicated and outdated microcodes will be discarded. It can read microcode data from standard input (stdin), by specifying a file name of “-” (minus sign).
Microcode data files are assumed to be in .dat text format if they have a .dat suffix, and to be in binary format otherwise. Standard input (stdin) is assumed to be in .dat text format. The -t option can be used to change the type of the files specified after it, including for stdin.
If a directory is specified, all files whose names do not begin with a dot will be loaded, in unspecified order. Nested directories are skipped.
Empty files and directories are ignored, and will be skipped.
You can select which microcodes should be written out, listed or uploaded to the kernel using the -S, -s, --date-before and --date-after options. Should none of those options be specified, all microcodes will be selected.
You can upload the selected microcodes to the kernel, write them out to a file (in binary format), to a Linux early initramfs archive, to per-processor-signature files in a directory, or to per-microcode files in a directory using the -w, --write-earlyfw, -k, -K, and -W options.
iucode_tool will identify microcodes in its output and error messages using a “n/k” notation, where “n” is the bundle number, and “k” is the microcode number within that bundle. The output of the --list-all option when processing multiple input files is the best example of how it works.
For more information about Intel processor microcodes, please read the included documentation and the Intel manuals listed in the SEE ALSO section.
iucode_tool accepts the following options:
If the processor flags mask is specified, it will select only microcodes that are suitable for at least one of the processor flag combinations present in the mask.
If the revision is specified, optionally prefixed by one of the “eq:”, “lt:” or “gt:” operators, it will select only microcodes that have that same revision (if no operator, or if the “eq:” operator is used), or microcodes that have a revision that is less than (“lt:” operator), or greater than (“gt:” operator), the one specified.
Specify more than once to select more microcodes. This option can be combined with the --scan-system option to select more microcodes. If signature is prefixed with a “!” (exclamation mark), it will deselect microcodes instead. Ordering matters, with later -s options overriding earlier ones, including --scan-system.
When specifying signature and pf_mask, hexadecimal numbers must be prefixed with “0x”, and octal numbers with “0”. Decimal numbers must not have leading zeros, otherwise they would be interpreted as octal numbers.
The special notation -s! (with no signature parameter) instructs iucode_tool to require explicit inclusion of microcode signatures (using the non-negated form of -s, or using --scan-system).
This option can be used only once, and it can be combined with the -s option to select more microcodes. The microcodes selected by --scan-system can also be deselected by a later -s !signature option.
The optional mode argument (accepted only by the long version of the option) selects the strategy used to scan processors:
This will typically reduce the early initramfs size by 736 bytes.
iucode_tool reads all data to memory before doing any processing. It enforces a sanity limit of a maximum of 1GiB worth of binary microcode data per microcode data file.
All informational and error messages are sent to standard error (stderr), while user-requested output (such as output generated by the list options) is sent to standard output (stdout).
iucode_tool creates files with permissions 0644 (rw-r--r--), modified by the current umask.
iucode_tool's selected microcode listing and microcode output files are sorted first by processor signature (in ascending order), and then by processor flags mask (in descending order).
When multiple revisions of a microcode are selected, the older ones will be skipped. Only the newest selected revision of a microcode (or the last one in load order when the --downgrade option is active) will be written to a file or uploaded to the kernel.
Intel microcode data files, both in binary and text formats, can be concatenated to generate a bigger and still valid microcode data file.
iucode_tool does not follow symlinks when writing microcode data files. It will either refuse to write the file and abort (default mode of operation), or (when the --overwrite option is active) it will remove the target symlink or file (and therefore breaking hardlinks) before writing the new file.
iucode_tool does follow directory symlinks to locate the directory to write files into.
Before Linux v4.4, the microcode update driver was split in two parts: the early microcode update driver (which gets microcode data from the initramfs) and the late microcode update driver, which could be a module and got microcode data from the firmware subsystem. The two drivers were unified in Linux v4.4.
The microcode update driver needs to be present in the system at all times to ensure microcode updates are reapplied on resume from suspend and CPU hotplug. Do not unload the microcode module, unless you really know better. Since Linux v4.4, the late microcode driver cannot be a module anymore and will always be present in the system when enabled.
Updating microcode early is safer. It can only be done at boot and it requires an initramfs, but it is strongly recommended: late microcode updates (which read microcode data from /lib/firmware) cannot safely change visible processor features.
Early microcode updates are available since Linux v3.9. They can safely change visible processor features (such as the microcode updates that disabled Intel TSX instructions on Intel Haswell cores do). They require an uncompressed initramfs image with the microcode update data in /kernel/x86/microcode/GenuineIntel.bin. This uncompressed initramfs image must come before any compressed initramfs image(s), and it has an special name: early initramfs.
The microcode update data inside the early initramfs image must be aligned to a 16‐byte boundary due to a bug in several versions of the Linux kernel early microcode update driver. This requires special steps when creating the initramfs archive with the microcode data, and will be handled automatically by the iucode_tool --write-earlyfw option.
Since Linux v4.2, it is also possible to build a kernel with the microcode update data as built-in firmware, using the CONFIG_FIRMWARE_IN_KERNEL facility. This feature is not yet mature as of Linux v4.2.8, v4.4.11, v4.5.5 and v4.6, and might not work in every case.
The /dev/cpu/microcode update interface has been deprecated and should not be used. It has one special requirement: each write syscall must contain whole microcode(s). It can be accessed through iucode_tool --kernel.
Up to Linux v3.5, late microcode updates were required to be triggered per-core, by writing the number 1 to /sys/devices/system/cpu/*/microcode/reload for every cpu. Depending on kernel version, you must either trigger it on every core to avoid a dangerous situation where some cores are using outdated microcode, or the kernel will accept the request only for the boot processor and use it to trigger an update on all system processor cores.
Since Linux v3.6, the late microcode update driver has a new interface that explicitly triggers an update for every core at once when the number 1 is written to /sys/devices/system/cpu/microcode/reload.
iucode_tool -K/lib/firmware/intel-ucode \
/lib/firmware/intel-ucode \
/tmp/file-with-new-microcodes.bin
zcat intel-microcode*.dat.gz | iucode_tool -l -
zcat intel-microcode*.bin.gz | iucode_tool -l -tb -
iucode_tool --scan-system \
--write-earlyfw=/tmp/early.cpio \
/lib/firmware/intel-ucode
iucode_tool -s 0x106a5 -s 0x106a4 -l /lib/firmware/intel-ucode
iucode_tool -L -tr /boot/intel-ucode.img
iucode_tool -Ll -S --write-earlyfw=/boot/intel-ucode.img.new \
-tr /boot/intel-ucode.img -tb /lib/firmware/intel-ucode && \
mv /boot/intel-ucode.img.new /boot/intel-ucode.img
Microcode with negative revision numbers is not special-cased, and will not be preferred over regular microcode.
The downgrade mode should be used only for microcodes with the same processor flags mask. It cannot handle the corner cases where modifying a processor flags mask would be required to force the kernel to load a lower revision of a microcode, and iucode_tool will issue an warning when that happens. So far, this has not proved to be a relevant limitation as changes to the processor flags mask of post-launch, production microcode updates are very rare.
The loader version microcode metadata field is ignored by iucode_tool. This shouldn't cause problems as long as the same signature never needs more than a single type of loader.
Files are not replaced atomically: if iucode_tool is interrupted while writing to a file, that file will be corrupted.
The Intel 64 and IA‐32 Architectures Software Developer's Manual, Volume 3A: System Programming Guide, Part 1 (order number 253668), section 9.11.
Henrique de Moraes Holschuh <hmh@hmh.eng.br>
2018-01-28 | IUCODE_TOOL 2.3.1 |