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@citrix.com>
Acked-by: Jan Beulich <jbeulich@suse.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>

diff --git a/docs/admin-guide/index.rst b/docs/admin-guide/index.rst
new file mode 100644 (file)
index 0000000..f725d75
--- /dev/null
+++ b/docs/admin-guide/index.rst
@@ -0,0 +1,5 @@
+Admin Guide
+===========
+
+.. toctree::
+  microcode-loading

diff --git a/docs/admin-guide/microcode-loading.rst b/docs/admin-guide/microcode-loading.rst
new file mode 100644 (file)
index 0000000..1858ed4
--- /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 updates are published as
+needed by the CPU 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 updates, 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::
+
+  [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::
+
+  [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 format which the processor accepts.  This format 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 file 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 archive 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 search the archive for the applicable
+file.  Xen will stop searching at the first match.

diff --git a/docs/index.rst b/docs/index.rst
index 20f097ddb09e4313f2a0a765779e081217ec7c7c..50c40c8174eeaa554e0f235809019df090c5bcee 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -5,3 +5,12 @@ The Xen Hypervisor documentation
 
   Xen's Sphinx/RST documentation is a work in progress.  The existing
   documentation can be found at https://xenbits.xen.org/docs/
+
+
+User documentation
+------------------
+
+.. toctree::
+  :maxdepth: 2
+
+  admin-guide/index