iucode_tool - Intel® 64 and IA-32 processor microcode tool

			     Version 2.3.1
			  Frebruary 5th, 2018

		     https://gitlab.com/iucode-tool

Intel® 64 and IA-32 system processors (x86_64 and i686 system processors)
are capable of field-upgrading their control program (microcode).  These
microcode updates correct processor errata, and are often important for
safe, correct system operation.

While most of the microcode updates fix problems that either happen rarely
or are related to less commonly used features, there are enough updates
fixing issues that would cause system lockup, memory corruption, and
unpredictable system behavior, to warrant taking it seriously.

Microcode updates are ephemeral: they will be lost after a system processor
hard reset or when the processor is powered off.  They must be reapplied at
every boot and after the system wakes up from suspend to RAM or to disk.

Updating the system processor microcode is the responsibility of the system
firmware (BIOS or EFI).  However, not all vendors will release timely
updates for their firmware when Intel releases updated microcode, and most
users don't update their system firmware in a timely fashion (or at all)
anyway.

The end result is that, unless some other method of distributing microcode
updates is in place, the processor in many systems will be running with
outdated microcode, increasing the chances of incorrect system operation.

Intel has made available to the general public a microcode update data file
(microcode bundle), which the operating system can use to install microcode
updates independently from any system firmware updates.  Currently, the
same data file (microcode bundle) is used to distribute microcode updates
for all Intel i686 and X86_64 processor models.


Updating the system processor microcode:

The Intel-distributed microcode bundle contains microcode update data for
several processor models.  Older microcode releases used a text format
which is unsuitable to be used directly by the Linux kernel: it must be
converted by an utility like iucode_tool before Linux can use it.  Newer
releases have the same microcode update content both in the legacy text
format, and in binary format.

Updating the processor microcode is a process that can be done at any time
(even with the system at full load), and as many times as required.  It is
strongly recommended that microcode updates be applied during early system
boot, though:

  * Microcode updates should be applied as soon as possible to
    shorten the time window where the errata fixed by the update
    could still trigger;

  * Some microcode updates can only be applied safely before the
    operating system enables more advanced processor functionality,
    otherwise that functionality must be disabled by the kernel
    (Atom PSE erratum);

  * Some microcode updates disable (faulty) functionality or make
    other "visible" changes to the processor, and must be applied
    before either the kernel or applications start using that
    functionality (e.g. Haswell Intel TSX erratum).

Therefore, one should always apply microcode updates through firmware
(BIOS/EFI) updates when possible.  Failing that, one should use the "early
initramfs" and "early microcode update driver" support in Linux v3.9 and
later.  As a last option, one can use the "late microcode update" driver,
but this one might run too late to be of any help (and it cannot safely
apply microcode updates such as the Intel Haswell TSX fix).


To apply a microcode update using the early microcode kernel driver:

 1. Arrange for iucode_tool --write-earlyfw to generate the early
    initramfs image from microcode data files.  You probably want
    to also use --scan-system to reduce the size of the generated
    early initramfs image;

 2. Either prepend the earlyfw image generated by iucode_tool to
    the initramfs, or, if your bootloader can handle it, arrange
    for it to load the early initramfs and the standard initramfs
    images in sequence;

 3. Boot the system using a suitable Linux v3.9 or later kernel,
    compiled with kconfig options CONFIG_MICROCODE_EARLY=y and
    CONFIG_MICROCODE_INTEL_EARLY=y.

 4. Ensure the late microcode update driver (microcode module) is
    either loaded or compiled in (CONFIG_MICROCODE=y), as it will
    be needed if the microcode needs to be reapplied to a processor,
    e.g. due to a suspend/resume or hibernate/resume cycle, or due
    to CPU hotplug.

This is usually handled by the Linux distro when you install microcode
update support packages.  Check your distro's documentation for details.


To apply a microcode update for an Intel system processor after the Linux
kernel boots, using the late microcode update driver (warning: this can
render the system unusable if it applies a microcode update that disables
processor features):

 ***** WARNING *****  the method below is unsafe  ***** WARNING *****

 1. Place the binary microcode in /lib/firmware/ with the correct
    file name (iucode_tool -K can do this automatically for Intel
    microcode);

 2. Trigger a microcode refresh action, either by the initial load
    of the kernel "microcode" module, or if it is already loaded,
    by running the shell commands:

    (Linux v3.6 and later)
    echo 1 > /sys/devices/system/cpu/microcode/reload

    (Linux v3.5 and earlier)
    for i in /sys/devices/system/cpu/cpu[0-9]*/microcode/reload ; do
        echo 1 2>/dev/null > "$i" || true
    done

 ***** WARNING *****  the method above is unsafe  ***** WARNING *****


Downloading the microcode update data file from Intel:

A new version of the microcode update data bundle can be downloaded
directly from Intel, by navigating to the support section looking for
downloads for your processor.  One could also search the Intel Download
Center for "microcode linux":

https://downloadcenter.intel.com/SearchResult.aspx?keyword=microcode+linux

To manually install the downloaded microcode data, unpack the archive you
got from Intel and copy the microcode-*.dat file from the archive to where
your distro expects it, e.g. /usr/share/misc/intel-microcode.dat

If your distro uses /lib/firmware to update microcode, you should instead
use "iucode_tool -K" to convert the downloaded microcode bundle to binary
firmware files.

You should make sure the microcode data is owned by root, and that it can
only be written to by root (e.g. mode 0644) for security reasons:

(example, adjust as needed for your Linux distro):

	chown root:root /usr/share/misc/intel-microcode.dat
	chmod 0644 /usr/share/misc/intel-microcode.dat

(example, if using /lib/firmware):

	chown -R root:root /lib/firmware/intel-ucode
	find /lib/firmware/intel-ucode -type d -exec chmod 0755 {} \;
	find /lib/firmware/intel-ucode -type f -exec chmod 0644 {} \;

You might have to regenerate the initramfs image to get the updated
microcode files into the initramfs.  The proper way to do this is
distro-specific.

If your distro has no use for the .dat file after you installed updated
binary files to /lib/firmware, you can remove it to save some space.


About the Intel-supplied microcode updates file:

Unfortunately, as of November 2014, Intel still does not usually publish
any information about changes to the intel-microcode.dat distribution to
the general public.  Such information may be available through restricted
developer and partner channels, though.  Very rarely, a specification
update might carry some information about the errata fixed by the latest
microcode revision.

Intel removes microcode from their public distribution regularly.  One can
theorize that removals of microcode updates for very old processors that
were distributed over a reasonable number of microcode data file releases
were done to reduce bundle file growth.  Unfortunately, such removals could
cause unnecessary regressions on very old, but still operational hardware,
so distros used on older hardware might want to still ship them.

On recent processors, Intel microcode release management can be puzzling:
Intel has often removed from the distribution microcode for recent
processors, as well as microcode that it had recently issued updates for.
Microcode version downgrades have also been observed.

We can only hope that Intel will start publishing microcode update
changelog information to the general public in the future.  This would
certainly make it easier for distros to schedule microcode updates for
their stable branches.



		   Technical details (optional reading)


Intel Microcode signatures:

Intel system processor microcode is identified by the processor signature
(a 32-bit number) and by three bits called "processor flags".  The
Microcode is often, but not always, the same among several processors that
differ only on their processor flags, and have the same processor
signature.

These signatures are useful when one wants to look for entries referring to
a specific processor in documentation, or request that iucode_tool create
microcode binary bundles for a specific set of processors.  Otherwise, you
can just ignore them as they are handled automatically by iucode_tool and
by the kernel microcode driver.

If you want to know the signature of the processors in your system, run
"iucode_tool --scan-system".  It is possible for a multiprocessor system
to contain processors with different signatures (known as mixed stepping
configurations), although this is usually not an ideal configuration.

The processor signature is returned in the EAX register from leaf 1 of the
CPUID instruction.  It contains an encoded format of the CPU stepping,
model, family and type, and a few undefined (reserved) bits that are zero
on all current Intel processors.


Listing what is inside a microcode bundle:

The microcode signatures for each microcode available in a microcode bundle
can be listed by iucode_tool:

iucode_tool -L /usr/share/misc/intel-microcode.dat

microcode bundle 1: /usr/share/misc/intel-microcode.dat
  001/001: sig 0x00000683, pf_mask 0x01, 2001-02-06, rev 0x0013, size 2048
  001/002: sig 0x00000f4a, pf_mask 0x5c, 2005-12-14, rev 0x0004, size 2048
  001/003: sig 0x00000653, pf_mask 0x04, 1999-05-20, rev 0x000b, size 2048
  ...

The first and third microcode updates are for very specific processor
models (a single combination of processor flags, each, as they only have
one bit set in the pf_mask field).  The second microcode update applies to
several processors that share the same family, model and stepping, but have
different processor flags (more than one bit set in the pf_mask field). The
processor flags and pf_mask field are explained below.

iucode_tool -L s000406A8_m00000001_r0000081F.fw

microcode bundle 1: s000406A8_m00000001_r0000081F.fw
  001/001: sig 0x000406a8, pf_mask 0x01, 2014-08-12, rev 0x081f, size 38912
           sig 0x000406a8, pf_mask 0x01, 2014-08-12, rev 0x081f
           sig 0x000406a9, pf_mask 0x01, 2014-08-12, rev 0x081f

This is a microcode update with multiple signatures.  At least one of the
signatures will typically be a duplicate.  iucode_tool will act on each
signature (list, select, etc) as if they were independent, but when writing
out the microcode, all of its signatures will be included.  It will not
output more than a single copy of the microcode to the same output file.


Microcode revisions:

Microcode revisions are signed 32-bit integers.  Negative revisions are
used by Intel during microcode and chip development, and will not be found
on public microcode updates: you'd usually find such microcode only in
UEFI/BIOS images, to support Engineering Sample processors.

Revision 0 is used by the system processor to signal that it is running the
factory-provided microcode (i.e. no microcode updates were installed).  No
Intel processor to date (since the Pentium Pro) is supposed to run with
factory (revision 0) microcode: a lot of functionality will be either
extremely buggy or missing entirely.

iucode_tool will list negative revisions as a large unsigned number.
However, it will prefer positive revisions over negative revisions when
selecting microcode.

microcode bundle 1: coreboot/s00040650_m00000072_rFFFF000A.fw
  01/001: sig 0x00040650, pf_mask 0x72, 2012-11-09, rev 0xffff000a, size 22528

The release dates are useful to track how old a microcode update is, but
are otherwise ignored by the kernel driver: Intel documentation clearly
states that only the revision number should be used to decide which
microcode update is more recent.


Microcode processor flags mask (pf_mask):

Some Intel processor variants may share the same processor signature, and
yet require different microcode.  These processors can be told apart by
checking their "processor flags" (bits 52, 51 and 50 of MSR 17h,
IA32_PLATFORM_ID).

              processor flags     processor flags mask
                 000b (0)            00000001b (01h)
                 001b (1)            00000010b (02h)
                 010b (2)            00000100b (04h)
                 011b (3)            00001000b (08h)
                 100b (4)            00010000b (10h)
                 101b (5)            00100000b (20h)
                 110b (6)            01000000b (40h)
                 111b (7)            10000000b (80h)

The microcode data file has a field called "processor flags mask", or
"pf_mask" for short, where a bit is set if the microcode can be applied to
a processor with that set of processor flags.  E.g. if bit 6 is set, that
microcode can be applied to a processor with the appropriate signature and
the processor flags combination 110 (in binary).

A microcode update identified by a processor flags mask of 42 (hexadecimal)
would apply to two types of processors: those with processor flags
combination 001 (binary), and also those with processor flags combination
110 (binary).

The definition of what a processor flag combination means varies with the
processor model.

Some very old processors lack processor flags support.  In that case,
microcode updates will have an empty processor flag mask (all bits clear).

When the "microcode" kernel driver is loaded, the processor flags
combination for each online processor in a system will be available through
sysfs.  These sysfs nodes follow the pattern:
/sys/devices/system/cpu/cpu*/microcode/processor_flags

NOTE: iucode_tool prefixes hexadecimal values with "0x".


Further reading:

The Intel 64 and IA-32 Architectures Software Developer's Manual, Volume
3A: System Programming Guide, Part 1 (order number 253668), section 9.11.

* Note: Intel is a registered trademark of Intel Corporation.