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@xxxxxxxxx>
> +	 Borislav Petkov <bp@xxxxxxx>
> +
> +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