0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ==========================
0004 The Linux Microcode Loader
0005 ==========================
0006
0007 :Authors: - Fenghua Yu <fenghua.yu@intel.com>
0008 - Borislav Petkov <bp@suse.de>
0009
0010 The kernel has a x86 microcode loading facility which is supposed to
0011 provide microcode loading methods in the OS. Potential use cases are
0012 updating the microcode on platforms beyond the OEM End-Of-Life support,
0013 and updating the microcode on long-running systems without rebooting.
0014
0015 The loader supports three loading methods:
0016
0017 Early load microcode
0018 ====================
0019
0020 The kernel can update microcode very early during boot. Loading
0021 microcode early can fix CPU issues before they are observed during
0022 kernel boot time.
0023
0024 The microcode is stored in an initrd file. During boot, it is read from
0025 it and loaded into the CPU cores.
0026
0027 The format of the combined initrd image is microcode in (uncompressed)
0028 cpio format followed by the (possibly compressed) initrd image. The
0029 loader parses the combined initrd image during boot.
0030
0031 The microcode files in cpio name space are:
0032
0033 on Intel:
0034 kernel/x86/microcode/GenuineIntel.bin
0035 on AMD :
0036 kernel/x86/microcode/AuthenticAMD.bin
0037
0038 During BSP (BootStrapping Processor) boot (pre-SMP), the kernel
0039 scans the microcode file in the initrd. If microcode matching the
0040 CPU is found, it will be applied in the BSP and later on in all APs
0041 (Application Processors).
0042
0043 The loader also saves the matching microcode for the CPU in memory.
0044 Thus, the cached microcode patch is applied when CPUs resume from a
0045 sleep state.
0046
0047 Here's a crude example how to prepare an initrd with microcode (this is
0048 normally done automatically by the distribution, when recreating the
0049 initrd, so you don't really have to do it yourself. It is documented
0050 here for future reference only).
0051 ::
0052
0053 #!/bin/bash
0054
0055 if [ -z "$1" ]; then
0056 echo "You need to supply an initrd file"
0057 exit 1
0058 fi
0059
0060 INITRD="$1"
0061
0062 DSTDIR=kernel/x86/microcode
0063 TMPDIR=/tmp/initrd
0064
0065 rm -rf $TMPDIR
0066
0067 mkdir $TMPDIR
0068 cd $TMPDIR
0069 mkdir -p $DSTDIR
0070
0071 if [ -d /lib/firmware/amd-ucode ]; then
0072 cat /lib/firmware/amd-ucode/microcode_amd*.bin > $DSTDIR/AuthenticAMD.bin
0073 fi
0074
0075 if [ -d /lib/firmware/intel-ucode ]; then
0076 cat /lib/firmware/intel-ucode/* > $DSTDIR/GenuineIntel.bin
0077 fi
0078
0079 find . | cpio -o -H newc >../ucode.cpio
0080 cd ..
0081 mv $INITRD $INITRD.orig
0082 cat ucode.cpio $INITRD.orig > $INITRD
0083
0084 rm -rf $TMPDIR
0085
0086
0087 The system needs to have the microcode packages installed into
0088 /lib/firmware or you need to fixup the paths above if yours are
0089 somewhere else and/or you've downloaded them directly from the processor
0090 vendor's site.
0091
0092 Late loading
0093 ============
0094
0095 There are two legacy user space interfaces to load microcode, either through
0096 /dev/cpu/microcode or through /sys/devices/system/cpu/microcode/reload file
0097 in sysfs.
0098
0099 The /dev/cpu/microcode method is deprecated because it needs a special
0100 userspace tool for that.
0101
0102 The easier method is simply installing the microcode packages your distro
0103 supplies and running::
0104
0105 # echo 1 > /sys/devices/system/cpu/microcode/reload
0106
0107 as root.
0108
0109 The loading mechanism looks for microcode blobs in
0110 /lib/firmware/{intel-ucode,amd-ucode}. The default distro installation
0111 packages already put them there.
0112
0113 Builtin microcode
0114 =================
0115
0116 The loader supports also loading of a builtin microcode supplied through
0117 the regular builtin firmware method CONFIG_EXTRA_FIRMWARE. Only 64-bit is
0118 currently supported.
0119
0120 Here's an example::
0121
0122 CONFIG_EXTRA_FIRMWARE="intel-ucode/06-3a-09 amd-ucode/microcode_amd_fam15h.bin"
0123 CONFIG_EXTRA_FIRMWARE_DIR="/lib/firmware"
0124
0125 This basically means, you have the following tree structure locally::
0126
0127 /lib/firmware/
0128 |-- amd-ucode
0129 ...
0130 | |-- microcode_amd_fam15h.bin
0131 ...
0132 |-- intel-ucode
0133 ...
0134 | |-- 06-3a-09
0135 ...
0136
0137 so that the build system can find those files and integrate them into
0138 the final kernel image. The early loader finds them and applies them.
0139
0140 Needless to say, this method is not the most flexible one because it
0141 requires rebuilding the kernel each time updated microcode from the CPU
0142 vendor is available.
