NAME¶
iucode_tool - Tool to manipulate Intel® IA-32/X86-64 microcode bundles
SYNOPSIS¶
iucode_tool [
options] [[-t
type]
filename|
dirname] ...
DESCRIPTION¶
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.
For more information about Intel processor microcodes, please read the included
documentation and the Intel manuals listed in the
SEE ALSO section.
OPTIONS¶
iucode_tool accepts the following options:
- -q, --quiet
- Inhibit usual output.
- -v, --verbose
- Print more information. Use more than once for added verbosity.
- -h, -?, --help
- List all available options and their meanings.
- --usage
- Show summary of options.
- -V, --version
- Show version of program.
- -t type
- Sets the file type of the following files. type can be:
- b
- binary format. This is the same format used by the kernel driver and the
BIOS/EFI, which is described in detail by the Intel 64 and IA-32
Architectures Software Developer's Manual, Volume 3A, section
9.11.
- d
- Intel microcode .dat text format. This is the format normally used by
Intel to distribute microcode data files.
- a
- (default) iucode_tool will use the suffix of the file name to
select the file type: .dat text format for files that have a .dat
suffix, and binary type otherwise. Note that for stdin, .dat text format
is assumed.
- --downgrade
- When multiple versions of the microcode for a specific processor are
available from different files, keep the one from the file loaded last,
regardless of revision levels. Files are always loaded in the order they
were specified in the command line. This option has no effect when just
one file has been loaded.
- --no-downgrade
- When multiple versions of the microcode for a specific processor are
available from different files, keep the one with the highest revision
level. This is the default mode of operation.
- --strict-checks
- Perform strict checks on the microcode data. It will refuse to load
microcodes and microcode data files with unexpected size and metadata. It
will also refuse to load microcode entries that have the same metadata,
but different payload. This is the default mode of operation.
- --no-strict-checks
- Perform less strict checks on the microcode data. Use only if you happen
to come across a microcode data file that has microcodes with weird sizes
or incorrect non-critical metadata (such as invalid dates), which you want
to retain. If you just want to skip those, use the --ignore-broken
option.
- --ignore-broken
- Skip broken microcode entries when loading a microcode data file, instead
of aborting program execution. If the microcode entry has an unknown
format or had its header severely corrupted, all remaining data in the
file will be ignored. This option is also useful to process data files
with extra padding at the end (the padding will be reported as an invalid
microcode entry), as well as to salvage microcodes from an incomplete data
file.
- --no-ignore-broken
- Abort program execution if a broken microcode is found while loading a
microcode data file. This is the default mode of operation.
- -s ! | [!]signature[,pf_mask]
- Select microcodes by the specified signature and processor flags mask
(pf_mask). If pf_mask is specified, it will select only
microcodes that are suitable for at least one of the processor flag
combinations in the mask.
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 unselect microcodes instead. Ordering matters,
with later -s options overriding earlier ones.
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).
The --scan-system option has precedence, therefore the microcodes it
selects cannot be unselected.
- -S, --scan-system
- Select microcodes by scanning all online processors on this system for
their signatures.
This option can be combined with the -s option to select more
microcodes.
Should the signature scan fail on all online processors, the program will
print a warning to the user and continue as if --scan-system had
not been specified. This is a fail-safe condition when iucode_tool
is used to install microcode updates for the next boot.
- --date-before=YYYY-MM-DD and
--date-after=YYYY-MM-DD
- Limit the selected microcodes by a date range. The date must be given in
ISO format, with four digits for the year and two digits for the month and
day and “ -” (minus sign) for the separator. Dates
are not range-checked, so you can use --date-after=2000-00-00 to
select all microcodes dated since January 1st, 2000.
- --loose-date-filtering
- When a date range is specified, all revisions of the microcode will be
considered for selection (ignoring just the date range, all other filters
still apply) should any of the microcode's revisions be within the date
range.
- --strict-date-filtering
- When a date range is specified, select only microcodes which are within
the date range. This is the default mode of operation.
- -l, --list
- List selected microcode signatures.
- -L, --list-all
- List all microcode signatures while they're being processed.
- -k[device], --kernel[=device]
- Upload selected microcodes to the kernel. Optionally, the device path can
be specified (default: /dev/cpu/microcode). This update method is
being deprecated.
- -K[directory],
--write-firmware[=directory]
- Write selected microcodes with the file names expected by the Linux kernel
firmware loader. Optionally, the destination directory can be specified
(default: /lib/firmware/intel-ucode).
- -wfile, --write-to=file
- Write selected microcodes to a file in binary format.
- --write-earlyfw=file
- Write selected microcodes to an early initramfs archive, which should be
prepended to the regular initramfs to allow the kernel to update processor
microcode very early during system boot.
- -Wdirectory, --write-named-to=file
- Write selected microcodes to the specified directory, one microcode per
file, in binary format. The file names reflect the microcode signature,
mask and revision.
- --overwrite
- Remove the destination file before writing, if it exists and is not a
directory. The destination file is not overwritten in-place. Hardlinks
will be severed, and any existing access permissions, ACLs and other
extended attributes of the old destination file will be lost.
- --no-overwrite
- Abort if the destination file already exists. This is the default mode of
operation. Do note that iucode_tool does not follow non-directory symlinks
when writing files.
NOTES¶
iucode_tool reads all data to memory before doing any processing.
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 by cpu signature, however the ordering inside a group of microcodes
that share the same cpu signature is
undefined: it is deterministic,
but it is sensitive to command line parameters and their ordering, and also
depends on the ordering of the individual microcodes inside each loaded data
file.
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.
Linux Notes¶
The cpuid kernel driver is required for the
--scan-system functionality
to work.
Early initramfs support for microcode updates is available since Linux v3.9.
Kernels without early initramfs support will just make the microcode file
available to the initramfs environment at
/kernel/x86/microcode/GenuineIntel.bin.
The early initramfs image with microcode update data must be aligned to a
16-byte boundary relative to the start of the initramfs file to work around a
bug in some versions of the Linux kernel.
Each Intel processor microcode must be uploaded through a single write syscall
to
/dev/cpu/microcode, but more than one microcode can be uploaded per
write syscall. Writing the microcode to the kernel device will update all
system processor cores at once. This method is being deprecated and does not
work on other system processor types.
The old Linux firmware interface for microcode updates needs to be triggered on
a per-core basis, by writing the number 1 to
/sys/devices/system/cpu/*/microcode/reload. 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 per-core interface has been replaced with 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.
The microcode driver should not be unloaded unless you are sure it is not going
to be needed. Depending on kernel version and configuration, the driver needs
to be loaded for the kernel to be able to reapply the microcode updates after
the system resumes from suspend or hibernation, and also to update any system
processor cores that were offline at the time the update was applied.
EXAMPLES¶
Updating files in /lib/firmware/intel-ucode:¶
- iucode_tool -K/lib/firmware/intel-ucode /lib/firmware/intel-ucode/*
/tmp/file-with-new-microcodes.bin
Processing several compressed files at once:¶
- zcat intel-microcode*.dat.gz | iucode_tool -k -
- zcat intel-microcode*.bin.gz | iucode_tool -k -tb -
BUGS¶
Microcode with negative revision numbers is not special-cased, and will not be
preferred over regular microcode.
Files are not replaced atomically: if
iucode_tool is interrupted while
writing to a file, that file will be corrupted.
SEE ALSO¶
The Intel 64 and IA-32 Architectures Software Developer's Manual, Volume
3A: System Programming Guide, Part 1 (order number 253668), section
9.11.
AUTHOR¶
Henrique de Moraes Holschuh <hmh@hmh.eng.br>