x86/microcode: Document the three loading methods
PATCH 1/1 x86/microcode: Document the three loading methods
From: Borislav Petkov <[email protected]>
Paul Menzel <[email protected]> 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.
--- 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
Documentation/x86/early-microcode.txt deleted +0 -70
@@ -1,70 +0,0 @@ -Early load microcode -==================== -By Fenghua Yu <[email protected]> - -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.
Documentation/x86/microcode.txt new file +133 -0
133 lines not on this page · raw message
Signature · 1 line
2.14.0.rc0
Thanks for the nice write-up! A few comments below:
Quoted 19 lines · Borislav Petkov
new file mode 100644
index 000000000000..6ab130c6ca45Documentation/x86/microcode.txt new file +14
-0@@ -0,0 +1,133 @@ + The Linux Microcode Loader + +Authors: Fenghua Yu <[email protected]> + Borislav Petkov <[email protected]> + +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 +=======================
Documentation/x86/microcode.txt line 24
Quoted 10 lines
Documentation/x86/microcode.txt new file +10
-0+ +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?
Documentation/x86/microcode.txt line 71
Quoted 6 lines
Documentation/x86/microcode.txt new file +6
-0+ 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
?
Quoted 6 lines
Documentation/x86/microcode.txt new file +6
-0+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.
Documentation/x86/microcode.txt line 101
Quoted 10 lines
Documentation/x86/microcode.txt new file +10
-0+ +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.
Quoted 21 lines
Documentation/x86/microcode.txt new file +21
-0+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
Documentation/x86/microcode.txt line 133
Quoted 10 lines
Documentation/x86/microcode.txt new file +10
-0+... +| |-- 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
Quoted 2 lines · Dominik Brodowski
What about: "... microcode in (uncompressed) cpio format followed by the (possibly compressed) initrd image", to clarify this distinction?
Meh.
Quoted 3 lines
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.
Quoted 4 lines
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.
Signature · 5 lines
Regards/Gruss,
Boris.
ECO tip #101: Trim your mails when you reply.
--