1.. SPDX-License-Identifier: CC-BY-4.0
2
3Microcode Loading
4=================
5
6Like many other pieces of hardware, CPUs themselves have errata which are
7discovered after shipping, and need to be addressed in the field.  Microcode
8can be considered as firmware for the processor, and updates are published as
9needed by the CPU vendors.
10
11Microcode is included as part of the system firmware by an OEM, and a system
12firmware update is the preferred way of obtaining updated microcode.  However,
13this is often not the most expedient way to get updates, so Xen supports
14loading microcode itself.
15
16Distros typically package microcode updates for users, and may provide hooks
17to cause microcode to be automatically loaded at boot time.  Consult your dom0
18distro guidance for microcode loading.
19
20Microcode can make almost arbitrary changes to the processor, including to
21software visible features.  This includes removing features (e.g. the Haswell
22TSX errata which necessitated disabling the feature entirely), or the addition
23of brand new features (e.g. the Spectre v2 controls to work around speculative
24execution vulnerabilities).
25
26
27Boot time microcode loading
28---------------------------
29
30Where possible, microcode should be loaded at boot time.  This allows the CPU
31to be updated to its eventual configuration before Xen starts making setup
32decisions based on the visible features.
33
34Xen will report during boot if it performed a microcode update::
35
36  [root@host ~]# xl dmesg | grep microcode
37  (XEN) microcode: CPU0 updated from revision 0x1a to 0x25, date = 2018-04-02
38  (XEN) microcode: CPU2 updated from revision 0x1a to 0x25, date = 2018-04-02
39  (XEN) microcode: CPU4 updated from revision 0x1a to 0x25, date = 2018-04-02
40  (XEN) microcode: CPU6 updated from revision 0x1a to 0x25, date = 2018-04-02
41
42The exact details printed are system and microcode specific.  After boot, the
43current microcode version can obtained from with dom0::
44
45  [root@host ~]# head /proc/cpuinfo
46  processor    : 0
47  vendor_id    : GenuineIntel
48  cpu family   : 6
49  model        : 60
50  model name   : Intel(R) Xeon(R) CPU E3-1240 v3 @ 3.40GHz
51  stepping     : 3
52  microcode    : 0x25
53  cpu MHz      : 3392.148
54  cache size   : 8192 KB
55  physical id  : 0
56
57
58Loading microcode from a single file
59~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
60
61Xen handles microcode blobs in the binary form shipped by vendors, which is
62also the format which the processor accepts.  This format contains header
63information which Xen and various userspace tools can use to identify the
64correct blob for a specific CPU.
65
66Tools such as Dracut will identify the correct blob for the current CPU, which
67will be a few kilobytes, for minimal overhead during boot.
68
69Additionally, Xen is capable of handling a number of blobs concatenated
70together, and will locate the appropriate blob based on the header
71information.
72
73This option is less efficient during boot, but may be preferred in situations
74where the exact CPU details aren't known ahead of booting (e.g. install
75media).
76
77The file containing the blob(s) needs to be accessible to Xen as early as
78possible.
79
80* For multiboot/multiboot2 boots, this is achieved by loading the file as a
81  multiboot module.  The ``ucode=$num`` command line option can be used to
82  identify which multiboot module contains the microcode, including negative
83  indexing to count from the end.
84
85* For EFI boots, there isn't really a concept of modules.  A microcode file
86  can be specified in the EFI configuration file with ``ucode=$file``.  Use of
87  this mechanism will override any ``ucode=`` settings on the command line.
88
89
90Loading microcode from a Linux initrd
91~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92
93For systems using a Linux based dom0, it usually suffices to install the
94appropriate distro package, and add ``ucode=scan`` to Xen's command line.
95
96Xen is compatible with the Linux initrd microcode protocol.  The initrd is
97expected to be generated with an uncompressed CPIO archive at the beginning
98which contains contains one of these two files::
99
100  kernel/x86/microcode/GenuineIntel.bin
101  kernel/x86/microcode/AuthenticAMD.bin
102
103The ``ucode=scan`` command line option will cause Xen to search through all
104modules to find any CPIO archives, and search the archive for the applicable
105file.  Xen will stop searching at the first match.
106
107
108Runtime microcode loading
109-------------------------
110
111.. warning::
112
113   If at all possible, microcode updates should be done by firmware updates,
114   or at boot time.  Not all microcode updates (or parts thereof) can be
115   applied at runtime.
116
117   Given the proprietary nature of microcode, we are unable to make any claim
118   that runtime microcode loading is risk-free.  Any runtime microcode loading
119   needs adequate testing on a development instance before being rolled out to
120   production systems.
121
122The ``xen-ucode`` utility can be used to initiate a runtime microcode load::
123
124  [root@host ~]# xen-ucode
125  xen-ucode: Xen microcode updating tool
126  Usage: xen-ucode <microcode blob>
127  [root@host ~]#
128
129The details of microcode blobs (if even packaged to begin with) are specific
130to the dom0 distribution.  Consult your dom0 OS documentation for details.
131One example with a Linux dom0 on a Haswell system might look like::
132
133  [root@host ~]# xen-ucode /lib/firmware/intel-ucode/06-3c-03
134  [root@host ~]#
135
136It will pass the blob to Xen, which will check to see whether the blob is
137correct for the processor, and newer than the running microcode.
138
139If these checks pass, the entire system will be rendezvoused and an update
140will be initiated on all CPUs in parallel.  As with boot time loading,
141diagnostics will be put out onto the console::
142
143  [root@host ~]# xl dmesg | grep microcode
144  (XEN) microcode: CPU0 updated from revision 0x1a to 0x25, date = 2018-04-02
145  (XEN) microcode: CPU2 updated from revision 0x1a to 0x25, date = 2018-04-02
146  (XEN) microcode: CPU4 updated from revision 0x1a to 0x25, date = 2018-04-02
147  (XEN) microcode: CPU6 updated from revision 0x1a to 0x25, date = 2018-04-02
148  (XEN) 4 cores are to update their microcode
149  (XEN) microcode: CPU0 updated from revision 0x25 to 0x27, date = 2019-02-26
150  (XEN) microcode: CPU4 updated from revision 0x25 to 0x27, date = 2019-02-26
151  (XEN) microcode: CPU2 updated from revision 0x25 to 0x27, date = 2019-02-26
152  (XEN) microcode: CPU6 updated from revision 0x25 to 0x27, date = 2019-02-26
153