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

			       Version 1.0.2
			      May 10th,  2013

		     https://gitorious.org/iucode-tool

Intel® 64 and IA-32 processors (x86_64 and i686 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 happen extremely
rarely, there are enough updates fixing issues that would cause system
lockup, memory corruption, or unpredictable system behavior, to warrant
taking it seriously.

Microcode updates are ephemeral: they will be lost after a 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 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 processor microcode:

The Intel-distributed microcode bundle contains data (microcode) to update
several processor models.  It uses a text format which is unsuitable to be
used directly by the Linux kernel, and which is also highly inefficient
space-wise.  An userspace utility must be used to convert the bundle to a
binary format that can be directly used by the Linux kernel.

Updating the processor microcode is supposed to be a safe process, which
can be done at any time (even with the system at full load), and as many
times as required.  The kernel driver will refuse to downgrade the
processor microcode to an older version.

Although it can be updated at any time, processor microcode should really
be updated as soon as possible during system start up, in order to
minimize the time window during which the issues fixed by the updates
could happen.  Also, some processor errata must be fixed by a microcode
update before the kernel can finish system processor initialization,
otherwise it has no choice but to disable features.

Therefore, one should always get microcode updates through firmware
(BIOS/EFI) updates when possible.

The second best way to update the microcode is to have the kernel do it as
part of its initial system processor and platform setup, using a facility
known as "early initramfs".  This facility is available since Linux v3.9,
and it contains files with special firmware updates (Intel processor
microcode and ACPI tables as of Linux v3.9).  It it must be prepended to
the regular initramfs.

An enhanced grub2-based boot loader is available from Intel, which is
capable of updating Intel processor microcode and could be used as a
stop-gap measure to get up-to-date microcode loaded before the kernel
starts.  It can be found at: http://www.biosbits.org.

The other possibilities are initramfs-assisted microcode updates or updates
triggered by an initscript, which are rather easy to deploy but might run
too late.

To apply a microcode update for an Intel system processor after the Linux
kernel boots:

 1. Upload it in binary format to /dev/cpu/microcode using microcode.ctl,
    iucode_tool -k, or some other suitable tool.  A single microcode must
    not be split over several write syscalls, but you can upload more than
    one microcode per write syscall.

    or

 2. Place the binary microcode in /lib/firmware/ with the correct file name
    (iucode_tool -K can do this automatically for Intel microcode), and
    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

    Older versions:
    for i in /sys/devices/system/cpu/cpu[0-9]*/microcode/reload ; do
        echo 1 2>/dev/null > "$i" || true
    done

    This requires udev (or something else that handles uevents) to be
    already operational to handle the firmware request by the kernel.

Method 1 is deprecated, as method 2 is generic and would work for any
system processor type, not just Intel.


Downloading the microcode update data file from Intel:

A new version of the microcode bundle can be downloaded directly from
Intel, by navigating to the support section looking for downloads for your
processor.  One can also try one of these RSS feeds:

http://feeds.downloadcenter.intel.com/rss/?p=483&lang=eng
http://feeds.downloadcenter.intel.com/rss/?p=2371&lang=eng

To manually install the downloaded microcode bundle, 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:

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

(or, if using /lib/firmware):

	chown -R root:root /lib/firmware/intel-ucode
	chmod -R 0644 /lib/firmware/intel-ucode

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 .dat file:

Unfortunately, as of August 2012, 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.  A few specific processor
specification updates now carry public information about the errata fixed by
the latest microcode revision, which is a step in the right direction.

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 processor microcode is identified by the processor signature (a
32-bit number) and by three bits called "processor flags".  The Microcode
is often 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".


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
  01/001: sig 0x00000683, pf mask 0x01, 2001-02-06, rev 0x0013, size 2048
  01/002: sig 0x00000f4a, pf mask 0x5c, 2005-12-14, rev 0x0004, size 2048
  01/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).  The second
microcode update applies to several processors that share the same family,
model and stepping, but have different processor flags.  These are
explained below.

Microcode revisions are signed 32-bit integers.  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).  Negative revisions
are used by Intel during microcode development, and will not be found on
public microcode updates.

The release dates are useful to track how old a microcode release 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".

There are 8 possible processor flags combinations, numbered from 0 to 7
(there are three processor flag bits, thus the combinations in binary range
from 000 to 111).

This number can used to address a specific bit in a byte (bit 0 being the
least significant bit, and bit 7 being the most significant bit).  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).

Thus, a microcode update identified by a pf mask of 0x42 would apply to two
types of processors: those with processor flags combination 010 (binary),
and also those with processor flags combination 100 (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


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.