[Xen-changelog] [xen staging] docs/admin-guide: Boot time microcode loading

[patchbot@xxxxxxx]

commit cb70a26f78848fe45f593f7ebc9cfaac760a791b
Author:     Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
AuthorDate: Mon Mar 18 16:22:29 2019 +0000
Commit:     Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
CommitDate: Fri Mar 22 13:48:02 2019 +0000

    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>
    Acked-by: Jan Beulich <jbeulich@xxxxxxxx>
    Acked-by: Wei Liu <wei.liu2@xxxxxxxxxx>
---
 docs/admin-guide/index.rst             |   5 ++
 docs/admin-guide/microcode-loading.rst | 103 +++++++++++++++++++++++++++++++++
 docs/index.rst                         |   9 +++
 3 files changed, 117 insertions(+)

diff --git a/docs/admin-guide/index.rst b/docs/admin-guide/index.rst
new file mode 100644
index 0000000000..f725d75ebe
--- /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
index 0000000000..1858ed4627
--- /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 20f097ddb0..50c40c8174 100644
--- 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
--
generated by git-patchbot for /home/xen/git/xen.git#staging

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/xen-changelog