[PATCH 3/3] docs/admin-guide: Boot time microcode loading

[Andrew Cooper <andrew.cooper3@citrix.com>]

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@citrix.com>
---
CC: George Dunlap <George.Dunlap@eu.citrix.com>
CC: Ian Jackson <ian.jackson@citrix.com>
CC: Jan Beulich <JBeulich@suse.com>
CC: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
CC: Stefano Stabellini <sstabellini@kernel.org>
CC: Tim Deegan <tim@xen.org>
CC: Wei Liu <wei.liu2@citrix.com>
CC: Julien Grall <julien.grall@arm.com>
CC: Roger Pau Monné <roger.pau@citrix.com>
CC: Lars Kurth <lars.kurth@citrix.com>

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@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel