[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [Xen-devel] [PATCH 3/3] docs/admin-guide: Boot time microcode loading
Recent discussion on xen-devel has demonstrated that Xen existing microcode loading support isn't adequately documented. Take the opportunity to address this, and start some end-user focused documentation. Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx> --- CC: George Dunlap <George.Dunlap@xxxxxxxxxxxxx> CC: Ian Jackson <ian.jackson@xxxxxxxxxx> CC: Jan Beulich <JBeulich@xxxxxxxx> CC: Konrad Rzeszutek Wilk <konrad.wilk@xxxxxxxxxx> CC: Stefano Stabellini <sstabellini@xxxxxxxxxx> CC: Tim Deegan <tim@xxxxxxx> CC: Wei Liu <wei.liu2@xxxxxxxxxx> CC: Julien Grall <julien.grall@xxxxxxx> CC: Roger Pau Monné <roger.pau@xxxxxxxxxx> CC: Lars Kurth <lars.kurth@xxxxxxxxxx> I've deliberately omitted runtime microcode loading at this point, because it is currently rather broken and its implementation is in flux. This document can be extended in due course. --- docs/admin-guide/index.rst | 5 ++ docs/admin-guide/microcode-loading.rst | 103 +++++++++++++++++++++++++++++++++ docs/index.rst | 8 +++ 3 files changed, 116 insertions(+) create mode 100644 docs/admin-guide/index.rst create mode 100644 docs/admin-guide/microcode-loading.rst diff --git a/docs/admin-guide/index.rst b/docs/admin-guide/index.rst new file mode 100644 index 0000000..4d9bcb4 --- /dev/null +++ b/docs/admin-guide/index.rst @@ -0,0 +1,5 @@ +User documentation +================== + +.. toctree:: + microcode-loading diff --git a/docs/admin-guide/microcode-loading.rst b/docs/admin-guide/microcode-loading.rst new file mode 100644 index 0000000..58393b8 --- /dev/null +++ b/docs/admin-guide/microcode-loading.rst @@ -0,0 +1,103 @@ +Microcode Loading +================= + +Like many other pieces of hardware, CPUs themselves have errata which are +discovered after shipping, and need to be addressed in the field. Microcode +can be considered as firmware for the processor, and new microcode is +published as needed by the processor vendors. + +Microcode is included as part of the system firmware by an OEM, and a system +firmware update is the preferred way of obtaining updated microcode. However, +this is often not the most expedient way to get updated microcode, so Xen +supports loading microcode itself. + +Distros typically package microcode updates for users, and may provide hooks +to cause microcode to be automatically loaded at boot time. Consult your dom0 +distro guidance for microcode loading. + +Microcode can make almost arbitrary changes to the processor, including to +software visible features. This includes removing features (e.g. the Haswell +TSX errata which necessitated disabling the feature entirely), or the addition +of brand new features (e.g. the Spectre v2 controls to work around speculative +execution vulnerabilities). + + +Boot time microcode loading +--------------------------- + +Where possible, microcode should be loaded at boot time. This allows the CPU +to be updated to its eventual configuration before Xen starts making setup +decisions based on the visible features. + +Xen will report during boot if it performed a microcode update. e.g.:: + + [root@host ~]# xl dmesg | grep microcode + (XEN) microcode: CPU0 updated from revision 0x1a to 0x25, date = 2018-04-02 + (XEN) microcode: CPU2 updated from revision 0x1a to 0x25, date = 2018-04-02 + (XEN) microcode: CPU4 updated from revision 0x1a to 0x25, date = 2018-04-02 + (XEN) microcode: CPU6 updated from revision 0x1a to 0x25, date = 2018-04-02 + +The exact details printed are system and microcode specific. After boot, the +current microcode version can obtained from with dom0. e.g.:: + + [root@host ~]# head /proc/cpuinfo + processor : 0 + vendor_id : GenuineIntel + cpu family : 6 + model : 60 + model name : Intel(R) Xeon(R) CPU E3-1240 v3 @ 3.40GHz + stepping : 3 + microcode : 0x25 + cpu MHz : 3392.148 + cache size : 8192 KB + physical id : 0 + + +Loading microcode from a single file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Xen handles microcode blobs in the binary form shipped by vendors, which is +also the form the processor uses. This binary form contains header +information which Xen and various userspace tools can use to identify the +correct blob for a specific CPU. + +Tools such as dracut will identify the correct blob for the current CPU, which +will be a few kilobytes, for minimal overhead during boot. + +Additionally, Xen is capable of handling a number of blobs concatenated +together, and will locate the appropriate blob based on the header +information. + +This option is less efficient during boot, but may be preferred in situations +where the exact CPU details aren't known ahead of booting (e.g. install +media). + +The file containing the blob(s) needs to be accessible to Xen as early as +possible. + +* For multiboot/multiboot2 boots, this is achieved by loading the blob as a + multiboot module. The ``ucode=$num`` command line option can be used to + identify which multiboot module contains the microcode, including negative + indexing to count from the end. + +* For EFI boots, there isn't really a concept of modules. A microcode file + can be specified in the EFI configuration file with ``ucode=$file``. Use of + this mechanism will override any ``ucode=`` settings on the command line. + + +Loading microcode from a Linux initrd +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For systems using a Linux based dom0, it usually suffices to install the +appropriate distro package, and add ``ucode=scan`` to Xen's command line. + +Xen is compatible with the Linux initrd microcode protocol. The initrd is +expected to be generated with an uncompressed CPIO fragment at the beginning +which contains contains one of these two files:: + + kernel/x86/microcode/GenuineIntel.bin + kernel/x86/microcode/AuthenticAMD.bin + +The ``ucode=scan`` command line option will cause Xen to search through all +modules to find any CPIO archives, and look up the applicable file in the CPIO +archive. diff --git a/docs/index.rst b/docs/index.rst index 732ebe0..ab3d0e0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,2 +1,10 @@ The Xen Hypervisor documentation ================================ + +User documentation +------------------ + +.. toctree:: + :maxdepth: 2 + + admin-guide/index -- 2.1.4 _______________________________________________ Xen-devel mailing list Xen-devel@xxxxxxxxxxxxxxxxxxxx https://lists.xenproject.org/mailman/listinfo/xen-devel
|
Lists.xenproject.org is hosted with RackSpace, monitoring our |