[Xen-changelog] [xen staging] x86/ucode: Document the behaviour of the microcode_ops hooks

[patchbot@xxxxxxx]

commit 9267a439c10a619a289528987ddeff1bd2c3a643
Author:     Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
AuthorDate: Fri Mar 20 15:37:28 2020 +0000
Commit:     Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
CommitDate: Thu Mar 26 18:57:45 2020 +0000

    x86/ucode: Document the behaviour of the microcode_ops hooks
    
    ... and struct cpu_signature for good measure.
    
    No comment is passed on the suitability of the behaviour...
    
    Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
    Acked-by: Jan Beulich <jbeulich@xxxxxxxx>
---
 xen/arch/x86/cpu/microcode/private.h | 46 ++++++++++++++++++++++++++++++++++++
 xen/include/asm-x86/microcode.h      |  5 ++++
 2 files changed, 51 insertions(+)

diff --git a/xen/arch/x86/cpu/microcode/private.h 
b/xen/arch/x86/cpu/microcode/private.h
index c32ddc8d19..230b935c94 100644
--- a/xen/arch/x86/cpu/microcode/private.h
+++ b/xen/arch/x86/cpu/microcode/private.h
@@ -20,14 +20,60 @@ struct microcode_patch {
 };
 
 struct microcode_ops {
+    /*
+     * Parse a microcode container.  Format is vendor-specific.
+     *
+     * Search within the container for the patch, suitable for the current
+     * CPU, which has the highest revision.  (Note: May be a patch which is
+     * older that what is running in the CPU.  This is a feature, to better
+     * cope with corner cases from buggy firmware.)
+     *
+     * If one is found, allocate and return a struct microcode_patch
+     * encapsulating the appropriate microcode patch.  Does not alias the
+     * original buffer.
+     *
+     * If one is not found, (nothing matches the current CPU), return NULL.
+     * Also may return ERR_PTR(-err), e.g. bad container, out of memory.
+     */
     struct microcode_patch *(*cpu_request_microcode)(const void *buf,
                                                      size_t size);
+
+    /* Obtain microcode-relevant details for the current CPU. */
     int (*collect_cpu_info)(struct cpu_signature *csig);
+
+    /*
+     * Attempt to load the provided patch into the CPU.  Returns an error if
+     * anything didn't go as expected.
+     */
     int (*apply_microcode)(const struct microcode_patch *patch);
+
+    /*
+     * Optional.  If provided and applicable to the specific update attempt,
+     * is run once by the initiating CPU.  Returning an error will abort the
+     * load attempt.
+     */
     int (*start_update)(void);
+
+    /*
+     * Optional.  If provided, called on every CPU which completes a microcode
+     * load.  May be called in the case of some errors, and not others.  May
+     * be called even if start_update() wasn't.
+     */
     void (*end_update_percpu)(void);
+
+    /* Free a patch previously allocated by cpu_request_microcode(). */
     void (*free_patch)(void *mc);
+
+    /*
+     * Is the microcode patch applicable for the current CPU, and newer than
+     * the currently running patch?
+     */
     bool (*match_cpu)(const struct microcode_patch *patch);
+
+    /*
+     * Given two patches, are they both applicable to the current CPU, and is
+     * new a higher revision than old?
+     */
     enum microcode_match_result (*compare_patch)(
         const struct microcode_patch *new, const struct microcode_patch *old);
 };
diff --git a/xen/include/asm-x86/microcode.h b/xen/include/asm-x86/microcode.h
index 89b9aaa02d..3a8e4e8221 100644
--- a/xen/include/asm-x86/microcode.h
+++ b/xen/include/asm-x86/microcode.h
@@ -7,8 +7,13 @@
 #include <public/xen.h>
 
 struct cpu_signature {
+    /* CPU signature (CPUID.1.EAX).  Only written on Intel. */
     unsigned int sig;
+
+    /* Platform Flags.  Only applicable to Intel. */
     unsigned int pf;
+
+    /* Microcode Revision. */
     unsigned int rev;
 };
 
--
generated by git-patchbot for /home/xen/git/xen.git#staging

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