Skip to contentSkip to conversation

docs/ucode: Extend runtime microcode loading documentation

PATCH In review Andrew Cooper 4 participants 5 messages Jun 1, 2020 – Jun 2, 2020

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 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.

---
CC: George Dunlap <[email protected]>
CC: Ian Jackson <[email protected]>
CC: Jan Beulich <[email protected]>
CC: Konrad Rzeszutek Wilk <[email protected]>
CC: Stefano Stabellini <[email protected]>
CC: Wei Liu <[email protected]>
CC: Julien Grall <[email protected]>
CC: Paul Durrant <[email protected]>

---
 docs/admin-guide/microcode-loading.rst | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)
docs/admin-guide/microcode-loading.rst +19 -3
index 5f0f661a2e..8cd5d0351b 100644
@@ -104,8 +104,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::
 
@@ -113,7 +113,23 @@ 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 proprietry nature of microcode, we are unable to make any claim
+   that a runtime microcode is risk-free.  Any runtime microcode loading needs
+   adequate testing on a dev 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 ~]#
+
+e.g. With a Linux dom0 on a Haswell system::
+
+  [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.
 
Signature · 1 line
2.11.0
#1 lore raw
Quoted 46 lines

-----Original Message-----
From: Andrew Cooper <[email protected]>
Sent: 01 June 2020 14:40
To: Xen-devel <[email protected]>
Cc: Andrew Cooper <[email protected]>; George Dunlap <[email protected]>; Ian Jackson <[email protected]>; Jan Beulich <[email protected]>; Konrad Rzeszutek Wilk <[email protected]>; Stefano Stabellini <[email protected]>; Wei Liu <[email protected]>; Julien Grall <[email protected]>; Paul Durrant <[email protected]>
Subject: [PATCH for-4.14] 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.

---
CC: George Dunlap <[email protected]>
CC: Ian Jackson <[email protected]>
CC: Jan Beulich <[email protected]>
CC: Konrad Rzeszutek Wilk <[email protected]>
CC: Stefano Stabellini <[email protected]>
CC: Wei Liu <[email protected]>
CC: Julien Grall <[email protected]>
CC: Paul Durrant <[email protected]>

---
 docs/admin-guide/microcode-loading.rst | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)
docs/admin-guide/microcode-loading.rst +2 -2
index 5f0f661a2e..8cd5d0351b 100644
@@ -104,8 +104,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::
 

docs/admin-guide/microcode-loading.rst Run time microcode loading · line 116

Quoted 5 lines
docs/admin-guide/microcode-loading.rst +1 -1
@@ -113,7 +113,23 @@ 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 proprietry nature of microcode, we are unable to make any claim

s/proprietry/proprietary

with that fixed this is...

Quoted 21 lines
docs/admin-guide/microcode-loading.rst +16 -1
+   that a runtime microcode is risk-free.  Any runtime microcode loading needs
+   adequate testing on a dev 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 ~]#
+
+e.g. With a Linux dom0 on a Haswell system::
+
+  [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.
 
--

2.11.0

Reviewed-by on v1 1/1
#2 lore raw
In reply to Andrew Cooper
Quoted 7 lines · Andrew Cooper

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.

Quoted 38 lines

---
CC: George Dunlap <[email protected]>
CC: Ian Jackson <[email protected]>
CC: Jan Beulich <[email protected]>
CC: Konrad Rzeszutek Wilk <[email protected]>
CC: Stefano Stabellini <[email protected]>
CC: Wei Liu <[email protected]>
CC: Julien Grall <[email protected]>
CC: Paul Durrant <[email protected]>

---
 docs/admin-guide/microcode-loading.rst | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)
docs/admin-guide/microcode-loading.rst +7 -3
index 5f0f661a2e..8cd5d0351b 100644
@@ -104,8 +104,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::
 
@@ -113,7 +113,23 @@ 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 proprietry nature of microcode, we are unable to make any claim
+   that a runtime microcode is risk-free.  Any runtime microcode loading needs
+   adequate testing on a dev instance before being rolled out to production
+   systems.
+

docs/admin-guide/microcode-loading.rst Run time microcode loading · line 130

Quoted 10 lines
docs/admin-guide/microcode-loading.rst +10 -0
+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 ~]#
+
+e.g. With a Linux dom0 on a Haswell system::
+
+  [root@host ~]# xen-ucode /lib/firmware/intel-ucode/06-3c-03

Could you expand a bit on the nomenclature used here?

I assume it's something like <fam>-<model>-<version> but might be good to provide people a hint to know how to find the appropriate blob for their system if possible.

Thanks, Roger.

#3 lore raw
Quoted 10 lines · Roger Pau Monné
Quoted 7 lines · Andrew Cooper

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.

Thanks,

Quoted 51 lines
Quoted 39 lines

---
CC: George Dunlap <[email protected]>
CC: Ian Jackson <[email protected]>
CC: Jan Beulich <[email protected]>
CC: Konrad Rzeszutek Wilk <[email protected]>
CC: Stefano Stabellini <[email protected]>
CC: Wei Liu <[email protected]>
CC: Julien Grall <[email protected]>
CC: Paul Durrant <[email protected]>

---
 docs/admin-guide/microcode-loading.rst | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)
docs/admin-guide/microcode-loading.rst +7 -3
index 5f0f661a2e..8cd5d0351b 100644
@@ -104,8 +104,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::
 
@@ -113,7 +113,23 @@ 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 proprietry nature of microcode, we are unable to make any claim
+   that a runtime microcode is risk-free.  Any runtime microcode loading needs
+   adequate testing on a dev instance before being rolled out to production
+   systems.
+

docs/admin-guide/microcode-loading.rst Run time microcode loading · line 130

Quoted 10 lines
docs/admin-guide/microcode-loading.rst +10 -0
+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 ~]#
+
+e.g. With a Linux dom0 on a Haswell system::
+
+  [root@host ~]# xen-ucode /lib/firmware/intel-ucode/06-3c-03

Could you expand a bit on the nomenclature used here?

Quoted 3 lines

I assume it's something like <fam>-<model>-<version> but might be good to provide people a hint to know how to find the appropriate blob for their system if possible.

It is $FAMILY-$MODEL-$STEPPING.  Currently only a single version of each microcode is installed at once by the microcode_ctl package.

However, its infeasible to cater to all setup's/situations here.  Within linux, you could clone
https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files/ or use the slightly older single monolithic microcode.dat.

And that is before you start considering non-Intel systems, or other ways of packaging microcode.

I'm open to suggestions for how to make this clearer, but we definitely can't do an exhaustive list of places you might find microcode.

~Andrew

Reviewed-by on v1 1/1
#4 lore raw
In reply to Andrew Cooper
Quoted 36 lines · Andrew Cooper

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.

---
CC: George Dunlap <[email protected]>
CC: Ian Jackson <[email protected]>
CC: Jan Beulich <[email protected]>
CC: Konrad Rzeszutek Wilk <[email protected]>
CC: Stefano Stabellini <[email protected]>
CC: Wei Liu <[email protected]>
CC: Julien Grall <[email protected]>
CC: Paul Durrant <[email protected]>

---
 docs/admin-guide/microcode-loading.rst | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)
docs/admin-guide/microcode-loading.rst +2 -2
index 5f0f661a2e..8cd5d0351b 100644
@@ -104,8 +104,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::
 

docs/admin-guide/microcode-loading.rst Run time microcode loading · line 117

Quoted 6 lines
docs/admin-guide/microcode-loading.rst +2 -1
@@ -113,7 +113,23 @@ 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 proprietry nature of microcode, we are unable to make any claim
+   that a runtime microcode is risk-free.  Any runtime microcode loading needs

"that runtime microcode loading is risk-free" (or some such, including the word "load")? Then

Jan