.\"                              hey, Emacs:   -*- nroff -*-
.\" Copyright (c) 2010-2016 Henrique de Moraes Holschuh <hmh@hmh.eng.br>
.\"
.\" iucode_tool is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; see the file COPYING.  If not, write to
.\" the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
.\"
.TH IUCODE_TOOL 8 "2016-04-30" "IUCODE_TOOL @VERSION@" "iucode_tool manual"
.\" Please update the above date whenever this man page is modified.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins (default)
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.\"
.\" disable a debian-specific workaround for the misuse of - to mean \-
.char - \(hy
.\"
.SH NAME
iucode_tool \- Tool to manipulate Intel\*R IA-32/X86-64 microcode bundles
.SH SYNOPSIS
.B iucode_tool
.RI [ options ]
.RI "[[\-t" type "] " filename | dirname "] ..."
.SH DESCRIPTION
\fBiucode_tool\fP is an utility that can load Intel\*R processor microcode
data from files in both text and binary microcode bundle formats.
.PP
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.
.PP
\fBiucode_tool\fP 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 (\fIstdin\fP), by specifying a file name of \(lq\-\(rq (minus sign).
.PP
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 (\fIstdin\fP) is
assumed to be in .dat text format.  The \fI\-t\fP option can be used to change
the type of the files specified after it, including for \fIstdin\fP.
.PP
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.
.PP
Empty files and directories are ignored, and will be skipped.
.PP
You can select which microcodes should be written out, listed or uploaded
to the kernel using the
.IR "\-S" ", " "\-s" ", " "\-\-date\-before" " and " "\-\-date\-after"
options.  Should none of those options be specified, all microcodes will be
selected.
.PP
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
.IR "\-w" ", "
.IR "\-\-write\-earlyfw" ", "
.IR "\-k" ", "
.IR "\-K" ", and "
.IR "\-W" " options."
.PP
For more information about Intel processor microcodes, please read the
included documentation and the Intel manuals listed in the \fISEE ALSO\fP
section.

.SH OPTIONS
\fBiucode_tool\fP accepts the following options:

.TP
.BR  \-q ", " \-\-quiet
Inhibit usual output.
.TP
.BR  \-v ", " \-\-verbose
Print more information.  Use more than once for added verbosity.
.TP
.BR  \-h ", " \-? ", " \-\-help
List all available options and their meanings.
.TP
.B  \-\-usage
Show summary of options.
.TP
.BR  \-V ", " \-\-version
Show version of program.

.TP
.BI "\-t " type
.RI "Sets the file type of the following files. " type " can be:"
.RS
.IP \fBb\fP
binary format.  This is the same format used by the kernel driver and the
BIOS/EFI, which is described in detail by the
.IR "Intel 64 and IA-32 Architectures Software Developer's Manual, Volume 3A",
section 9.11.
.IP \fBd\fP
Intel microcode .dat text format.  This is the format normally used
by Intel to distribute microcode data files.
.IP \fBr\fP
recover microcode in binary format.  Search uncompressed generic binary
files for microcodes in Intel microcode binary format to recover.  Note:
It can find microcode that will not pass strict checks, and thus cause
\fBiucode_tool\fP to exit if the \fI\-\-no\-strict\-checks\fP or
\fI\-\-ignore\-broken\fP options are not in effect.
.IP \fBa\fP
(default) \fBiucode_tool\fP will use the suffix of the file name to
select the file type: .dat text format for files that have a
.I .dat
suffix, and binary type otherwise.  Note that for \fIstdin\fP, .dat
text format is assumed.
.RE

.TP
.B "\-\-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.

.TP
.B "\-\-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.

.TP
.B "\-\-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.

.TP
.B "\-\-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 \fI\-\-ignore\-broken\fP
option.

.TP
.B "\-\-ignore\-broken"
Skip broken microcode entries when loading a microcode data file, instead
of aborting program execution.  If the microcode entry has an unsupported
format or had its header severely corrupted, all remaining data in the file
will have to be ignored.  In that case, using a file type of \fIrecover
microcode in binary format\fP (\fI\-tr\fP option) is recommended, as it
can skip over badly mangled microcode data.

.TP
.B "\-\-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.


.TP
.BI "\-s ! | [!]" signature "[," pf_mask "]"
Select microcodes by the specified \fIsignature\fP and \fIprocessor flags
mask\fP (\fIpf_mask\fP).  If \fIpf_mask\fP is specified, it will select only
microcodes that are suitable for at least one of the processor flag
combinations present in the mask.

Specify more than once to select more microcodes.  This option can be combined
with the \fI\-\-scan\-system\fP option to select more microcodes.  If
\fIsignature\fP is prefixed with a \(lq\fI!\fP\(rq (exclamation mark), it will
deselect microcodes instead.  Ordering matters, with later \fI\-s\fP options
overriding earlier ones.

When specifying \fIsignature\fP and \fIpf_mask\fP, hexadecimal numbers must be
prefixed with \(lq\fI0x\fP\(rq, and octal numbers with \(lq\fI0\fP\(rq.
Decimal numbers must not have leading zeros, otherwise they would be
interpreted as octal numbers.

The special notation \fI\-s!\fP (with no \fIsignature\fP parameter) instructs
\fBiucode_tool\fP to require explicit inclusion of microcode signatures (using
the non\-negated form of \fI\-s\fP, or using \fI\-\-scan\-system\fP).

.RI  "The " \-\-scan\-system
option has precedence, therefore the microcodes it selects cannot be
deselected.

.TP
.BR "\-S" ", " "\-\-scan\-system"
Select microcodes by scanning online processors on this system for their
signatures.

.RI "This option can be combined with the " "\-s" " option"
to select more microcodes.

Should the signature scan fail, the program will print a warning to the user
and continue as if \fI\-\-scan\-system\fP had not been specified.  This is a
fail-safe condition when \fBiucode_tool\fP is used to install microcode updates
for the next boot.

.TP
\fB\-\-date\-before\fR=\fIYYYY\-MM\-DD\fR and \fB\-\-date\-after\fR=\fIYYYY\-MM\-DD\fR
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
\(lq\fI\-\fP\(rq (minus sign) for the separator.  Dates are not range-checked,
so you can use \fI\-\-date\-after=2000\-00\-00\fP to select all microcodes
dated since January 1st, 2000.

.TP
.B \-\-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.

.TP
.B \-\-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.

.TP
.BR "\-l" ", " "\-\-list"
List selected microcode signatures to standard output (\fIstdout\fP).
.TP
.BR "\-L" ", " "\-\-list\-all"
List all microcode signatures while they're being processed to standard output
(\fIstdout\fP).

.TP
.BR "\-k" "[\fIdevice\fP], " "\-\-kernel" "[=\fIdevice\fP]"
Upload selected microcodes to the kernel.  Optionally, the device path can be
specified (default:
.IR "@MICROCODE_DEVICE_DEFAULT@" ").  This update method is deprecated:
it will be removed eventually from the kernel and from iucode_tool.
.TP
.BR "\-K" "[\fIdirectory\fP], " "\-\-write\-firmware" "[=\fIdirectory\fP]"
Write selected microcodes with the file names expected by the Linux kernel
firmware loader.  Optionally, the destination directory can be specified
.RI "(default: " "@MICROCODE_DIR_DEFAULT@" ")."

.TP
.BR "\-w\fIfile\fP" ", " "\-\-write\-to" "=\fIfile\fP"
Write selected microcodes to a file in binary format.

.TP
.BR "\-\-write\-earlyfw" "=\fIfile\fP"
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.

.TP
.BR "\-W\fIdirectory\fP" ", " "\-\-write\-named\-to" "=\fIdirectory\fP"
Write selected microcodes to the specified directory, one microcode per
file, in binary format.  The file names reflect the microcode signature,
mask and revision.

.TP
.BR "\-\-write\-all\-named\-to" "=\fIdirectory\fP"
Write every microcode to the specified directory, one microcode per
file, in binary format.  The file names reflect the microcode signature,
mask and revision.  This is the only way to write out every revision of
the same microcode.

.TP
.B "\-\-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.

.TP
.B "\-\-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.

.SH NOTES

\fBiucode_tool\fP 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.

.PP
All informational and error messages are sent to standard error
(\fIstderr\fP), while user-requested output (such as output generated by
the list options) is sent to standard output (\fIstdout\fP).

.PP
\fBiucode_tool\fP creates files with permissions 0644 (rw\-r\-\-r\-\-),
modified by the current umask.

.PP
\fBiucode_tool\fP'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 \fIundefined\fP: 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.

.PP
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 \fI\-\-downgrade\fP option is active) will
be written to a file or uploaded to the kernel.

.PP
Intel microcode data files, both in binary and text formats, can be
concatenated to generate a bigger and still valid microcode data file.

.PP
\fBiucode_tool\fP 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 \fI\-\-overwrite\fP option is active) it will
remove the target symlink or file (and therefore breaking hardlinks)
\fIbefore\fP writing the new file.

.PP
\fBiucode_tool\fP does follow directory symlinks to locate the directory
to write files into.

.SS Linux Notes
There are two microcode update kernel drivers in Linux: the early
microcode update driver (which gets the microcode update data from a
special uncompressed initramfs image) and the late microcode update
driver, which gets microcode update data through the firmware subsystem.

The late microcode update driver should be present in the system at all
times to ensure microcode updates are reapplied on resume from suspend and
cpu hotplug, even when the early microcode update driver is used.  Do not
unload it, unless you really know better.

Updating microcode through the early driver is safer, but can only be done
at boot.  Using the early driver to update microcode is strongly
recommended.  The late microcode update driver can apply new microcode
updates at any time, but it cannot safely apply any new microcode updates
that would change visible processor features.

The early microcode kernel driver is available since Linux v3.9, and it can
safely apply microcode updates that change visible processor features (such
as the microcode updates that disabled Intel TSX instructions on Intel
Haswell cores).  It needs an uncompressed initramfs image with the
microcode update data in \fI/kernel/x86/microcode/GenuineIntel.bin\fP.
This uncompressed initramfs image must come before any compressed initramfs
image(s), and it has an special name: \fIearly initramfs\fP.

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 \fBiucode_tool\fP \fI\-\-write\-earlyfw\fP option.

The \fI/dev/cpu/microcode\fP update interface of the late microcode update
driver has been deprecated and made optional, and should not be used.  It
has one special requirement: each write syscall must contain whole
microcode(s).  It can be accessed through \fBiucode_tool\fP
\fI\-\-kernel\fP.

Up to Linux v3.5, the late microcode update driver required microcode
updates to be triggered per-core, by writing the number 1 to
\fI/sys/devices/system/cpu/*/microcode/reload\fP 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 \fI/sys/devices/system/cpu/microcode/reload\fP.

.SH EXAMPLES
.SS Updating files in \fI@MICROCODE_DIR_DEFAULT@\fP:
.HP
iucode_tool \-K@MICROCODE_DIR_DEFAULT@ \\
.br
	@MICROCODE_DIR_DEFAULT@ \\
.br
	/tmp/file\-with\-new\-microcodes.bin
.SS Processing several compressed files at once:
.HP
zcat intel\-microcode*.dat.gz | iucode_tool\ \-l\ \-
.HP
zcat intel\-microcode*.bin.gz | iucode_tool \-l\ \-tb\ \-
.SS Selecting microcodes and creating an early initramfs:
.HP
iucode_tool \-\-scan\-system \\
.br
	\-\-write\-earlyfw=/tmp/early.cpio \\
.br
	/lib/firmware/intel\-ucode
.HP
iucode_tool \-s\ 0x106a5 \-s\ 0x106a4 \-l /lib/firmware/intel\-ucode
.SS Using the recovery loader to load and to update microcode in an early initramfs:
.HP
iucode_tool \-L \-tr /boot/intel\-ucode.img
.HP
iucode_tool \-Ll \-S \-\-write\-earlyfw=/boot/intel\-ucode.img.new \\
.br
	\-tr /boot/intel\-ucode.img \-tb /lib/firmware/intel\-ucode && \\
.br
mv /boot/intel\-ucode.img.new /boot/intel\-ucode.img

.SH BUGS
Microcode with negative revision numbers is not special-cased, and will not be
preferred over regular microcode.

.PP
The \fIdowngrade mode\fP should be used only for microcodes with the same
\fIpf_mask\fP.  It cannot handle the corner cases where modifying a
\fIpf_mask\fP would be required to force the kernel to load a lower revision of
a microcode.  So far, this has not proved to be a relevant limitation as
changes to the \fIpf_mask\fP of post-launch, production microcode updates are
very rare.

.PP
The \fIloader version\fP microcode metadata field is ignored by
\fBiucode_tool\fP.  This shouldn't cause problems as long as the same signature
never needs more than a single type of loader.

.PP
Files are not replaced atomically: if \fBiucode_tool\fP is interrupted while
writing to a file, that file will be corrupted.

.SH "SEE ALSO"
\fBThe Intel 64 and IA-32 Architectures Software Developer's Manual, Volume 3A:
System Programming Guide, Part 1\fP (order number 253668), section 9.11.
.\" .BR foo (1), 
.\" .BR bar (1).
.SH AUTHOR
Henrique de Moraes Holschuh <hmh@hmh.eng.br>