[PATCH] x86/microcode: Document the three loading methods

[PATCH] x86/microcode: Document the three loading methods

[Borislav Petkov]

From: Borislav Petkov <bp@suse.de>

Paul Menzel <pmenzel@molgen.mpg.de> asked recently how to load microcode
on a system and I realized that we don't really have all the methods
written down somewhere. Do that, so people can go and look them up.

Signed-off-by: Borislav Petkov <bp@suse.de>
---
 Documentation/x86/early-microcode.txt |  70 ------------------
 Documentation/x86/microcode.txt       | 133 ++++++++++++++++++++++++++++++++++
 2 files changed, 133 insertions(+), 70 deletions(-)
 delete mode 100644 Documentation/x86/early-microcode.txt
 create mode 100644 Documentation/x86/microcode.txt

diff --git a/Documentation/x86/early-microcode.txt b/Documentation/x86/early-microcode.txt
deleted file mode 100644
index 07749e7f3d50..000000000000
--- a/Documentation/x86/early-microcode.txt
+++ /dev/null
@@ -1,70 +0,0 @@
-Early load microcode
-====================
-By Fenghua Yu <fenghua.yu@intel.com>
-
-Kernel can update microcode in early phase of boot time. Loading microcode early
-can fix CPU issues before they are observed during kernel boot time.
-
-Microcode is stored in an initrd file. The microcode is read from the initrd
-file and loaded to CPUs during boot time.
-
-The format of the combined initrd image is microcode in cpio format followed by
-the initrd image (maybe compressed). Kernel parses the combined initrd image
-during boot time. The microcode file in cpio name space is:
-on Intel: kernel/x86/microcode/GenuineIntel.bin
-on AMD  : kernel/x86/microcode/AuthenticAMD.bin
-
-During BSP boot (before SMP starts), if the kernel finds the microcode file in
-the initrd file, it parses the microcode and saves matching microcode in memory.
-If matching microcode is found, it will be uploaded in BSP and later on in all
-APs.
-
-The cached microcode patch is applied when CPUs resume from a sleep state.
-
-There are two legacy user space interfaces to load microcode, either through
-/dev/cpu/microcode or through /sys/devices/system/cpu/microcode/reload file
-in sysfs.
-
-In addition to these two legacy methods, the early loading method described
-here is the third method with which microcode can be uploaded to a system's
-CPUs.
-
-The following example script shows how to generate a new combined initrd file in
-/boot/initrd-3.5.0.ucode.img with original microcode microcode.bin and
-original initrd image /boot/initrd-3.5.0.img.
-
-mkdir initrd
-cd initrd
-mkdir -p kernel/x86/microcode
-cp ../microcode.bin kernel/x86/microcode/GenuineIntel.bin (or AuthenticAMD.bin)
-find . | cpio -o -H newc >../ucode.cpio
-cd ..
-cat ucode.cpio /boot/initrd-3.5.0.img >/boot/initrd-3.5.0.ucode.img
-
-Builtin microcode
-=================
-
-We can also load builtin microcode supplied through the regular firmware
-builtin method CONFIG_FIRMWARE_IN_KERNEL. Only 64-bit is currently
-supported.
-
-Here's an example:
-
-CONFIG_FIRMWARE_IN_KERNEL=y
-CONFIG_EXTRA_FIRMWARE="intel-ucode/06-3a-09 amd-ucode/microcode_amd_fam15h.bin"
-CONFIG_EXTRA_FIRMWARE_DIR="/lib/firmware"
-
-This basically means, you have the following tree structure locally:
-
-/lib/firmware/
-|-- amd-ucode
-...
-|   |-- microcode_amd_fam15h.bin
-...
-|-- intel-ucode
-...
-|   |-- 06-3a-09
-...
-
-so that the build system can find those files and integrate them into
-the final kernel image. The early loader finds them and applies them.
diff --git a/Documentation/x86/microcode.txt b/Documentation/x86/microcode.txt
new file mode 100644
index 000000000000..6ab130c6ca45
--- /dev/null
+++ b/Documentation/x86/microcode.txt
@@ -0,0 +1,133 @@
+	The Linux Microcode Loader
+
+Authors: Fenghua Yu <fenghua.yu@intel.com>
+	 Borislav Petkov <bp@suse.de>
+
+The kernel has a x86 microcode loading facility which is supposed to
+provide microcode loading methods in the OS. Potential use cases are
+updating the microcode on platforms beyond the OEM EOL support, and
+updating the microcode on long-running systems without rebooting.
+
+The loader supports three loading methods:
+
+1. Early load microcode
+=======================
+
+The kernel can update microcode very early during boot. Loading
+microcode early can fix CPU issues before they are observed during
+kernel boot time.
+
+The microcode is stored in an initrd file. During boot, it is read from
+it and loaded into the CPU cores.
+
+The format of the combined initrd image is microcode in cpio format
+followed by the initrd image (possibly compressed). The loader parses
+the combined initrd image during boot.
+
+The microcode files in cpio name space are:
+
+on Intel: kernel/x86/microcode/GenuineIntel.bin
+on AMD  : kernel/x86/microcode/AuthenticAMD.bin
+
+During BSP (BootStrapping Processor) boot (pre-SMP), the kernel
+scans the microcode file in the initrd. If microcode matching the
+CPU is found, it will be applied in the BSP and later on in all APs
+(Application Processors).
+
+The loader also saves the matching microcode for the CPU in memory.
+Thus, the cached microcode patch is applied when CPUs resume from a
+sleep state.
+
+Here's a crude example how to prepare an initrd with microcode (this is
+normally done automatically by the distribution, when recreating the
+initrd, so you don't really have to do it yourself. It is documented
+here for future reference only).
+
+---
+  #!/bin/bash
+  
+  if [ -z "$1" ]; then
+      echo "You need to supply an initrd file"
+      exit 1
+  fi
+  
+  INITRD="$1"
+  
+  DSTDIR=kernel/x86/microcode
+  TMPDIR=/tmp/initrd
+  
+  rm -rf $TMPDIR
+  
+  mkdir $TMPDIR
+  cd $TMPDIR
+  mkdir -p $DSTDIR
+  
+  if [ -d /lib/firmware/amd-ucode ]; then
+          cat /lib/firmware/amd-ucode/microcode_amd*.bin > $DSTDIR/AuthenticAMD.bin
+  fi
+  
+  if [ -d /lib/firmware/intel-ucode ]; then
+          cat /lib/firmware/intel-ucode/* > $DSTDIR/GenuineIntel.bin
+  fi
+  
+  find . | cpio -o -H newc >../ucode.cpio
+  cd ..
+  mv $INITRD $INITRD.orig
+  cat ucode.cpio $INITRD.orig > $INITRD
+  
+  rm -rf $TMPDIR
+---
+
+The system needs to have the microcode packages installed into
+/lib/firmware or you need to fixup the paths above if yours are
+somewhere else and/or you've downloaded them directly from the processor
+vendor's site.
+
+2. Late loading
+===============
+
+There are two legacy user space interfaces to load microcode, either through
+/dev/cpu/microcode or through /sys/devices/system/cpu/microcode/reload file
+in sysfs.
+
+The /dev/cpu/microcode method is deprecated because it needs a special
+userspace tool for that.
+
+The easier method is simply installing the microcode packages your distro
+supplies and running:
+
+# echo 1 > /sys/devices/system/cpu/microcode/reload
+
+as root.
+
+3. Builtin microcode
+====================
+
+The loader supports also loading of a builtin microcode supplied through
+the regular firmware builtin method CONFIG_FIRMWARE_IN_KERNEL. Only
+64-bit is currently supported.
+
+Here's an example:
+
+CONFIG_FIRMWARE_IN_KERNEL=y
+CONFIG_EXTRA_FIRMWARE="intel-ucode/06-3a-09 amd-ucode/microcode_amd_fam15h.bin"
+CONFIG_EXTRA_FIRMWARE_DIR="/lib/firmware"
+
+This basically means, you have the following tree structure locally:
+
+/lib/firmware/
+|-- amd-ucode
+...
+|   |-- microcode_amd_fam15h.bin
+...
+|-- intel-ucode
+...
+|   |-- 06-3a-09
+...
+
+so that the build system can find those files and integrate them into
+the final kernel image. The early loader finds them and applies them.
+
+Needless to say, this method is not the most flexible one because it
+requires rebuilding the kernel each time updated microcode from the CPU
+vendor is available.
-- 
2.14.0.rc0

Re: [PATCH] x86/microcode: Document the three loading methods

[Dominik Brodowski]

Thanks for the nice write-up! A few comments below:

On Mon, Jul 17, 2017 at 11:43:28AM +0200, Borislav Petkov wrote:
> new file mode 100644
> index 000000000000..6ab130c6ca45
> --- /dev/null
> +++ b/Documentation/x86/microcode.txt
> @@ -0,0 +1,133 @@
> +	The Linux Microcode Loader
> +
> +Authors: Fenghua Yu <fenghua.yu@intel.com>
> +	 Borislav Petkov <bp@suse.de>
> +
> +The kernel has a x86 microcode loading facility which is supposed to
> +provide microcode loading methods in the OS. Potential use cases are
> +updating the microcode on platforms beyond the OEM EOL support, and
> +updating the microcode on long-running systems without rebooting.
> +
> +The loader supports three loading methods:
> +
> +1. Early load microcode
> +=======================
> +
> +The kernel can update microcode very early during boot. Loading
> +microcode early can fix CPU issues before they are observed during
> +kernel boot time.
> +
> +The microcode is stored in an initrd file. During boot, it is read from
> +it and loaded into the CPU cores.
> +
> +The format of the combined initrd image is microcode in cpio format
> +followed by the initrd image (possibly compressed). The loader parses

What about: "... microcode in (uncompressed) cpio format followed by the
(possibly compressed) initrd image", to clarify this distinction?

> +          cat /lib/firmware/amd-ucode/microcode_amd*.bin > $DSTDIR/AuthenticAMD.bin
> +  fi
> +  
> +  if [ -d /lib/firmware/intel-ucode ]; then
> +          cat /lib/firmware/intel-ucode/* > $DSTDIR/GenuineIntel.bin
> +  fi

What about something more fancy, such as
	iucode_tool -v /lib/firmware/intel-ucode/ -S $DSTDIR/GenuineIntel.bin
?

> +2. Late loading
> +===============
> +
> +There are two legacy user space interfaces to load microcode, either through
> +/dev/cpu/microcode or through /sys/devices/system/cpu/microcode/reload file
> +in sysfs.
> +
> +The /dev/cpu/microcode method is deprecated because it needs a special
> +userspace tool for that.
> +
> +The easier method is simply installing the microcode packages your distro
> +supplies and running:
> +
> +# echo 1 > /sys/devices/system/cpu/microcode/reload
> +
> +as root.

Maybe specify here that this works using the firmware infrastructure,
therefore the microcode will be loaded from /lib/firmware/ ? Basically the
same terms apply for this method as for the builtin microcode you describe
next.

> +3. Builtin microcode
> +====================
> +
> +The loader supports also loading of a builtin microcode supplied through
> +the regular firmware builtin method CONFIG_FIRMWARE_IN_KERNEL. Only
> +64-bit is currently supported.
> +
> +Here's an example:
> +
> +CONFIG_FIRMWARE_IN_KERNEL=y
> +CONFIG_EXTRA_FIRMWARE="intel-ucode/06-3a-09 amd-ucode/microcode_amd_fam15h.bin"
> +CONFIG_EXTRA_FIRMWARE_DIR="/lib/firmware"
> +
> +This basically means, you have the following tree structure locally:
> +
> +/lib/firmware/
> +|-- amd-ucode
> +...
> +|   |-- microcode_amd_fam15h.bin
> +...
> +|-- intel-ucode
> +...
> +|   |-- 06-3a-09
> +...
> +
> +so that the build system can find those files and integrate them into
> +the final kernel image. The early loader finds them and applies them.
> +
> +Needless to say, this method is not the most flexible one because it
> +requires rebuilding the kernel each time updated microcode from the CPU
> +vendor is available.

Best,
	Dominik

Re: [PATCH] x86/microcode: Document the three loading methods

[Borislav Petkov]

On Tue, Jul 18, 2017 at 08:27:54AM +0200, Dominik Brodowski wrote:
> What about: "... microcode in (uncompressed) cpio format followed by the
> (possibly compressed) initrd image", to clarify this distinction?

Meh.

> What about something more fancy, such as
> 	iucode_tool -v /lib/firmware/intel-ucode/ -S $DSTDIR/GenuineIntel.bin
> ?

Why, because fancy is better? And simple is not good enough?

The less we rely on special tools for kernel stuff, the better.

> Maybe specify here that this works using the firmware infrastructure,
> therefore the microcode will be loaded from /lib/firmware/ ? Basically the
> same terms apply for this method as for the builtin microcode you describe
> next.

The distro package already installs it into /lib/firmware but ok, I'll
note the path explicitly.

Thx.

-- 
Regards/Gruss,
    Boris.

ECO tip #101: Trim your mails when you reply.
--