amd64-microcode for Debian
--------------------------

Introduction:

AMD AMD64 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 after the processor is powered off.  They must be reapplied at
every boot and after the system wakes up from suspend to RAM or 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 AMD 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.

Debian can apply microcode updates to the system processors during the
operating system boot automatically.  This requires the use of a suitably
configured Linux kernel 3.14 or later, and an initramfs.


Installing microcode updates:

For the Debian default kernel, it is enough to install the amd64-microcode
package as well as the initramfs-tools package and the microcode update
will be applied automatically at the next reboot.

It is also possible to use "dracut" instead of initramfs-tools, but the
support for early microcode updates must be enabled manually in
dracut.conf (set the option "early_microcode=yes").  Force an update of
the initramfs using dracut, and reboot.  Note that since Linux kernel 4.4,
one must use dracut 044 or later.

Applying the microcode updates without the use of an early initramfs is
not supported in Debian.


RECOVERY PROCEDURE:

It is possible for a microcode update to not work well, or to not work at
all on specific system models.  This is very rare when using the safe
microcode update procedure described above and an up-to-date Linux kernel,
but it has happened at least once.

Should you experience problems because of the microcode update, you will
have to bypass the microcode update process that happens during operating
system startup (boot), and remove the amd64-microcode package until the
underlying issue is fixed.

To bypass the microcode update during system startup, you must instruct the
boot loader (grub, lilo, etc) to pass the "dis_ucode_ldr" parameter
(without the quotes) to the kernel.

If your system uses grub (the default bootloader in Debian):

  1. Access the grub menu during boot (press and hold the left "Shift"
     key right after starting the system up if you don't see a grub menu
     during boot);

  2. Move the highlight/cursor to the kernel/boot option you want to
     use, and press the "e" key to edit it;

  3. Locate the line that starts with "linux" using the cursor
     keys.  You must add the word "dis_ucode_ldr" (without the quotes) to
     the end of that line;

  4. Press "Ctrl+X" to start (boot) the system.  The microcode updates
     will be skipped.

After the system is running, remove or purge the amd64-microcode package.

If removing/purging the package doesn't do it automatically for some
reason, refresh the initramfs using the "update-initramfs -u" command (as
the root user), and possibly "update-initramfs -u -k <kernel version>".

"dracut" users, please refer to the dracut documentation on how to update
the initramfs images for every installed kernel.

Please report any issues caused by microcode updates to the mailing-list or
to the Debian bug tracker.

 -- Henrique de Moraes Holschuh <hmh@debian.org>, 2024-08-11
