[xen staging] docs/ucode: Extend runtime microcode loading documentation

[patchbot@xxxxxxx]

commit 99a76a88d5e7f4693bb6b286e366006e1da1c954
Author:     Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
AuthorDate: Mon Jun 1 14:36:28 2020 +0100
Commit:     Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
CommitDate: Tue Jun 2 19:18:44 2020 +0100

    docs/ucode: Extend runtime microcode loading documentation
    
    Extend the disclaimer about runtime loading.  While we've done our best to
    make the mechaism reliable, the safety of late loading does ultimately 
depend
    on the contents of the blobs.
    
    Extend the xen-ucode portion with examples of how to use it.
    
    Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
    Reviewed-by: Roger Pau Monné <roger.pau@xxxxxxxxxx>
    Reviewed-by: Jan Beulich <jbeulich@xxxxxxxx>
    Release-acked-by: Paul Durrant <paul@xxxxxxx>
    ---
    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: Wei Liu <wl@xxxxxxx>
    CC: Julien Grall <julien@xxxxxxx>
    CC: Paul Durrant <paul@xxxxxxx>
---
 docs/admin-guide/microcode-loading.rst | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

diff --git a/docs/admin-guide/microcode-loading.rst 
b/docs/admin-guide/microcode-loading.rst
index e83cadd2c2..a07e25802f 100644
--- a/docs/admin-guide/microcode-loading.rst
+++ b/docs/admin-guide/microcode-loading.rst
@@ -105,8 +105,8 @@ modules to find any CPIO archives, and search the archive 
for the applicable
 file.  Xen will stop searching at the first match.
 
 
-Run time microcode loading
---------------------------
+Runtime microcode loading
+-------------------------
 
 .. warning::
 
@@ -114,7 +114,25 @@ Run time microcode loading
    or at boot time.  Not all microcode updates (or parts thereof) can be
    applied at runtime.
 
-The ``xen-ucode`` utility can be used to initiate a runtime microcode load.
+   Given the proprietary nature of microcode, we are unable to make any claim
+   that runtime microcode loading is risk-free.  Any runtime microcode loading
+   needs adequate testing on a development instance before being rolled out to
+   production systems.
+
+The ``xen-ucode`` utility can be used to initiate a runtime microcode load::
+
+  [root@host ~]# xen-ucode
+  xen-ucode: Xen microcode updating tool
+  Usage: xen-ucode <microcode blob>
+  [root@host ~]#
+
+The details of microcode blobs (if even packaged to begin with) are specific
+to the dom0 distribution.  Consult your dom0 OS documentation for details.
+One example with a Linux dom0 on a Haswell system might look like::
+
+  [root@host ~]# xen-ucode /lib/firmware/intel-ucode/06-3c-03
+  [root@host ~]#
+
 It will pass the blob to Xen, which will check to see whether the blob is
 correct for the processor, and newer than the running microcode.
 
--
generated by git-patchbot for /home/xen/git/xen.git#staging