[PATCH v3 0/2] fix several issues in documentation

[PATCH v3 0/2] fix several issues in documentation

[Juergen Gross]

Some documents contain invalid pandoc syntax leading to failures when
creating PDFs from them, e.g. when calling "make all" in the docs
directory.

Correct those by using proper lists, code blocks and special character
escaping.

Changes in V3:
- dropped patches 1 and 2 of V2 as already applied
- complete rework of intel_psr_cat_cdp.pandoc formatting (Andrew)

Changes in V2:
- dropped patches 1 and 4 as already applied
- rebased to current staging
- re-added dropped line in livepatch.markdown (Konrad)

In case the maintainers are fine with my changes I believe the series
should be included in 4.11. So for the series:

Release-acked-by: Juergen Gross <jgross@suse.com>

Juergen Gross (2):
  doc: correct livepatch.markdown syntax
  doc: correct intel_psr_cat_cdp.pandoc syntax

 docs/features/intel_psr_cat_cdp.pandoc | 562 ++++++++++++++++---------------
 docs/misc/livepatch.markdown           | 590 +++++++++++++++------------------
 2 files changed, 573 insertions(+), 579 deletions(-)

-- 
2.13.6


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel

[PATCH v3 1/2] doc: correct livepatch.markdown syntax

[Juergen Gross]

"make -C docs all" fails due to incorrect markdown syntax in
livepatch.markdown. Correct it.

Signed-off-by: Juergen Gross <jgross@suse.com>
Reviewed-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
---
 docs/misc/livepatch.markdown | 590 ++++++++++++++++++++-----------------------
 1 file changed, 273 insertions(+), 317 deletions(-)

diff --git a/docs/misc/livepatch.markdown b/docs/misc/livepatch.markdown
index 54a6b850cb..a4de44472a 100644
--- a/docs/misc/livepatch.markdown
+++ b/docs/misc/livepatch.markdown
@@ -89,33 +89,27 @@ As example we will assume the hypervisor does not have XSA-132 (see
 4ff3449f0e9d175ceb9551d3f2aecb59273f639d) and we would like to binary patch
 the hypervisor with it. The original code looks as so:
 
-<pre>
-   48 89 e0                  mov    %rsp,%rax  
-   48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax  
-</pre>
+       48 89 e0                  mov    %rsp,%rax
+       48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax
 
 while the new patched hypervisor would be:
 
-<pre>
-   48 c7 45 b8 00 00 00 00   movq   $0x0,-0x48(%rbp)  
-   48 c7 45 c0 00 00 00 00   movq   $0x0,-0x40(%rbp)  
-   48 c7 45 c8 00 00 00 00   movq   $0x0,-0x38(%rbp)  
-   48 89 e0                  mov    %rsp,%rax  
-   48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax  
-</pre>
+       48 c7 45 b8 00 00 00 00   movq   $0x0,-0x48(%rbp)
+       48 c7 45 c0 00 00 00 00   movq   $0x0,-0x40(%rbp)
+       48 c7 45 c8 00 00 00 00   movq   $0x0,-0x38(%rbp)
+       48 89 e0                  mov    %rsp,%rax
+       48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax
 
-This is inside the arch_do_domctl. This new change adds 21 extra
+This is inside the arch\_do\_domctl. This new change adds 21 extra
 bytes of code which alters all the offsets inside the function. To alter
 these offsets and add the extra 21 bytes of code we might not have enough
 space in .text to squeeze this in.
 
 As such we could simplify this problem by only patching the site
-which calls arch_do_domctl:
+which calls arch\_do\_domctl:
 
-<pre>
-do_domctl:  
- e8 4b b1 05 00          callq  ffff82d08015fbb9 <arch_do_domctl>  
-</pre>
+    do_domctl:
+     e8 4b b1 05 00          callq  ffff82d08015fbb9 <arch_do_domctl>
 
 with a new address for where the new `arch_do_domctl` would be (this
 area would be allocated dynamically).
@@ -123,15 +117,13 @@ area would be allocated dynamically).
 Astute readers will wonder what we need to do if we were to patch `do_domctl`
 - which is not called directly by hypervisor but on behalf of the guests via
 the `compat_hypercall_table` and `hypercall_table`.
-Patching the offset in `hypercall_table` for `do_domctl:
-(ffff82d080103079 <do_domctl>:)
+Patching the offset in `hypercall_table` for `do_domctl`:
+(ffff82d080103079 &lt;do\_domctl&gt;:)
 
-<pre>
-
- ffff82d08024d490:   79 30  
- ffff82d08024d492:   10 80 d0 82 ff ff   
-
-</pre>
+    
+     ffff82d08024d490:   79 30
+     ffff82d08024d492:   10 80 d0 82 ff ff
+    
 
 with the new address where the new `do_domctl` is possible. The other
 place where it is used is in `hvm_hypercall64_table` which would need
@@ -164,19 +156,17 @@ CPU branching logic (I-cache, but it is just one unconditional jump).
 
 For this example we will assume that the hypervisor has not been compiled
 with fe2e079f642effb3d24a6e1a7096ef26e691d93e (XSA-125: *pre-fill structures
-for certain HYPERVISOR_xen_version sub-ops*) which mem-sets an structure
+for certain HYPERVISOR\_xen\_version sub-ops*) which mem-sets an structure
 in `xen_version` hypercall. This function is not called **anywhere** in
 the hypervisor (it is called by the guest) but referenced in the
 `compat_hypercall_table` and `hypercall_table` (and indirectly called
 from that). Patching the offset in `hypercall_table` for the old
-`do_xen_version` (ffff82d080112f9e <do_xen_version>)
-
-</pre>
- ffff82d08024b270 <hypercall_table>:   
- ...  
- ffff82d08024b2f8:   9e 2f 11 80 d0 82 ff ff  
+`do_xen_version` (ffff82d080112f9e &lt;do\_xen\_version&gt;)
 
-</pre>
+     ffff82d08024b270 <hypercall_table>:
+     ...
+     ffff82d08024b2f8:   9e 2f 11 80 d0 82 ff ff
+    
 
 with the new address where the new `do_xen_version` is possible. The other
 place where it is used is in `hvm_hypercall64_table` which would need
@@ -184,21 +174,17 @@ to be patched in a similar way. This would require an in-place splicing
 of the new virtual address of `do_xen_version`.
 
 An alternative solution would be to patch insert a trampoline in the
-old `do_xen_version' function to directly jump to the new `do_xen_version`.
+old `do_xen_version` function to directly jump to the new `do_xen_version`.
 
-<pre>
- ffff82d080112f9e do_xen_version:  
- ffff82d080112f9e:       48 c7 c0 da ff ff ff    mov    $0xffffffffffffffda,%rax  
- ffff82d080112fa5:       83 ff 09                cmp    $0x9,%edi  
- ffff82d080112fa8:       0f 87 24 05 00 00       ja     ffff82d0801134d2 ; do_xen_version+0x534  
-</pre>
+     ffff82d080112f9e do_xen_version:
+     ffff82d080112f9e:       48 c7 c0 da ff ff ff    mov    $0xffffffffffffffda,%rax
+     ffff82d080112fa5:       83 ff 09                cmp    $0x9,%edi
+     ffff82d080112fa8:       0f 87 24 05 00 00       ja     ffff82d0801134d2 ; do_xen_version+0x534
 
 with:
 
-<pre>
- ffff82d080112f9e do_xen_version:  
- ffff82d080112f9e:       e9 XX YY ZZ QQ          jmpq   [new do_xen_version]  
-</pre>
+     ffff82d080112f9e do_xen_version:
+     ffff82d080112f9e:       e9 XX YY ZZ QQ          jmpq   [new do_xen_version]
 
 which would lessen the amount of patching to just one location.
 
@@ -208,7 +194,7 @@ new replacement function which required:
  * inserting trampoline with new offset in the old function to point to the
    new function.
  * Optionally we can insert in the old function a trampoline jump to an function
-   providing an BUG_ON to catch errant code.
+   providing an BUG\_ON to catch errant code.
 
 The disadvantage of this are that the unconditional jump will consume a small
 I-cache penalty. However the simplicity of the patching and higher chance
@@ -260,7 +246,7 @@ Note that every structure has padding. This is added so that the hypervisor
 can re-use those fields as it sees fit.
 
 Earlier design attempted to ineptly explain the relations of the ELF sections
-to each other without using proper ELF mechanism (sh_info, sh_link, data
+to each other without using proper ELF mechanism (sh\_info, sh\_link, data
 structures using Elf types, etc). This design will explain the structures
 and how they are used together and not dig in the ELF format - except mention
 that the section names should match the structure names.
@@ -285,27 +271,25 @@ like what the Linux kernel module loader does.
 
 The payload contains at least three sections:
 
- * `.livepatch.funcs` - which is an array of livepatch_func structures.
+ * `.livepatch.funcs` - which is an array of livepatch\_func structures.
  * `.livepatch.depends` - which is an ELF Note that describes what the payload
     depends on. **MUST** have one.
  *  `.note.gnu.build-id` - the build-id of this payload. **MUST** have one.
 
 ### .livepatch.funcs
 
-The `.livepatch.funcs` contains an array of livepatch_func structures
+The `.livepatch.funcs` contains an array of livepatch\_func structures
 which describe the functions to be patched:
 
-<pre>
-struct livepatch_func {  
-    const char *name;  
-    void *new_addr;  
-    void *old_addr;  
-    uint32_t new_size;  
-    uint32_t old_size;  
-    uint8_t version;  
-    uint8_t opaque[31];  
-};  
-</pre>
+    struct livepatch_func {
+        const char *name;
+        void *new_addr;
+        void *old_addr;
+        uint32_t new_size;
+        uint32_t old_size;
+        uint8_t version;
+        uint8_t opaque[31];
+    };
 
 The size of the structure is 64 bytes on 64-bit hypervisors. It will be
 52 on 32-bit hypervisors.
@@ -362,36 +346,34 @@ being applied and after being reverted:
 
 A simple example of what a payload file can be:
 
-<pre>
-/* MUST be in sync with hypervisor. */  
-struct livepatch_func {  
-    const char *name;  
-    void *new_addr;  
-    void *old_addr;  
-    uint32_t new_size;  
-    uint32_t old_size;  
-    uint8_t version;
-    uint8_t pad[31];  
-};  
-
-/* Our replacement function for xen_extra_version. */  
-const char *xen_hello_world(void)  
-{  
-    return "Hello World";  
-}  
-
-static unsigned char patch_this_fnc[] = "xen_extra_version";  
-
-struct livepatch_func livepatch_hello_world = {  
-    .version = LIVEPATCH_PAYLOAD_VERSION,
-    .name = patch_this_fnc,  
-    .new_addr = xen_hello_world,  
-    .old_addr = (void *)0xffff82d08013963c, /* Extracted from xen-syms. */  
-    .new_size = 13, /* To be be computed by scripts. */  
-    .old_size = 13, /* -----------""---------------  */  
-} __attribute__((__section__(".livepatch.funcs")));  
-
-</pre>
+    /* MUST be in sync with hypervisor. */
+    struct livepatch_func {
+        const char *name;
+        void *new_addr;
+        void *old_addr;
+        uint32_t new_size;
+        uint32_t old_size;
+        uint8_t version;
+        uint8_t pad[31];
+    };
+    
+    /* Our replacement function for xen_extra_version. */
+    const char *xen_hello_world(void)
+    {
+        return "Hello World";
+    }
+    
+    static unsigned char patch_this_fnc[] = "xen_extra_version";
+    
+    struct livepatch_func livepatch_hello_world = {
+        .version = LIVEPATCH_PAYLOAD_VERSION,
+        .name = patch_this_fnc,
+        .new_addr = xen_hello_world,
+        .old_addr = (void *)0xffff82d08013963c, /* Extracted from xen-syms. */
+        .new_size = 13, /* To be be computed by scripts. */
+        .old_size = 13, /* -----------""---------------  */
+    } __attribute__((__section__(".livepatch.funcs")));
+    
 
 Code must be compiled with -fPIC.
 
@@ -406,10 +388,8 @@ Each entry in this array is eight bytes.
 
 The type definition of the function are as follow:
 
-<pre>
-typedef void (*livepatch_loadcall_t)(void);  
-typedef void (*livepatch_unloadcall_t)(void);   
-</pre>
+    typedef void (*livepatch_loadcall_t)(void);
+    typedef void (*livepatch_unloadcall_t)(void);
 
 ### .livepatch.depends and .note.gnu.build-id
 
@@ -423,7 +403,7 @@ which follows the format of an ELF Note. The contents of this
 build the hypevisor and payload.
 
 If GNU linker is used then the name is `GNU` and the description
-is a NT_GNU_BUILD_ID type ID. The description can be an SHA1
+is a NT\_GNU\_BUILD\_ID type ID. The description can be an SHA1
 checksum, MD5 checksum or any unique value.
 
 The size of these structures varies with the --build-id linker option.
@@ -454,22 +434,20 @@ Furthermore it is possible to have multiple different payloads for the same
 function. As such an unique name per payload has to be visible to allow proper manipulation.
 
 The hypercall is part of the `xen_sysctl`. The top level structure contains
-one uint32_t to determine the sub-operations and one padding field which
+one uint32\_t to determine the sub-operations and one padding field which
 *MUST* always be zero.
 
-<pre>
-struct xen_sysctl_livepatch_op {  
-    uint32_t cmd;                   /* IN: XEN_SYSCTL_LIVEPATCH_*. */  
-    uint32_t pad;                   /* IN: Always zero. */  
-	union {  
-          ... see below ...  
-        } u;  
-};  
-
-</pre>
+    struct xen_sysctl_livepatch_op {
+        uint32_t cmd;                   /* IN: XEN_SYSCTL_LIVEPATCH_*. */
+        uint32_t pad;                   /* IN: Always zero. */
+	    union {
+              ... see below ...
+            } u;
+    };
+    
 while the rest of hypercall specific structures are part of the this structure.
 
-### Basic type: struct xen_livepatch_name
+### Basic type: struct xen\_livepatch\_name
 
 Most of the hypercalls employ an shared structure called `struct xen_livepatch_name`
 which contains:
@@ -480,26 +458,24 @@ which contains:
 
 The structure is as follow:
 
-<pre>
-/*  
- *  Uniquely identifies the payload.  Should be human readable.  
- * Includes the NUL terminator  
- */  
-#define XEN_LIVEPATCH_NAME_SIZE 128  
-struct xen_livepatch_name {  
-    XEN_GUEST_HANDLE_64(char) name;         /* IN, pointer to name. */  
-    uint16_t size;                          /* IN, size of name. May be upto   
-                                               XEN_LIVEPATCH_NAME_SIZE. */  
-    uint16_t pad[3];                        /* IN: MUST be zero. */ 
-};  
-</pre>
-
-### XEN_SYSCTL_LIVEPATCH_UPLOAD (0)
+    /*
+     *  Uniquely identifies the payload.  Should be human readable.
+     * Includes the NUL terminator
+     */
+    #define XEN_LIVEPATCH_NAME_SIZE 128
+    struct xen_livepatch_name {
+        XEN_GUEST_HANDLE_64(char) name;         /* IN, pointer to name. */
+        uint16_t size;                          /* IN, size of name. May be upto
+                                                   XEN_LIVEPATCH_NAME_SIZE. */
+        uint16_t pad[3];                        /* IN: MUST be zero. */
+    };
+
+### XEN\_SYSCTL\_LIVEPATCH\_UPLOAD (0)
 
 Upload a payload to the hypervisor. The payload is verified
 against basic checks and if there are any issues the proper return code
 will be returned. The payload is not applied at this time - that is
-controlled by *XEN_SYSCTL_LIVEPATCH_ACTION*.
+controlled by *XEN\_SYSCTL\_LIVEPATCH\_ACTION*.
 
 The caller provides:
 
@@ -512,21 +488,19 @@ payload. It can be embedded into the ELF payload at creation time
 and extracted by tools.
 
 The return value is zero if the payload was succesfully uploaded.
-Otherwise an -XEN_EXX return value is provided. Duplicate `name` are not supported.
+Otherwise an -XEN\_EXX return value is provided. Duplicate `name` are not supported.
 
 The `payload` is the ELF payload as mentioned in the `Payload format` section.
 
 The structure is as follow:
 
-<pre>
-struct xen_sysctl_livepatch_upload {  
-    xen_livepatch_name_t name;          /* IN, name of the patch. */  
-    uint64_t size;                      /* IN, size of the ELF file. */  
-    XEN_GUEST_HANDLE_64(uint8) payload; /* IN: ELF file. */  
-};  
-</pre>
+    struct xen_sysctl_livepatch_upload {
+        xen_livepatch_name_t name;          /* IN, name of the patch. */
+        uint64_t size;                      /* IN, size of the ELF file. */
+        XEN_GUEST_HANDLE_64(uint8) payload; /* IN: ELF file. */
+    };
 
-### XEN_SYSCTL_LIVEPATCH_GET (1)
+### XEN\_SYSCTL\_LIVEPATCH\_GET (1)
 
 Retrieve an status of an specific payload. This caller provides:
 
@@ -537,33 +511,29 @@ Retrieve an status of an specific payload. This caller provides:
 Upon completion the `struct xen_livepatch_status` is updated.
 
  * `status` - indicates the current status of the payload:
-   * *LIVEPATCH_STATUS_CHECKED*  (1) loaded and the ELF payload safety checks passed.
-   * *LIVEPATCH_STATUS_APPLIED* (2) loaded, checked, and applied.
+   * *LIVEPATCH\_STATUS\_CHECKED*  (1) loaded and the ELF payload safety checks passed.
+   * *LIVEPATCH\_STATUS\_APPLIED* (2) loaded, checked, and applied.
    *  No other value is possible.
- * `rc` - -XEN_EXX type errors encountered while performing the last
-   LIVEPATCH_ACTION_* operation. The normal values can be zero or -XEN_EAGAIN which
+ * `rc` - -XEN\_EXX type errors encountered while performing the last
+   LIVEPATCH\_ACTION\_\* operation. The normal values can be zero or -XEN\_EAGAIN which
    respectively mean: success or operation in progress. Other values
    imply an error occurred. If there is an error in `rc`, `status` will **NOT**
    have changed.
 
-The return value of the hypercall is zero on success and -XEN_EXX on failure.
-(Note that the `rc`` value can be different from the return value, as in
-rc=-XEN_EAGAIN and return value can be 0).
+The return value of the hypercall is zero on success and -XEN\_EXX on failure.
+(Note that the `rc` value can be different from the return value, as in
+rc=-XEN\_EAGAIN and return value can be 0).
 
 For example, supposing there is an payload:
 
-<pre>
- status: LIVEPATCH_STATUS_CHECKED
- rc: 0
-</pre>
+     status: LIVEPATCH_STATUS_CHECKED
+     rc: 0
 
-We apply an action - LIVEPATCH_ACTION_REVERT - to revert it (which won't work
+We apply an action - LIVEPATCH\_ACTION\_REVERT - to revert it (which won't work
 as we have not even applied it. Afterwards we will have:
 
-<pre>
- status: LIVEPATCH_STATUS_CHECKED
- rc: -XEN_EINVAL
-</pre>
+     status: LIVEPATCH_STATUS_CHECKED
+     rc: -XEN_EINVAL
 
 It has failed but it remains loaded.
 
@@ -571,21 +541,19 @@ This operation is synchronous and does not require preemption.
 
 The structure is as follow:
 
-<pre>
-struct xen_livepatch_status {  
-#define LIVEPATCH_STATUS_CHECKED      1  
-#define LIVEPATCH_STATUS_APPLIED      2  
-    uint32_t state;                 /* OUT: LIVEPATCH_STATE_*. */  
-    int32_t rc;                     /* OUT: 0 if no error, otherwise -XEN_EXX. */  
-};  
+    struct xen_livepatch_status {
+    #define LIVEPATCH_STATUS_CHECKED      1
+    #define LIVEPATCH_STATUS_APPLIED      2
+        uint32_t state;                 /* OUT: LIVEPATCH_STATE_*. */
+        int32_t rc;                     /* OUT: 0 if no error, otherwise -XEN_EXX. */
+    };
+    
+    struct xen_sysctl_livepatch_get {
+        xen_livepatch_name_t name;      /* IN, the name of the payload. */
+        xen_livepatch_status_t status;  /* IN/OUT: status of the payload. */
+    };
 
-struct xen_sysctl_livepatch_get {  
-    xen_livepatch_name_t name;      /* IN, the name of the payload. */  
-    xen_livepatch_status_t status;  /* IN/OUT: status of the payload. */  
-};  
-</pre>
-
-### XEN_SYSCTL_LIVEPATCH_LIST (2)
+### XEN\_SYSCTL\_LIVEPATCH\_LIST (2)
 
 Retrieve an array of abbreviated status and names of payloads that are loaded in the
 hypervisor.
@@ -606,20 +574,20 @@ The caller provides:
    structures. Caller *MUST* allocate up to `nr` of them.
  * `name` - virtual address of where to write the unique name of the payload.
    Caller *MUST* allocate up to `nr` of them. Each *MUST* be of
-   **XEN_LIVEPATCH_NAME_SIZE** size. Note that **XEN_LIVEPATCH_NAME_SIZE** includes
+   **XEN\_LIVEPATCH\_NAME\_SIZE** size. Note that **XEN\_LIVEPATCH\_NAME\_SIZE** includes
    the NUL terminator.
  * `len` - virtual address of where to write the length of each unique name
    of the payload. Caller *MUST* allocate up to `nr` of them. Each *MUST* be
-   of sizeof(uint32_t) (4 bytes).
+   of sizeof(uint32\_t) (4 bytes).
 
 If the hypercall returns an positive number, it is the number (upto `nr`
 provided to the hypercall) of the payloads returned, along with `nr` updated
 with the number of remaining payloads, `version` updated (it may be the same
 across hypercalls - if it varies the data is stale and further calls could
-fail). The `status`, `name`, and `len`' are updated at their designed index
+fail). The `status`, `name`, and `len` are updated at their designed index
 value (`idx`) with the returned value of data.
 
-If the hypercall returns -XEN_E2BIG the `nr` is too big and should be
+If the hypercall returns -XEN\_E2BIG the `nr` is too big and should be
 lowered.
 
 If the hypercall returns an zero value there are no more payloads.
@@ -634,61 +602,59 @@ data and start from scratch. It is OK for the toolstack to use the new
 The `struct xen_livepatch_status` structure contains an status of payload which includes:
 
  * `status` - indicates the current status of the payload:
-   * *LIVEPATCH_STATUS_CHECKED*  (1) loaded and the ELF payload safety checks passed.
-   * *LIVEPATCH_STATUS_APPLIED* (2) loaded, checked, and applied.
+   * *LIVEPATCH\_STATUS\_CHECKED*  (1) loaded and the ELF payload safety checks passed.
+   * *LIVEPATCH\_STATUS\_APPLIED* (2) loaded, checked, and applied.
    *  No other value is possible.
- * `rc` - -XEN_EXX type errors encountered while performing the last
-   LIVEPATCH_ACTION_* operation. The normal values can be zero or -XEN_EAGAIN which
+ * `rc` - -XEN\_EXX type errors encountered while performing the last
+   LIVEPATCH\_ACTION\_\* operation. The normal values can be zero or -XEN\_EAGAIN which
    respectively mean: success or operation in progress. Other values
    imply an error occurred. If there is an error in `rc`, `status` will **NOT**
    have changed.
 
 The structure is as follow:
 
-<pre>
-struct xen_sysctl_livepatch_list {  
-    uint32_t version;                       /* OUT: Hypervisor stamps value.
-                                               If varies between calls, we are  
-                                               getting stale data. */  
-    uint32_t idx;                           /* IN: Index into hypervisor list. */
-    uint32_t nr;                            /* IN: How many status, names, and len  
-                                               should be filled out. Can be zero to get  
-                                               amount of payloads and version.  
-                                               OUT: How many payloads left. */  
-    uint32_t pad;                           /* IN: Must be zero. */  
-    XEN_GUEST_HANDLE_64(xen_livepatch_status_t) status;  /* OUT. Must have enough  
-                                               space allocate for nr of them. */  
-    XEN_GUEST_HANDLE_64(char) id;           /* OUT: Array of names. Each member  
-                                               MUST XEN_LIVEPATCH_NAME_SIZE in size.  
-                                               Must have nr of them. */  
-    XEN_GUEST_HANDLE_64(uint32) len;        /* OUT: Array of lengths of name's.  
-                                               Must have nr of them. */  
-};  
-</pre>
-
-### XEN_SYSCTL_LIVEPATCH_ACTION (3)
+    struct xen_sysctl_livepatch_list {
+        uint32_t version;                       /* OUT: Hypervisor stamps value.
+                                                   If varies between calls, we are
+                                                   getting stale data. */
+        uint32_t idx;                           /* IN: Index into hypervisor list. */
+        uint32_t nr;                            /* IN: How many status, names, and len
+                                                   should be filled out. Can be zero to get
+                                                   amount of payloads and version.
+                                                   OUT: How many payloads left. */
+        uint32_t pad;                           /* IN: Must be zero. */
+        XEN_GUEST_HANDLE_64(xen_livepatch_status_t) status;  /* OUT. Must have enough
+                                                   space allocate for nr of them. */
+        XEN_GUEST_HANDLE_64(char) id;           /* OUT: Array of names. Each member
+                                                   MUST XEN_LIVEPATCH_NAME_SIZE in size.
+                                                   Must have nr of them. */
+        XEN_GUEST_HANDLE_64(uint32) len;        /* OUT: Array of lengths of name's.
+                                                   Must have nr of them. */
+    };
+
+### XEN\_SYSCTL\_LIVEPATCH\_ACTION (3)
 
 Perform an operation on the payload structure referenced by the `name` field.
 The operation request is asynchronous and the status should be retrieved
-by using either **XEN_SYSCTL_LIVEPATCH_GET** or **XEN_SYSCTL_LIVEPATCH_LIST** hypercall.
+by using either **XEN\_SYSCTL\_LIVEPATCH\_GET** or **XEN\_SYSCTL\_LIVEPATCH\_LIST** hypercall.
 
 The caller provides:
 
- * A 'struct xen_livepatch_name` `name` containing the unique name.
+ * A `struct xen_livepatch_name` `name` containing the unique name.
  * `cmd` the command requested:
-  * *LIVEPATCH_ACTION_UNLOAD* (1) unload the payload.
+  * *LIVEPATCH\_ACTION\_UNLOAD* (1) unload the payload.
    Any further hypercalls against the `name` will result in failure unless
-   **XEN_SYSCTL_LIVEPATCH_UPLOAD** hypercall is perfomed with same `name`.
-  * *LIVEPATCH_ACTION_REVERT* (2) revert the payload. If the operation takes
-  more time than the upper bound of time the `rc` in `xen_livepatch_status'
-  retrieved via **XEN_SYSCTL_LIVEPATCH_GET** will be -XEN_EBUSY.
-  * *LIVEPATCH_ACTION_APPLY* (3) apply the payload. If the operation takes
-  more time than the upper bound of time the `rc` in `xen_livepatch_status'
-  retrieved via **XEN_SYSCTL_LIVEPATCH_GET** will be -XEN_EBUSY.
-  * *LIVEPATCH_ACTION_REPLACE* (4) revert all applied payloads and apply this
+   **XEN\_SYSCTL\_LIVEPATCH\_UPLOAD** hypercall is perfomed with same `name`.
+  * *LIVEPATCH\_ACTION\_REVERT* (2) revert the payload. If the operation takes
+  more time than the upper bound of time the `rc` in `xen_livepatch_status`
+  retrieved via **XEN\_SYSCTL\_LIVEPATCH\_GET** will be -XEN\_EBUSY.
+  * *LIVEPATCH\_ACTION\_APPLY* (3) apply the payload. If the operation takes
+  more time than the upper bound of time the `rc` in `xen_livepatch_status`
+  retrieved via **XEN\_SYSCTL\_LIVEPATCH\_GET** will be -XEN\_EBUSY.
+  * *LIVEPATCH\_ACTION\_REPLACE* (4) revert all applied payloads and apply this
   payload. If the operation takes more time than the upper bound of time
-  the `rc` in `xen_livepatch_status' retrieved via **XEN_SYSCTL_LIVEPATCH_GET**
-  will be -XEN_EBUSY.
+  the `rc` in `xen_livepatch_status` retrieved via **XEN\_SYSCTL\_LIVEPATCH\_GET**
+  will be -XEN\_EBUSY.
  * `time` the upper bound of time (ns) the cmd should take. Zero means to use
    the hypervisor default. If within the time the operation does not succeed
    the operation would go in error state.
@@ -698,71 +664,65 @@ The return value will be zero unless the provided fields are incorrect.
 
 The structure is as follow:
 
-<pre>
-#define LIVEPATCH_ACTION_UNLOAD  1  
-#define LIVEPATCH_ACTION_REVERT  2  
-#define LIVEPATCH_ACTION_APPLY   3  
-#define LIVEPATCH_ACTION_REPLACE 4  
-struct xen_sysctl_livepatch_action {  
-    xen_livepatch_name_t name;              /* IN, name of the patch. */  
-    uint32_t cmd;                           /* IN: LIVEPATCH_ACTION_* */  
-    uint32_t time;                          /* IN: If zero then uses */
-                                            /* hypervisor default. */
-                                            /* Or upper bound of time (ns) */
-                                            /* for operation to take. */
-};  
-
-</pre>
-
-## State diagrams of LIVEPATCH_ACTION commands.
+    #define LIVEPATCH_ACTION_UNLOAD  1
+    #define LIVEPATCH_ACTION_REVERT  2
+    #define LIVEPATCH_ACTION_APPLY   3
+    #define LIVEPATCH_ACTION_REPLACE 4
+    struct xen_sysctl_livepatch_action {
+        xen_livepatch_name_t name;              /* IN, name of the patch. */
+        uint32_t cmd;                           /* IN: LIVEPATCH_ACTION_* */
+        uint32_t time;                          /* IN: If zero then uses */
+                                                /* hypervisor default. */
+                                                /* Or upper bound of time (ns) */
+                                                /* for operation to take. */
+    };
+    
+
+## State diagrams of LIVEPATCH\_ACTION commands.
 
 There is a strict ordering state of what the commands can be.
-The LIVEPATCH_ACTION prefix has been dropped to easy reading and
-does not include the LIVEPATCH_STATES:
+The LIVEPATCH\_ACTION prefix has been dropped to easy reading and
+does not include the LIVEPATCH\_STATES:
 
-<pre>
-              /->\  
-              \  /  
- UNLOAD <--- CHECK ---> REPLACE|APPLY --> REVERT --\  
-                \                                  |  
-                 \-------------------<-------------/  
-
-</pre>
-## State transition table of LIVEPATCH_ACTION commands and LIVEPATCH_STATUS.
+                  /->\
+                  \  /
+     UNLOAD <--- CHECK ---> REPLACE|APPLY --> REVERT --\
+                    \                                  |
+                     \-------------------<-------------/
+    
+## State transition table of LIVEPATCH\_ACTION commands and LIVEPATCH\_STATUS.
 
 Note that:
 
- - The CHECKED state is the starting one achieved with *XEN_SYSCTL_LIVEPATCH_UPLOAD* hypercall.
+ - The CHECKED state is the starting one achieved with *XEN\_SYSCTL\_LIVEPATCH\_UPLOAD* hypercall.
  - The REVERT operation on success will automatically move to the CHECKED state.
  - There are two STATES: CHECKED and APPLIED.
  - There are four actions (aka commands): APPLY, REPLACE, REVERT, and UNLOAD.
 
 The state transition table of valid states and action states:
 
-<pre>
-
-+---------+---------+--------------------------------+-------+--------+
-| ACTION  | Current | Result                         | Next STATE:    |
-| ACTION  | STATE   |                                |CHECKED|APPLIED |
-+---------+----------+-------------------------------+-------+--------+
-| UNLOAD  | CHECKED | Unload payload. Always works.  |       |        |
-|         |         | No next states.                |       |        |
-+---------+---------+--------------------------------+-------+--------+
-| APPLY   | CHECKED | Apply payload (success).       |       |   x    |
-+---------+---------+--------------------------------+-------+--------+
-| APPLY   | CHECKED | Apply payload (error|timeout)  |   x   |        |
-+---------+---------+--------------------------------+-------+--------+
-| REPLACE | CHECKED | Revert payloads and apply new  |       |   x    |
-|         |         | payload with success.          |       |        |
-+---------+---------+--------------------------------+-------+--------+
-| REPLACE | CHECKED | Revert payloads and apply new  |   x   |        |
-|         |         | payload with error.            |       |        |
-+---------+---------+--------------------------------+-------+--------+
-| REVERT  | APPLIED | Revert payload (success).      |   x   |        |
-+---------+---------+--------------------------------+-------+--------+
-| REVERT  | APPLIED | Revert payload (error|timeout) |       |   x    |
-+---------+---------+--------------------------------+-------+--------+
-</pre>
+    
+    +---------+---------+--------------------------------+-------+--------+
+    | ACTION  | Current | Result                         | Next STATE:    |
+    | ACTION  | STATE   |                                |CHECKED|APPLIED |
+    +---------+----------+-------------------------------+-------+--------+
+    | UNLOAD  | CHECKED | Unload payload. Always works.  |       |        |
+    |         |         | No next states.                |       |        |
+    +---------+---------+--------------------------------+-------+--------+
+    | APPLY   | CHECKED | Apply payload (success).       |       |   x    |
+    +---------+---------+--------------------------------+-------+--------+
+    | APPLY   | CHECKED | Apply payload (error|timeout)  |   x   |        |
+    +---------+---------+--------------------------------+-------+--------+
+    | REPLACE | CHECKED | Revert payloads and apply new  |       |   x    |
+    |         |         | payload with success.          |       |        |
+    +---------+---------+--------------------------------+-------+--------+
+    | REPLACE | CHECKED | Revert payloads and apply new  |   x   |        |
+    |         |         | payload with error.            |       |        |
+    +---------+---------+--------------------------------+-------+--------+
+    | REVERT  | APPLIED | Revert payload (success).      |   x   |        |
+    +---------+---------+--------------------------------+-------+--------+
+    | REVERT  | APPLIED | Revert payload (error|timeout) |       |   x    |
+    +---------+---------+--------------------------------+-------+--------+
 
 All the other state transitions are invalid.
 
@@ -770,10 +730,10 @@ All the other state transitions are invalid.
 
 The normal sequence of events is to:
 
- 1. *XEN_SYSCTL_LIVEPATCH_UPLOAD* to upload the payload. If there are errors *STOP* here.
- 2. *XEN_SYSCTL_LIVEPATCH_GET* to check the `->rc`. If *-XEN_EAGAIN* spin. If zero go to next step.
- 3. *XEN_SYSCTL_LIVEPATCH_ACTION* with *LIVEPATCH_ACTION_APPLY* to apply the patch.
- 4. *XEN_SYSCTL_LIVEPATCH_GET* to check the `->rc`. If in *-XEN_EAGAIN* spin. If zero exit with success.
+ 1. *XEN\_SYSCTL\_LIVEPATCH\_UPLOAD* to upload the payload. If there are errors *STOP* here.
+ 2. *XEN\_SYSCTL\_LIVEPATCH\_GET* to check the `->rc`. If *-XEN\_EAGAIN* spin. If zero go to next step.
+ 3. *XEN\_SYSCTL\_LIVEPATCH\_ACTION* with *LIVEPATCH\_ACTION\_APPLY* to apply the patch.
+ 4. *XEN\_SYSCTL\_LIVEPATCH\_GET* to check the `->rc`. If in *-XEN\_EAGAIN* spin. If zero exit with success.
 
 
 ## Addendum
@@ -807,18 +767,18 @@ minimize the chance of the patch not being applied due to safety
 checks failing. Safety checks such as not patching code which
 is on the stack - which can lead to corruption.
 
-#### Rendezvous code instead of stop_machine for patching
+#### Rendezvous code instead of stop\_machine for patching
 
 The hypervisor's time rendezvous code runs synchronously across all CPUs
-every second. Using the stop_machine to patch can stall the time rendezvous
+every second. Using the stop\_machine to patch can stall the time rendezvous
 code and result in NMI. As such having the patching be done at the tail
 of rendezvous code should avoid this problem.
 
 However the entrance point for that code is
-do_softirq->timer_softirq_action->time_calibration
-which ends up calling on_selected_cpus on remote CPUs.
+do\_softirq-&gt;timer\_softirq\_action-&gt;time\_calibration
+which ends up calling on\_selected\_cpus on remote CPUs.
 
-The remote CPUs receive CALL_FUNCTION_VECTOR IPI and execute the
+The remote CPUs receive CALL\_FUNCTION\_VECTOR IPI and execute the
 desired function.
 
 #### Before entering the guest code.
@@ -832,7 +792,7 @@ could be adjusted), combined with forcing all other CPUs through the
 hypervisor with IPIs, can be utilized to execute lockstep instructions
 on all CPUs.
 
-The approach is similar in concept to stop_machine and the time rendezvous
+The approach is similar in concept to stop\_machine and the time rendezvous
 but is time-bound. However the local CPU stack is much shorter and
 a lot more deterministic.
 
@@ -967,10 +927,10 @@ The implementation must also have a mechanism for (in no particular order):
    the stack, make sure the payload is built with same compiler as hypervisor).
    Specifically we want to make sure that live patching codepaths cannot be patched.
  * NOP out the code sequence if `new_size` is zero.
- * Deal with other relocation types:  R_X86_64_[8,16,32,32S], R_X86_64_PC[8,16,64]
+ * Deal with other relocation types:  R\_X86\_64\_[8,16,32,32S], R\_X86\_64\_PC[8,16,64]
    in payload file.
 
-### Handle inlined __LINE__
+### Handle inlined \_\_LINE\_\_
 
 This problem is related to hotpatch construction
 and potentially has influence on the design of the hotpatching
@@ -1030,7 +990,7 @@ Options:
 For BUG(), WARN(), etc., the line number is embedded into the bug frame, not
 the function itself.
 
-Similar considerations are true to a lesser extent for __FILE__, but it
+Similar considerations are true to a lesser extent for \_\_FILE\_\_, but it
 could be argued that file renaming should be done outside of hotpatches.
 
 ## Signature checking requirements.
@@ -1042,49 +1002,47 @@ expecting such that it can properly do signature verification.
 
 The signature is based on the all of the payloads continuously laid out
 in memory. The signature is to be appended at the end of the ELF payload
-prefixed with the string `'~Module signature appended~\n'`, followed by
+prefixed with the string '`~Module signature appended~\n`', followed by
 an signature header then followed by the signature, key identifier, and signers
 name.
 
 Specifically the signature header would be:
 
-<pre>
-#define PKEY_ALGO_DSA       0  
-#define PKEY_ALGO_RSA       1  
-
-#define PKEY_ID_PGP         0 /* OpenPGP generated key ID */  
-#define PKEY_ID_X509        1 /* X.509 arbitrary subjectKeyIdentifier */  
-
-#define HASH_ALGO_MD4          0  
-#define HASH_ALGO_MD5          1  
-#define HASH_ALGO_SHA1         2  
-#define HASH_ALGO_RIPE_MD_160  3  
-#define HASH_ALGO_SHA256       4  
-#define HASH_ALGO_SHA384       5  
-#define HASH_ALGO_SHA512       6  
-#define HASH_ALGO_SHA224       7  
-#define HASH_ALGO_RIPE_MD_128  8  
-#define HASH_ALGO_RIPE_MD_256  9  
-#define HASH_ALGO_RIPE_MD_320 10  
-#define HASH_ALGO_WP_256      11  
-#define HASH_ALGO_WP_384      12  
-#define HASH_ALGO_WP_512      13  
-#define HASH_ALGO_TGR_128     14  
-#define HASH_ALGO_TGR_160     15  
-#define HASH_ALGO_TGR_192     16  
-
-
-struct elf_payload_signature {  
-	u8	algo;		/* Public-key crypto algorithm PKEY_ALGO_*. */  
-	u8	hash;		/* Digest algorithm: HASH_ALGO_*. */  
-	u8	id_type;	/* Key identifier type PKEY_ID*. */  
-	u8	signer_len;	/* Length of signer's name */  
-	u8	key_id_len;	/* Length of key identifier */  
-	u8	__pad[3];  
-	__be32	sig_len;	/* Length of signature data */  
-};
-
-</pre>
+    #define PKEY_ALGO_DSA       0
+    #define PKEY_ALGO_RSA       1
+    
+    #define PKEY_ID_PGP         0 /* OpenPGP generated key ID */
+    #define PKEY_ID_X509        1 /* X.509 arbitrary subjectKeyIdentifier */
+    
+    #define HASH_ALGO_MD4          0
+    #define HASH_ALGO_MD5          1
+    #define HASH_ALGO_SHA1         2
+    #define HASH_ALGO_RIPE_MD_160  3
+    #define HASH_ALGO_SHA256       4
+    #define HASH_ALGO_SHA384       5
+    #define HASH_ALGO_SHA512       6
+    #define HASH_ALGO_SHA224       7
+    #define HASH_ALGO_RIPE_MD_128  8
+    #define HASH_ALGO_RIPE_MD_256  9
+    #define HASH_ALGO_RIPE_MD_320 10
+    #define HASH_ALGO_WP_256      11
+    #define HASH_ALGO_WP_384      12
+    #define HASH_ALGO_WP_512      13
+    #define HASH_ALGO_TGR_128     14
+    #define HASH_ALGO_TGR_160     15
+    #define HASH_ALGO_TGR_192     16
+    
+    
+    struct elf_payload_signature {
+	    u8	algo;		/* Public-key crypto algorithm PKEY_ALGO_*. */
+	    u8	hash;		/* Digest algorithm: HASH_ALGO_*. */
+	    u8	id_type;	/* Key identifier type PKEY_ID*. */
+	    u8	signer_len;	/* Length of signer's name */
+	    u8	key_id_len;	/* Length of key identifier */
+	    u8	__pad[3];
+	    __be32	sig_len;	/* Length of signature data */
+    };
+    
 (Note that this has been borrowed from Linux module signature code.).
 
 
@@ -1128,15 +1086,13 @@ at least five bytes if patching in trampoline.
 Depending on compiler settings, there are several functions in Xen that
 are smaller (without inter-function padding).
 
-<pre> 
-readelf -sW xen-syms | grep " FUNC " | \
-    awk '{ if ($3 < 5) print $3, $4, $5, $8 }'
-
-...
-3 FUNC LOCAL wbinvd_ipi
-3 FUNC LOCAL shadow_l1_index
-...
-</pre>
+    readelf -sW xen-syms | grep " FUNC " | \
+        awk '{ if ($3 < 5) print $3, $4, $5, $8 }'
+    
+    ...
+    3 FUNC LOCAL wbinvd_ipi
+    3 FUNC LOCAL shadow_l1_index
+    ...
 A compile-time check for, e.g., a minimum alignment of functions or a
 runtime check that verifies symbol size (+ padding to next symbols) for
 that in the hypervisor is advised.
-- 
2.13.6


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel

[PATCH v3.5 1/2] doc: correct livepatch.markdown syntax

[Andrew Cooper]

From: Juergen Gross <jgross@suse.com>

"make -C docs all" fails due to incorrect markdown syntax in
livepatch.markdown. Correct it.

Signed-off-by: Juergen Gross <jgross@suse.com>
Reviewed-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>

Misc fixes:
 * Insert real URLs
 * Drop trailing whitespace
 * Consistent alignment and indentation for code blocks and lists
 * Consistent capitalisation
 * Consistent use of `` blocks for command line arguments and function names
 * Rearrange things not to leave &lt; and &gt; in the text

No change in content.  The document now reads rather more consistently in HTML
and PDF form.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
---
 docs/misc/livepatch.markdown | 693 ++++++++++++++++++++-----------------------
 1 file changed, 320 insertions(+), 373 deletions(-)

diff --git a/docs/misc/livepatch.markdown b/docs/misc/livepatch.markdown
index 54a6b85..2bdf871 100644
--- a/docs/misc/livepatch.markdown
+++ b/docs/misc/livepatch.markdown
@@ -85,53 +85,42 @@ mechanism. See `Trampoline (e9 opcode)` section for more details.
 ### Example of trampoline and in-place splicing
 
 As example we will assume the hypervisor does not have XSA-132 (see
-*domctl/sysctl: don't leak hypervisor stack to toolstacks*
-4ff3449f0e9d175ceb9551d3f2aecb59273f639d) and we would like to binary patch
-the hypervisor with it. The original code looks as so:
+[domctl/sysctl: don't leak hypervisor stack to toolstacks](http://xenbits.xen.org/gitweb/?p=xen.git;a=commitdiff;h=4ff3449f0e9d175ceb9551d3f2aecb59273f639d))
+and we would like to binary patch the hypervisor with it. The original code
+looks as so:
 
-<pre>
-   48 89 e0                  mov    %rsp,%rax  
-   48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax  
-</pre>
+    48 89 e0                  mov    %rsp,%rax
+    48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax
 
 while the new patched hypervisor would be:
 
-<pre>
-   48 c7 45 b8 00 00 00 00   movq   $0x0,-0x48(%rbp)  
-   48 c7 45 c0 00 00 00 00   movq   $0x0,-0x40(%rbp)  
-   48 c7 45 c8 00 00 00 00   movq   $0x0,-0x38(%rbp)  
-   48 89 e0                  mov    %rsp,%rax  
-   48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax  
-</pre>
+    48 c7 45 b8 00 00 00 00   movq   $0x0,-0x48(%rbp)
+    48 c7 45 c0 00 00 00 00   movq   $0x0,-0x40(%rbp)
+    48 c7 45 c8 00 00 00 00   movq   $0x0,-0x38(%rbp)
+    48 89 e0                  mov    %rsp,%rax
+    48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax
 
-This is inside the arch_do_domctl. This new change adds 21 extra
+This is inside the arch\_do\_domctl. This new change adds 21 extra
 bytes of code which alters all the offsets inside the function. To alter
 these offsets and add the extra 21 bytes of code we might not have enough
 space in .text to squeeze this in.
 
 As such we could simplify this problem by only patching the site
-which calls arch_do_domctl:
+which calls arch\_do\_domctl:
 
-<pre>
-do_domctl:  
- e8 4b b1 05 00          callq  ffff82d08015fbb9 <arch_do_domctl>  
-</pre>
+    do_domctl:
+    e8 4b b1 05 00          callq  ffff82d08015fbb9 <arch_do_domctl>
 
 with a new address for where the new `arch_do_domctl` would be (this
 area would be allocated dynamically).
 
 Astute readers will wonder what we need to do if we were to patch `do_domctl`
 - which is not called directly by hypervisor but on behalf of the guests via
-the `compat_hypercall_table` and `hypercall_table`.
-Patching the offset in `hypercall_table` for `do_domctl:
-(ffff82d080103079 <do_domctl>:)
+the `compat_hypercall_table` and `hypercall_table`.  Patching the offset in
+`hypercall_table` for `do_domctl`:
 
-<pre>
-
- ffff82d08024d490:   79 30  
- ffff82d08024d492:   10 80 d0 82 ff ff   
-
-</pre>
+    ffff82d08024d490:   79 30
+    ffff82d08024d492:   10 80 d0 82 ff ff
 
 with the new address where the new `do_domctl` is possible. The other
 place where it is used is in `hvm_hypercall64_table` which would need
@@ -139,10 +128,11 @@ to be patched in a similar way. This would require an in-place splicing
 of the new virtual address of `arch_do_domctl`.
 
 In summary this example patched the callee of the affected function by
- * allocating memory for the new code to live in,
- * changing the virtual address in all the functions which called the old
+
+ * Allocating memory for the new code to live in,
+ * Changing the virtual address in all the functions which called the old
    code (computing the new offset, patching the callq with a new callq).
- * changing the function pointer tables with the new virtual address of
+ * Changing the function pointer tables with the new virtual address of
    the function (splicing in the new virtual address). Since this table
    resides in the .rodata section we would need to temporarily change the
    page table permissions during this part.
@@ -162,21 +152,18 @@ existing function to be patched to jump directly to the new code. This
 lessens the locations to be patched to one but it puts pressure on the
 CPU branching logic (I-cache, but it is just one unconditional jump).
 
-For this example we will assume that the hypervisor has not been compiled
-with fe2e079f642effb3d24a6e1a7096ef26e691d93e (XSA-125: *pre-fill structures
-for certain HYPERVISOR_xen_version sub-ops*) which mem-sets an structure
-in `xen_version` hypercall. This function is not called **anywhere** in
-the hypervisor (it is called by the guest) but referenced in the
-`compat_hypercall_table` and `hypercall_table` (and indirectly called
-from that). Patching the offset in `hypercall_table` for the old
-`do_xen_version` (ffff82d080112f9e <do_xen_version>)
-
-</pre>
- ffff82d08024b270 <hypercall_table>:   
- ...  
- ffff82d08024b2f8:   9e 2f 11 80 d0 82 ff ff  
+For this example we will assume that the hypervisor has not been compiled with
+XSA-125 (see
+[pre-fill structures for certain HYPERVISOR\_xen\_version sub-ops](http://xenbits.xen.org/gitweb/?p=xen.git;a=commitdiff;h=fe2e079f642effb3d24a6e1a7096ef26e691d93e))
+which mem-sets an structure in `xen_version` hypercall. This function is not
+called **anywhere** in the hypervisor (it is called by the guest) but
+referenced in the `compat_hypercall_table` and `hypercall_table` (and
+indirectly called from that). Patching the offset in `hypercall_table` for the
+old `do_xen_version`:
 
-</pre>
+    ffff82d08024b270 <hypercall_table>:
+    ...
+    ffff82d08024b2f8:   9e 2f 11 80 d0 82 ff ff
 
 with the new address where the new `do_xen_version` is possible. The other
 place where it is used is in `hvm_hypercall64_table` which would need
@@ -184,31 +171,28 @@ to be patched in a similar way. This would require an in-place splicing
 of the new virtual address of `do_xen_version`.
 
 An alternative solution would be to patch insert a trampoline in the
-old `do_xen_version' function to directly jump to the new `do_xen_version`.
+old `do_xen_version` function to directly jump to the new `do_xen_version`:
 
-<pre>
- ffff82d080112f9e do_xen_version:  
- ffff82d080112f9e:       48 c7 c0 da ff ff ff    mov    $0xffffffffffffffda,%rax  
- ffff82d080112fa5:       83 ff 09                cmp    $0x9,%edi  
- ffff82d080112fa8:       0f 87 24 05 00 00       ja     ffff82d0801134d2 ; do_xen_version+0x534  
-</pre>
+    ffff82d080112f9e do_xen_version:
+    ffff82d080112f9e:       48 c7 c0 da ff ff ff    mov    $0xffffffffffffffda,%rax
+    ffff82d080112fa5:       83 ff 09                cmp    $0x9,%edi
+    ffff82d080112fa8:       0f 87 24 05 00 00       ja     ffff82d0801134d2 ; do_xen_version+0x534
 
 with:
 
-<pre>
- ffff82d080112f9e do_xen_version:  
- ffff82d080112f9e:       e9 XX YY ZZ QQ          jmpq   [new do_xen_version]  
-</pre>
+    ffff82d080112f9e do_xen_version:
+    ffff82d080112f9e:       e9 XX YY ZZ QQ          jmpq   [new do_xen_version]
 
 which would lessen the amount of patching to just one location.
 
 In summary this example patched the affected function to jump to the
 new replacement function which required:
- * allocating memory for the new code to live in,
- * inserting trampoline with new offset in the old function to point to the
+
+ * Allocating memory for the new code to live in,
+ * Inserting trampoline with new offset in the old function to point to the
    new function.
  * Optionally we can insert in the old function a trampoline jump to an function
-   providing an BUG_ON to catch errant code.
+   providing an BUG\_ON to catch errant code.
 
 The disadvantage of this are that the unconditional jump will consume a small
 I-cache penalty. However the simplicity of the patching and higher chance
@@ -260,7 +244,7 @@ Note that every structure has padding. This is added so that the hypervisor
 can re-use those fields as it sees fit.
 
 Earlier design attempted to ineptly explain the relations of the ELF sections
-to each other without using proper ELF mechanism (sh_info, sh_link, data
+to each other without using proper ELF mechanism (sh\_info, sh\_link, data
 structures using Elf types, etc). This design will explain the structures
 and how they are used together and not dig in the ELF format - except mention
 that the section names should match the structure names.
@@ -285,60 +269,53 @@ like what the Linux kernel module loader does.
 
 The payload contains at least three sections:
 
- * `.livepatch.funcs` - which is an array of livepatch_func structures.
+ * `.livepatch.funcs` - which is an array of livepatch\_func structures.
  * `.livepatch.depends` - which is an ELF Note that describes what the payload
     depends on. **MUST** have one.
  *  `.note.gnu.build-id` - the build-id of this payload. **MUST** have one.
 
 ### .livepatch.funcs
 
-The `.livepatch.funcs` contains an array of livepatch_func structures
+The `.livepatch.funcs` contains an array of livepatch\_func structures
 which describe the functions to be patched:
 
-<pre>
-struct livepatch_func {  
-    const char *name;  
-    void *new_addr;  
-    void *old_addr;  
-    uint32_t new_size;  
-    uint32_t old_size;  
-    uint8_t version;  
-    uint8_t opaque[31];  
-};  
-</pre>
+    struct livepatch_func {
+        const char *name;
+        void *new_addr;
+        void *old_addr;
+        uint32_t new_size;
+        uint32_t old_size;
+        uint8_t version;
+        uint8_t opaque[31];
+    };
 
 The size of the structure is 64 bytes on 64-bit hypervisors. It will be
 52 on 32-bit hypervisors.
 
-* `name` is the symbol name of the old function. Only used if `old_addr` is
+ * `name` is the symbol name of the old function. Only used if `old_addr` is
    zero, otherwise will be used during dynamic linking (when hypervisor loads
    the payload).
-
-* `old_addr` is the address of the function to be patched and is filled in at
-  payload generation time if hypervisor function address is known. If unknown,
-  the value *MUST* be zero and the hypervisor will attempt to resolve the address.
-
-* `new_addr` can either have a non-zero value or be zero.
-  * If there is a non-zero value, then it is the address of the function that is
-    replacing the old function and the address is recomputed during relocation.
-    The value **MUST** be the address of the new function in the payload file.
-
-  * If the value is zero, then we NOPing out at the `old_addr` location
+ * `old_addr` is the address of the function to be patched and is filled in at
+   payload generation time if hypervisor function address is known. If unknown,
+   the value *MUST* be zero and the hypervisor will attempt to resolve the
+   address.
+ * `new_addr` can either have a non-zero value or be zero.
+   * If there is a non-zero value, then it is the address of the function that
+    is replacing the old function and the address is recomputed during
+    relocation.  The value **MUST** be the address of the new function in the
+    payload file.
+   * If the value is zero, then we NOPing out at the `old_addr` location
     `new_size` bytes.
-
-* `old_size` contains the sizes of the respective `old_addr` function in bytes.
-   The value of `old_size` **MUST** not be zero.
-
-* `new_size` depends on what `new_addr` contains:
-  * If `new_addr` contains an non-zero value, then `new_size` has the size of
-    the new function (which will replace the one at `old_addr`)  in bytes.
-  * If the value of `new_addr` is zero then `new_size` determines how many
+ * `old_size` contains the sizes of the respective `old_addr` function in
+    bytes.  The value of `old_size` **MUST** not be zero.
+ * `new_size` depends on what `new_addr` contains:
+   * If `new_addr` contains an non-zero value, then `new_size` has the size of
+    the new function (which will replace the one at `old_addr`) in bytes.
+   * If the value of `new_addr` is zero then `new_size` determines how many
     instruction bytes to NOP (up to opaque size modulo smallest platform
     instruction - 1 byte x86 and 4 bytes on ARM).
-
-* `version` is to be one.
-
-* `opaque` **MUST** be zero.
+ * `version` is to be one.
+ * `opaque` **MUST** be zero.
 
 The size of the `livepatch_func` array is determined from the ELF section
 size.
@@ -362,38 +339,35 @@ being applied and after being reverted:
 
 A simple example of what a payload file can be:
 
-<pre>
-/* MUST be in sync with hypervisor. */  
-struct livepatch_func {  
-    const char *name;  
-    void *new_addr;  
-    void *old_addr;  
-    uint32_t new_size;  
-    uint32_t old_size;  
-    uint8_t version;
-    uint8_t pad[31];  
-};  
-
-/* Our replacement function for xen_extra_version. */  
-const char *xen_hello_world(void)  
-{  
-    return "Hello World";  
-}  
-
-static unsigned char patch_this_fnc[] = "xen_extra_version";  
-
-struct livepatch_func livepatch_hello_world = {  
-    .version = LIVEPATCH_PAYLOAD_VERSION,
-    .name = patch_this_fnc,  
-    .new_addr = xen_hello_world,  
-    .old_addr = (void *)0xffff82d08013963c, /* Extracted from xen-syms. */  
-    .new_size = 13, /* To be be computed by scripts. */  
-    .old_size = 13, /* -----------""---------------  */  
-} __attribute__((__section__(".livepatch.funcs")));  
-
-</pre>
-
-Code must be compiled with -fPIC.
+    /* MUST be in sync with hypervisor. */
+    struct livepatch_func {
+        const char *name;
+        void *new_addr;
+        void *old_addr;
+        uint32_t new_size;
+        uint32_t old_size;
+        uint8_t version;
+        uint8_t pad[31];
+    };
+
+    /* Our replacement function for xen_extra_version. */
+    const char *xen_hello_world(void)
+    {
+        return "Hello World";
+    }
+
+    static unsigned char patch_this_fnc[] = "xen_extra_version";
+
+    struct livepatch_func livepatch_hello_world = {
+        .version = LIVEPATCH_PAYLOAD_VERSION,
+        .name = patch_this_fnc,
+        .new_addr = xen_hello_world,
+        .old_addr = (void *)0xffff82d08013963c, /* Extracted from xen-syms. */
+        .new_size = 13, /* To be be computed by scripts. */
+        .old_size = 13, /* -----------""---------------  */
+    } __attribute__((__section__(".livepatch.funcs")));
+
+Code must be compiled with `-fPIC`.
 
 ### .livepatch.hooks.load and .livepatch.hooks.unload
 
@@ -406,10 +380,8 @@ Each entry in this array is eight bytes.
 
 The type definition of the function are as follow:
 
-<pre>
-typedef void (*livepatch_loadcall_t)(void);  
-typedef void (*livepatch_unloadcall_t)(void);   
-</pre>
+    typedef void (*livepatch_loadcall_t)(void);
+    typedef void (*livepatch_unloadcall_t)(void);
 
 ### .livepatch.depends and .note.gnu.build-id
 
@@ -423,10 +395,10 @@ which follows the format of an ELF Note. The contents of this
 build the hypevisor and payload.
 
 If GNU linker is used then the name is `GNU` and the description
-is a NT_GNU_BUILD_ID type ID. The description can be an SHA1
+is a NT\_GNU\_BUILD\_ID type ID. The description can be an SHA1
 checksum, MD5 checksum or any unique value.
 
-The size of these structures varies with the --build-id linker option.
+The size of these structures varies with the `--build-id` linker option.
 
 ## Hypercalls
 
@@ -454,22 +426,20 @@ Furthermore it is possible to have multiple different payloads for the same
 function. As such an unique name per payload has to be visible to allow proper manipulation.
 
 The hypercall is part of the `xen_sysctl`. The top level structure contains
-one uint32_t to determine the sub-operations and one padding field which
+one uint32\_t to determine the sub-operations and one padding field which
 *MUST* always be zero.
 
-<pre>
-struct xen_sysctl_livepatch_op {  
-    uint32_t cmd;                   /* IN: XEN_SYSCTL_LIVEPATCH_*. */  
-    uint32_t pad;                   /* IN: Always zero. */  
-	union {  
-          ... see below ...  
-        } u;  
-};  
+    struct xen_sysctl_livepatch_op {
+        uint32_t cmd;                   /* IN: XEN_SYSCTL_LIVEPATCH_*. */
+        uint32_t pad;                   /* IN: Always zero. */
+	    union {
+              ... see below ...
+            } u;
+    };
 
-</pre>
 while the rest of hypercall specific structures are part of the this structure.
 
-### Basic type: struct xen_livepatch_name
+### Basic type: struct xen\_livepatch\_name
 
 Most of the hypercalls employ an shared structure called `struct xen_livepatch_name`
 which contains:
@@ -480,26 +450,24 @@ which contains:
 
 The structure is as follow:
 
-<pre>
-/*  
- *  Uniquely identifies the payload.  Should be human readable.  
- * Includes the NUL terminator  
- */  
-#define XEN_LIVEPATCH_NAME_SIZE 128  
-struct xen_livepatch_name {  
-    XEN_GUEST_HANDLE_64(char) name;         /* IN, pointer to name. */  
-    uint16_t size;                          /* IN, size of name. May be upto   
-                                               XEN_LIVEPATCH_NAME_SIZE. */  
-    uint16_t pad[3];                        /* IN: MUST be zero. */ 
-};  
-</pre>
-
-### XEN_SYSCTL_LIVEPATCH_UPLOAD (0)
+    /*
+     *  Uniquely identifies the payload.  Should be human readable.
+     * Includes the NUL terminator
+     */
+    #define XEN_LIVEPATCH_NAME_SIZE 128
+    struct xen_livepatch_name {
+        XEN_GUEST_HANDLE_64(char) name;         /* IN, pointer to name. */
+        uint16_t size;                          /* IN, size of name. May be upto
+                                                   XEN_LIVEPATCH_NAME_SIZE. */
+        uint16_t pad[3];                        /* IN: MUST be zero. */
+    };
+
+### XEN\_SYSCTL\_LIVEPATCH\_UPLOAD (0)
 
 Upload a payload to the hypervisor. The payload is verified
 against basic checks and if there are any issues the proper return code
 will be returned. The payload is not applied at this time - that is
-controlled by *XEN_SYSCTL_LIVEPATCH_ACTION*.
+controlled by *XEN\_SYSCTL\_LIVEPATCH\_ACTION*.
 
 The caller provides:
 
@@ -512,21 +480,19 @@ payload. It can be embedded into the ELF payload at creation time
 and extracted by tools.
 
 The return value is zero if the payload was succesfully uploaded.
-Otherwise an -XEN_EXX return value is provided. Duplicate `name` are not supported.
+Otherwise an -XEN\_EXX return value is provided. Duplicate `name` are not supported.
 
 The `payload` is the ELF payload as mentioned in the `Payload format` section.
 
 The structure is as follow:
 
-<pre>
-struct xen_sysctl_livepatch_upload {  
-    xen_livepatch_name_t name;          /* IN, name of the patch. */  
-    uint64_t size;                      /* IN, size of the ELF file. */  
-    XEN_GUEST_HANDLE_64(uint8) payload; /* IN: ELF file. */  
-};  
-</pre>
+    struct xen_sysctl_livepatch_upload {
+        xen_livepatch_name_t name;          /* IN, name of the patch. */
+        uint64_t size;                      /* IN, size of the ELF file. */
+        XEN_GUEST_HANDLE_64(uint8) payload; /* IN: ELF file. */
+    };
 
-### XEN_SYSCTL_LIVEPATCH_GET (1)
+### XEN\_SYSCTL\_LIVEPATCH\_GET (1)
 
 Retrieve an status of an specific payload. This caller provides:
 
@@ -537,33 +503,29 @@ Retrieve an status of an specific payload. This caller provides:
 Upon completion the `struct xen_livepatch_status` is updated.
 
  * `status` - indicates the current status of the payload:
-   * *LIVEPATCH_STATUS_CHECKED*  (1) loaded and the ELF payload safety checks passed.
-   * *LIVEPATCH_STATUS_APPLIED* (2) loaded, checked, and applied.
+   * *LIVEPATCH\_STATUS\_CHECKED* (1) loaded and the ELF payload safety checks passed.
+   * *LIVEPATCH\_STATUS\_APPLIED* (2) loaded, checked, and applied.
    *  No other value is possible.
- * `rc` - -XEN_EXX type errors encountered while performing the last
-   LIVEPATCH_ACTION_* operation. The normal values can be zero or -XEN_EAGAIN which
+ * `rc` - -XEN\_EXX type errors encountered while performing the last
+   LIVEPATCH\_ACTION\_\* operation. The normal values can be zero or -XEN\_EAGAIN which
    respectively mean: success or operation in progress. Other values
    imply an error occurred. If there is an error in `rc`, `status` will **NOT**
    have changed.
 
-The return value of the hypercall is zero on success and -XEN_EXX on failure.
-(Note that the `rc`` value can be different from the return value, as in
-rc=-XEN_EAGAIN and return value can be 0).
+The return value of the hypercall is zero on success and -XEN\_EXX on failure.
+(Note that the `rc` value can be different from the return value, as in
+rc=-XEN\_EAGAIN and return value can be 0).
 
 For example, supposing there is an payload:
 
-<pre>
- status: LIVEPATCH_STATUS_CHECKED
- rc: 0
-</pre>
+    status: LIVEPATCH_STATUS_CHECKED
+    rc: 0
 
-We apply an action - LIVEPATCH_ACTION_REVERT - to revert it (which won't work
+We apply an action - LIVEPATCH\_ACTION\_REVERT - to revert it (which won't work
 as we have not even applied it. Afterwards we will have:
 
-<pre>
- status: LIVEPATCH_STATUS_CHECKED
- rc: -XEN_EINVAL
-</pre>
+    status: LIVEPATCH_STATUS_CHECKED
+    rc: -XEN_EINVAL
 
 It has failed but it remains loaded.
 
@@ -571,21 +533,19 @@ This operation is synchronous and does not require preemption.
 
 The structure is as follow:
 
-<pre>
-struct xen_livepatch_status {  
-#define LIVEPATCH_STATUS_CHECKED      1  
-#define LIVEPATCH_STATUS_APPLIED      2  
-    uint32_t state;                 /* OUT: LIVEPATCH_STATE_*. */  
-    int32_t rc;                     /* OUT: 0 if no error, otherwise -XEN_EXX. */  
-};  
+    struct xen_livepatch_status {
+    #define LIVEPATCH_STATUS_CHECKED      1
+    #define LIVEPATCH_STATUS_APPLIED      2
+        uint32_t state;                 /* OUT: LIVEPATCH_STATE_*. */
+        int32_t rc;                     /* OUT: 0 if no error, otherwise -XEN_EXX. */
+    };
 
-struct xen_sysctl_livepatch_get {  
-    xen_livepatch_name_t name;      /* IN, the name of the payload. */  
-    xen_livepatch_status_t status;  /* IN/OUT: status of the payload. */  
-};  
-</pre>
+    struct xen_sysctl_livepatch_get {
+        xen_livepatch_name_t name;      /* IN, the name of the payload. */
+        xen_livepatch_status_t status;  /* IN/OUT: status of the payload. */
+    };
 
-### XEN_SYSCTL_LIVEPATCH_LIST (2)
+### XEN\_SYSCTL\_LIVEPATCH\_LIST (2)
 
 Retrieve an array of abbreviated status and names of payloads that are loaded in the
 hypervisor.
@@ -594,32 +554,32 @@ The caller provides:
 
  * `version`. Version of the payload. Caller should re-use the field provided by
     the hypervisor. If the value differs the data is stale.
- * `idx` index iterator. The index into the hypervisor's payload count. It is
+ * `idx` Index iterator. The index into the hypervisor's payload count. It is
     recommended that on first invocation zero be used so that `nr` (which the
     hypervisor will update with the remaining payload count) be provided.
     Also the hypervisor will provide `version` with the most current value.
- * `nr` the max number of entries to populate. Can be zero which will result
+ * `nr` The max number of entries to populate. Can be zero which will result
     in the hypercall being a probing one and return the number of payloads
     (and update the `version`).
  * `pad` - *MUST* be zero.
- * `status` virtual address of where to write `struct xen_livepatch_status`
+ * `status` Virtual address of where to write `struct xen_livepatch_status`
    structures. Caller *MUST* allocate up to `nr` of them.
- * `name` - virtual address of where to write the unique name of the payload.
+ * `name` - Virtual address of where to write the unique name of the payload.
    Caller *MUST* allocate up to `nr` of them. Each *MUST* be of
-   **XEN_LIVEPATCH_NAME_SIZE** size. Note that **XEN_LIVEPATCH_NAME_SIZE** includes
+   **XEN\_LIVEPATCH\_NAME\_SIZE** size. Note that **XEN\_LIVEPATCH\_NAME\_SIZE** includes
    the NUL terminator.
- * `len` - virtual address of where to write the length of each unique name
+ * `len` - Virtual address of where to write the length of each unique name
    of the payload. Caller *MUST* allocate up to `nr` of them. Each *MUST* be
-   of sizeof(uint32_t) (4 bytes).
+   of sizeof(uint32\_t) (4 bytes).
 
 If the hypercall returns an positive number, it is the number (upto `nr`
 provided to the hypercall) of the payloads returned, along with `nr` updated
 with the number of remaining payloads, `version` updated (it may be the same
 across hypercalls - if it varies the data is stale and further calls could
-fail). The `status`, `name`, and `len`' are updated at their designed index
+fail). The `status`, `name`, and `len` are updated at their designed index
 value (`idx`) with the returned value of data.
 
-If the hypercall returns -XEN_E2BIG the `nr` is too big and should be
+If the hypercall returns -XEN\_E2BIG the `nr` is too big and should be
 lowered.
 
 If the hypercall returns an zero value there are no more payloads.
@@ -634,62 +594,60 @@ data and start from scratch. It is OK for the toolstack to use the new
 The `struct xen_livepatch_status` structure contains an status of payload which includes:
 
  * `status` - indicates the current status of the payload:
-   * *LIVEPATCH_STATUS_CHECKED*  (1) loaded and the ELF payload safety checks passed.
-   * *LIVEPATCH_STATUS_APPLIED* (2) loaded, checked, and applied.
+   * *LIVEPATCH\_STATUS\_CHECKED* (1) loaded and the ELF payload safety checks passed.
+   * *LIVEPATCH\_STATUS\_APPLIED* (2) loaded, checked, and applied.
    *  No other value is possible.
- * `rc` - -XEN_EXX type errors encountered while performing the last
-   LIVEPATCH_ACTION_* operation. The normal values can be zero or -XEN_EAGAIN which
+ * `rc` - -XEN\_EXX type errors encountered while performing the last
+   LIVEPATCH\_ACTION\_\* operation. The normal values can be zero or -XEN\_EAGAIN which
    respectively mean: success or operation in progress. Other values
    imply an error occurred. If there is an error in `rc`, `status` will **NOT**
    have changed.
 
 The structure is as follow:
 
-<pre>
-struct xen_sysctl_livepatch_list {  
-    uint32_t version;                       /* OUT: Hypervisor stamps value.
-                                               If varies between calls, we are  
-                                               getting stale data. */  
-    uint32_t idx;                           /* IN: Index into hypervisor list. */
-    uint32_t nr;                            /* IN: How many status, names, and len  
-                                               should be filled out. Can be zero to get  
-                                               amount of payloads and version.  
-                                               OUT: How many payloads left. */  
-    uint32_t pad;                           /* IN: Must be zero. */  
-    XEN_GUEST_HANDLE_64(xen_livepatch_status_t) status;  /* OUT. Must have enough  
-                                               space allocate for nr of them. */  
-    XEN_GUEST_HANDLE_64(char) id;           /* OUT: Array of names. Each member  
-                                               MUST XEN_LIVEPATCH_NAME_SIZE in size.  
-                                               Must have nr of them. */  
-    XEN_GUEST_HANDLE_64(uint32) len;        /* OUT: Array of lengths of name's.  
-                                               Must have nr of them. */  
-};  
-</pre>
-
-### XEN_SYSCTL_LIVEPATCH_ACTION (3)
+    struct xen_sysctl_livepatch_list {
+        uint32_t version;                       /* OUT: Hypervisor stamps value.
+                                                   If varies between calls, we are
+                                                   getting stale data. */
+        uint32_t idx;                           /* IN: Index into hypervisor list. */
+        uint32_t nr;                            /* IN: How many status, names, and len
+                                                   should be filled out. Can be zero to get
+                                                   amount of payloads and version.
+                                                   OUT: How many payloads left. */
+        uint32_t pad;                           /* IN: Must be zero. */
+        XEN_GUEST_HANDLE_64(xen_livepatch_status_t) status;  /* OUT. Must have enough
+                                                   space allocate for nr of them. */
+        XEN_GUEST_HANDLE_64(char) id;           /* OUT: Array of names. Each member
+                                                   MUST XEN_LIVEPATCH_NAME_SIZE in size.
+                                                   Must have nr of them. */
+        XEN_GUEST_HANDLE_64(uint32) len;        /* OUT: Array of lengths of name's.
+                                                   Must have nr of them. */
+    };
+
+### XEN\_SYSCTL\_LIVEPATCH\_ACTION (3)
 
 Perform an operation on the payload structure referenced by the `name` field.
 The operation request is asynchronous and the status should be retrieved
-by using either **XEN_SYSCTL_LIVEPATCH_GET** or **XEN_SYSCTL_LIVEPATCH_LIST** hypercall.
+by using either **XEN\_SYSCTL\_LIVEPATCH\_GET** or **XEN\_SYSCTL\_LIVEPATCH\_LIST** hypercall.
 
 The caller provides:
 
- * A 'struct xen_livepatch_name` `name` containing the unique name.
- * `cmd` the command requested:
-  * *LIVEPATCH_ACTION_UNLOAD* (1) unload the payload.
+ * A `struct xen_livepatch_name` `name` containing the unique name.
+ * `cmd` The command requested:
+  * *LIVEPATCH\_ACTION\_UNLOAD* (1) Unload the payload.
    Any further hypercalls against the `name` will result in failure unless
-   **XEN_SYSCTL_LIVEPATCH_UPLOAD** hypercall is perfomed with same `name`.
-  * *LIVEPATCH_ACTION_REVERT* (2) revert the payload. If the operation takes
-  more time than the upper bound of time the `rc` in `xen_livepatch_status'
-  retrieved via **XEN_SYSCTL_LIVEPATCH_GET** will be -XEN_EBUSY.
-  * *LIVEPATCH_ACTION_APPLY* (3) apply the payload. If the operation takes
-  more time than the upper bound of time the `rc` in `xen_livepatch_status'
-  retrieved via **XEN_SYSCTL_LIVEPATCH_GET** will be -XEN_EBUSY.
-  * *LIVEPATCH_ACTION_REPLACE* (4) revert all applied payloads and apply this
+   **XEN\_SYSCTL\_LIVEPATCH\_UPLOAD** hypercall is perfomed with same `name`.
+  * *LIVEPATCH\_ACTION\_REVERT* (2) Revert the payload. If the operation takes
+  more time than the upper bound of time the `rc` in `xen_livepatch_status`
+  retrieved via **XEN\_SYSCTL\_LIVEPATCH\_GET** will be -XEN\_EBUSY.
+  * *LIVEPATCH\_ACTION\_APPLY* (3) Apply the payload. If the operation takes
+  more time than the upper bound of time the `rc` in `xen_livepatch_status`
+  retrieved via **XEN\_SYSCTL\_LIVEPATCH\_GET** will be -XEN\_EBUSY.
+  * *LIVEPATCH\_ACTION\_REPLACE* (4) Revert all applied payloads and apply this
   payload. If the operation takes more time than the upper bound of time
-  the `rc` in `xen_livepatch_status' retrieved via **XEN_SYSCTL_LIVEPATCH_GET**
-  will be -XEN_EBUSY.
- * `time` the upper bound of time (ns) the cmd should take. Zero means to use
+  the `rc` in `xen_livepatch_status` retrieved via **XEN\_SYSCTL\_LIVEPATCH\_GET**
+  will be -XEN\_EBUSY.
+ * `time` The upper bound of time (ns) the cmd should take. Zero means to use
    the hypervisor default. If within the time the operation does not succeed
    the operation would go in error state.
  * `pad` - *MUST* be zero.
@@ -698,71 +656,64 @@ The return value will be zero unless the provided fields are incorrect.
 
 The structure is as follow:
 
-<pre>
-#define LIVEPATCH_ACTION_UNLOAD  1  
-#define LIVEPATCH_ACTION_REVERT  2  
-#define LIVEPATCH_ACTION_APPLY   3  
-#define LIVEPATCH_ACTION_REPLACE 4  
-struct xen_sysctl_livepatch_action {  
-    xen_livepatch_name_t name;              /* IN, name of the patch. */  
-    uint32_t cmd;                           /* IN: LIVEPATCH_ACTION_* */  
-    uint32_t time;                          /* IN: If zero then uses */
-                                            /* hypervisor default. */
-                                            /* Or upper bound of time (ns) */
-                                            /* for operation to take. */
-};  
+    #define LIVEPATCH_ACTION_UNLOAD  1
+    #define LIVEPATCH_ACTION_REVERT  2
+    #define LIVEPATCH_ACTION_APPLY   3
+    #define LIVEPATCH_ACTION_REPLACE 4
+    struct xen_sysctl_livepatch_action {
+        xen_livepatch_name_t name;              /* IN, name of the patch. */
+        uint32_t cmd;                           /* IN: LIVEPATCH_ACTION_* */
+        uint32_t time;                          /* IN: If zero then uses */
+                                                /* hypervisor default. */
+                                                /* Or upper bound of time (ns) */
+                                                /* for operation to take. */
+    };
 
-</pre>
 
-## State diagrams of LIVEPATCH_ACTION commands.
+## State diagrams of LIVEPATCH\_ACTION commands.
 
 There is a strict ordering state of what the commands can be.
-The LIVEPATCH_ACTION prefix has been dropped to easy reading and
-does not include the LIVEPATCH_STATES:
+The LIVEPATCH\_ACTION prefix has been dropped to easy reading and
+does not include the LIVEPATCH\_STATES:
 
-<pre>
-              /->\  
-              \  /  
- UNLOAD <--- CHECK ---> REPLACE|APPLY --> REVERT --\  
-                \                                  |  
-                 \-------------------<-------------/  
+                 /->\
+                 \  /
+    UNLOAD <--- CHECK ---> REPLACE|APPLY --> REVERT --\
+                   \                                  |
+                    \-------------------<-------------/
 
-</pre>
-## State transition table of LIVEPATCH_ACTION commands and LIVEPATCH_STATUS.
+## State transition table of LIVEPATCH\_ACTION commands and LIVEPATCH\_STATUS.
 
 Note that:
 
- - The CHECKED state is the starting one achieved with *XEN_SYSCTL_LIVEPATCH_UPLOAD* hypercall.
+ - The CHECKED state is the starting one achieved with *XEN\_SYSCTL\_LIVEPATCH\_UPLOAD* hypercall.
  - The REVERT operation on success will automatically move to the CHECKED state.
  - There are two STATES: CHECKED and APPLIED.
  - There are four actions (aka commands): APPLY, REPLACE, REVERT, and UNLOAD.
 
 The state transition table of valid states and action states:
 
-<pre>
-
-+---------+---------+--------------------------------+-------+--------+
-| ACTION  | Current | Result                         | Next STATE:    |
-| ACTION  | STATE   |                                |CHECKED|APPLIED |
-+---------+----------+-------------------------------+-------+--------+
-| UNLOAD  | CHECKED | Unload payload. Always works.  |       |        |
-|         |         | No next states.                |       |        |
-+---------+---------+--------------------------------+-------+--------+
-| APPLY   | CHECKED | Apply payload (success).       |       |   x    |
-+---------+---------+--------------------------------+-------+--------+
-| APPLY   | CHECKED | Apply payload (error|timeout)  |   x   |        |
-+---------+---------+--------------------------------+-------+--------+
-| REPLACE | CHECKED | Revert payloads and apply new  |       |   x    |
-|         |         | payload with success.          |       |        |
-+---------+---------+--------------------------------+-------+--------+
-| REPLACE | CHECKED | Revert payloads and apply new  |   x   |        |
-|         |         | payload with error.            |       |        |
-+---------+---------+--------------------------------+-------+--------+
-| REVERT  | APPLIED | Revert payload (success).      |   x   |        |
-+---------+---------+--------------------------------+-------+--------+
-| REVERT  | APPLIED | Revert payload (error|timeout) |       |   x    |
-+---------+---------+--------------------------------+-------+--------+
-</pre>
+    +---------+---------+--------------------------------+-------+--------+
+    | ACTION  | Current | Result                         |   Next STATE:  |
+    | ACTION  | STATE   |                                |CHECKED|APPLIED |
+    +---------+----------+-------------------------------+-------+--------+
+    | UNLOAD  | CHECKED | Unload payload. Always works.  |       |        |
+    |         |         | No next states.                |       |        |
+    +---------+---------+--------------------------------+-------+--------+
+    | APPLY   | CHECKED | Apply payload (success).       |       |   x    |
+    +---------+---------+--------------------------------+-------+--------+
+    | APPLY   | CHECKED | Apply payload (error|timeout)  |   x   |        |
+    +---------+---------+--------------------------------+-------+--------+
+    | REPLACE | CHECKED | Revert payloads and apply new  |       |   x    |
+    |         |         | payload with success.          |       |        |
+    +---------+---------+--------------------------------+-------+--------+
+    | REPLACE | CHECKED | Revert payloads and apply new  |   x   |        |
+    |         |         | payload with error.            |       |        |
+    +---------+---------+--------------------------------+-------+--------+
+    | REVERT  | APPLIED | Revert payload (success).      |   x   |        |
+    +---------+---------+--------------------------------+-------+--------+
+    | REVERT  | APPLIED | Revert payload (error|timeout) |       |   x    |
+    +---------+---------+--------------------------------+-------+--------+
 
 All the other state transitions are invalid.
 
@@ -770,10 +721,10 @@ All the other state transitions are invalid.
 
 The normal sequence of events is to:
 
- 1. *XEN_SYSCTL_LIVEPATCH_UPLOAD* to upload the payload. If there are errors *STOP* here.
- 2. *XEN_SYSCTL_LIVEPATCH_GET* to check the `->rc`. If *-XEN_EAGAIN* spin. If zero go to next step.
- 3. *XEN_SYSCTL_LIVEPATCH_ACTION* with *LIVEPATCH_ACTION_APPLY* to apply the patch.
- 4. *XEN_SYSCTL_LIVEPATCH_GET* to check the `->rc`. If in *-XEN_EAGAIN* spin. If zero exit with success.
+ 1. *XEN\_SYSCTL\_LIVEPATCH\_UPLOAD* to upload the payload. If there are errors *STOP* here.
+ 2. *XEN\_SYSCTL\_LIVEPATCH\_GET* to check the `->rc`. If *-XEN\_EAGAIN* spin. If zero go to next step.
+ 3. *XEN\_SYSCTL\_LIVEPATCH\_ACTION* with *LIVEPATCH\_ACTION\_APPLY* to apply the patch.
+ 4. *XEN\_SYSCTL\_LIVEPATCH\_GET* to check the `->rc`. If in *-XEN\_EAGAIN* spin. If zero exit with success.
 
 
 ## Addendum
@@ -807,18 +758,18 @@ minimize the chance of the patch not being applied due to safety
 checks failing. Safety checks such as not patching code which
 is on the stack - which can lead to corruption.
 
-#### Rendezvous code instead of stop_machine for patching
+#### Rendezvous code instead of stop\_machine for patching
 
 The hypervisor's time rendezvous code runs synchronously across all CPUs
-every second. Using the stop_machine to patch can stall the time rendezvous
+every second. Using the `stop_machine` to patch can stall the time rendezvous
 code and result in NMI. As such having the patching be done at the tail
 of rendezvous code should avoid this problem.
 
-However the entrance point for that code is
-do_softirq->timer_softirq_action->time_calibration
-which ends up calling on_selected_cpus on remote CPUs.
+However the entrance point for that code is `do_softirq ->
+timer_softirq_action -> time_calibration` which ends up calling
+`on_selected_cpus` on remote CPUs.
 
-The remote CPUs receive CALL_FUNCTION_VECTOR IPI and execute the
+The remote CPUs receive CALL\_FUNCTION\_VECTOR IPI and execute the
 desired function.
 
 #### Before entering the guest code.
@@ -832,16 +783,16 @@ could be adjusted), combined with forcing all other CPUs through the
 hypervisor with IPIs, can be utilized to execute lockstep instructions
 on all CPUs.
 
-The approach is similar in concept to stop_machine and the time rendezvous
+The approach is similar in concept to `stop_machine` and the time rendezvous
 but is time-bound. However the local CPU stack is much shorter and
 a lot more deterministic.
 
-This is implemented in the Xen Project hypervisor.
+This is implemented in the Xen hypervisor.
 
 ### Compiling the hypervisor code
 
 Hotpatch generation often requires support for compiling the target
-with -ffunction-sections / -fdata-sections.  Changes would have to
+with `-ffunction-sections` / `-fdata-sections`.  Changes would have to
 be done to the linker scripts to support this.
 
 ### Generation of Live Patch ELF payloads
@@ -866,7 +817,7 @@ and reorder it afterwards.
 As found almost every patch (XSA) to a non-trivial function requires
 additional entries in the exception table and/or the bug frames.
 
-This is implemented in the Xen Project hypervisor.
+This is implemented in the Xen hypervisor.
 
 ### .rodata sections
 
@@ -882,18 +833,18 @@ To guard against that we must be prepared to do patching similar to
 trampoline patching or in-line depending on the flavour. If we can
 do in-line patching we would need to:
 
- * alter `.rodata` to be writeable.
- * inline patch.
- * alter `.rodata` to be read-only.
+ * Alter `.rodata` to be writeable.
+ * Inline patch.
+ * Alter `.rodata` to be read-only.
 
 If are doing trampoline patching we would need to:
 
- * allocate a new memory location for the string.
- * all locations which use this string will have to be updated to use the
+ * Allocate a new memory location for the string.
+ * All locations which use this string will have to be updated to use the
    offset to the string.
- * mark the region RO when we are done.
+ * Mark the region RO when we are done.
 
-The trampoline patching is implemented in the Xen Project hypervisor.
+The trampoline patching is implemented in the Xen hypervisor.
 
 ### .bss and .data sections.
 
@@ -908,7 +859,7 @@ Patching in the new function will end up also patching in the new .rodata
 section and the new function will reference the new string in the new
 .rodata section.
 
-This is implemented in the Xen Project hypervisor.
+This is implemented in the Xen hypervisor.
 
 ### Security
 
@@ -941,7 +892,7 @@ The old code allows much more flexibility and an additional guard,
 but is more complex to implement.
 
 The second option which requires an build-id of the hypervisor
-is implemented in the Xen Project hypervisor.
+is implemented in the Xen hypervisor.
 
 Specifically each payload has two build-id ELF notes:
  * The build-id of the payload itself (generated via --build-id).
@@ -967,10 +918,10 @@ The implementation must also have a mechanism for (in no particular order):
    the stack, make sure the payload is built with same compiler as hypervisor).
    Specifically we want to make sure that live patching codepaths cannot be patched.
  * NOP out the code sequence if `new_size` is zero.
- * Deal with other relocation types:  R_X86_64_[8,16,32,32S], R_X86_64_PC[8,16,64]
+ * Deal with other relocation types:  R\_X86\_64\_[8,16,32,32S], R\_X86\_64\_PC[8,16,64]
    in payload file.
 
-### Handle inlined __LINE__
+### Handle inlined \_\_LINE\_\_
 
 This problem is related to hotpatch construction
 and potentially has influence on the design of the hotpatching
@@ -1030,7 +981,7 @@ Options:
 For BUG(), WARN(), etc., the line number is embedded into the bug frame, not
 the function itself.
 
-Similar considerations are true to a lesser extent for __FILE__, but it
+Similar considerations are true to a lesser extent for \_\_FILE\_\_, but it
 could be argued that file renaming should be done outside of hotpatches.
 
 ## Signature checking requirements.
@@ -1042,49 +993,46 @@ expecting such that it can properly do signature verification.
 
 The signature is based on the all of the payloads continuously laid out
 in memory. The signature is to be appended at the end of the ELF payload
-prefixed with the string `'~Module signature appended~\n'`, followed by
+prefixed with the string '`~Module signature appended~\n`', followed by
 an signature header then followed by the signature, key identifier, and signers
 name.
 
 Specifically the signature header would be:
 
-<pre>
-#define PKEY_ALGO_DSA       0  
-#define PKEY_ALGO_RSA       1  
-
-#define PKEY_ID_PGP         0 /* OpenPGP generated key ID */  
-#define PKEY_ID_X509        1 /* X.509 arbitrary subjectKeyIdentifier */  
-
-#define HASH_ALGO_MD4          0  
-#define HASH_ALGO_MD5          1  
-#define HASH_ALGO_SHA1         2  
-#define HASH_ALGO_RIPE_MD_160  3  
-#define HASH_ALGO_SHA256       4  
-#define HASH_ALGO_SHA384       5  
-#define HASH_ALGO_SHA512       6  
-#define HASH_ALGO_SHA224       7  
-#define HASH_ALGO_RIPE_MD_128  8  
-#define HASH_ALGO_RIPE_MD_256  9  
-#define HASH_ALGO_RIPE_MD_320 10  
-#define HASH_ALGO_WP_256      11  
-#define HASH_ALGO_WP_384      12  
-#define HASH_ALGO_WP_512      13  
-#define HASH_ALGO_TGR_128     14  
-#define HASH_ALGO_TGR_160     15  
-#define HASH_ALGO_TGR_192     16  
-
-
-struct elf_payload_signature {  
-	u8	algo;		/* Public-key crypto algorithm PKEY_ALGO_*. */  
-	u8	hash;		/* Digest algorithm: HASH_ALGO_*. */  
-	u8	id_type;	/* Key identifier type PKEY_ID*. */  
-	u8	signer_len;	/* Length of signer's name */  
-	u8	key_id_len;	/* Length of key identifier */  
-	u8	__pad[3];  
-	__be32	sig_len;	/* Length of signature data */  
-};
-
-</pre>
+    #define PKEY_ALGO_DSA       0
+    #define PKEY_ALGO_RSA       1
+
+    #define PKEY_ID_PGP         0 /* OpenPGP generated key ID */
+    #define PKEY_ID_X509        1 /* X.509 arbitrary subjectKeyIdentifier */
+
+    #define HASH_ALGO_MD4          0
+    #define HASH_ALGO_MD5          1
+    #define HASH_ALGO_SHA1         2
+    #define HASH_ALGO_RIPE_MD_160  3
+    #define HASH_ALGO_SHA256       4
+    #define HASH_ALGO_SHA384       5
+    #define HASH_ALGO_SHA512       6
+    #define HASH_ALGO_SHA224       7
+    #define HASH_ALGO_RIPE_MD_128  8
+    #define HASH_ALGO_RIPE_MD_256  9
+    #define HASH_ALGO_RIPE_MD_320 10
+    #define HASH_ALGO_WP_256      11
+    #define HASH_ALGO_WP_384      12
+    #define HASH_ALGO_WP_512      13
+    #define HASH_ALGO_TGR_128     14
+    #define HASH_ALGO_TGR_160     15
+    #define HASH_ALGO_TGR_192     16
+
+    struct elf_payload_signature {
+	    u8	algo;		/* Public-key crypto algorithm PKEY_ALGO_*. */
+	    u8	hash;		/* Digest algorithm: HASH_ALGO_*. */
+	    u8	id_type;	/* Key identifier type PKEY_ID*. */
+	    u8	signer_len;	/* Length of signer's name */
+	    u8	key_id_len;	/* Length of key identifier */
+	    u8	__pad[3];
+	    __be32	sig_len;	/* Length of signature data */
+    };
+
 (Note that this has been borrowed from Linux module signature code.).
 
 
@@ -1128,15 +1076,14 @@ at least five bytes if patching in trampoline.
 Depending on compiler settings, there are several functions in Xen that
 are smaller (without inter-function padding).
 
-<pre> 
-readelf -sW xen-syms | grep " FUNC " | \
-    awk '{ if ($3 < 5) print $3, $4, $5, $8 }'
+    readelf -sW xen-syms | grep " FUNC " | \
+        awk '{ if ($3 < 5) print $3, $4, $5, $8 }'
+
+    ...
+    3 FUNC LOCAL wbinvd_ipi
+    3 FUNC LOCAL shadow_l1_index
+    ...
 
-...
-3 FUNC LOCAL wbinvd_ipi
-3 FUNC LOCAL shadow_l1_index
-...
-</pre>
 A compile-time check for, e.g., a minimum alignment of functions or a
 runtime check that verifies symbol size (+ padding to next symbols) for
 that in the hypervisor is advised.
-- 
2.1.4


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel

Re: [PATCH for-4.11 v3.5 1/2] doc: correct livepatch.markdown syntax

[Andrew Cooper]

Sorry - it appears I mess the CC list up here.  CC'ing "The Rest" for
this combined fixup and cleanup patch for livepatch.markdown, for
inclusion into 4.11

~Andrew

On 08/05/18 10:55, Andrew Cooper wrote:
> From: Juergen Gross <jgross@suse.com>
>
> "make -C docs all" fails due to incorrect markdown syntax in
> livepatch.markdown. Correct it.
>
> Signed-off-by: Juergen Gross <jgross@suse.com>
> Reviewed-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
>
> Misc fixes:
>  * Insert real URLs
>  * Drop trailing whitespace
>  * Consistent alignment and indentation for code blocks and lists
>  * Consistent capitalisation
>  * Consistent use of `` blocks for command line arguments and function names
>  * Rearrange things not to leave &lt; and &gt; in the text
>
> No change in content.  The document now reads rather more consistently in HTML
> and PDF form.
>
> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
> ---
>  docs/misc/livepatch.markdown | 693 ++++++++++++++++++++-----------------------
>  1 file changed, 320 insertions(+), 373 deletions(-)
>
> diff --git a/docs/misc/livepatch.markdown b/docs/misc/livepatch.markdown
> index 54a6b85..2bdf871 100644
> --- a/docs/misc/livepatch.markdown
> +++ b/docs/misc/livepatch.markdown
> @@ -85,53 +85,42 @@ mechanism. See `Trampoline (e9 opcode)` section for more details.
>  ### Example of trampoline and in-place splicing
>  
>  As example we will assume the hypervisor does not have XSA-132 (see
> -*domctl/sysctl: don't leak hypervisor stack to toolstacks*
> -4ff3449f0e9d175ceb9551d3f2aecb59273f639d) and we would like to binary patch
> -the hypervisor with it. The original code looks as so:
> +[domctl/sysctl: don't leak hypervisor stack to toolstacks](http://xenbits.xen.org/gitweb/?p=xen.git;a=commitdiff;h=4ff3449f0e9d175ceb9551d3f2aecb59273f639d))
> +and we would like to binary patch the hypervisor with it. The original code
> +looks as so:
>  
> -<pre>
> -   48 89 e0                  mov    %rsp,%rax  
> -   48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax  
> -</pre>
> +    48 89 e0                  mov    %rsp,%rax
> +    48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax
>  
>  while the new patched hypervisor would be:
>  
> -<pre>
> -   48 c7 45 b8 00 00 00 00   movq   $0x0,-0x48(%rbp)  
> -   48 c7 45 c0 00 00 00 00   movq   $0x0,-0x40(%rbp)  
> -   48 c7 45 c8 00 00 00 00   movq   $0x0,-0x38(%rbp)  
> -   48 89 e0                  mov    %rsp,%rax  
> -   48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax  
> -</pre>
> +    48 c7 45 b8 00 00 00 00   movq   $0x0,-0x48(%rbp)
> +    48 c7 45 c0 00 00 00 00   movq   $0x0,-0x40(%rbp)
> +    48 c7 45 c8 00 00 00 00   movq   $0x0,-0x38(%rbp)
> +    48 89 e0                  mov    %rsp,%rax
> +    48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax
>  
> -This is inside the arch_do_domctl. This new change adds 21 extra
> +This is inside the arch\_do\_domctl. This new change adds 21 extra
>  bytes of code which alters all the offsets inside the function. To alter
>  these offsets and add the extra 21 bytes of code we might not have enough
>  space in .text to squeeze this in.
>  
>  As such we could simplify this problem by only patching the site
> -which calls arch_do_domctl:
> +which calls arch\_do\_domctl:
>  
> -<pre>
> -do_domctl:  
> - e8 4b b1 05 00          callq  ffff82d08015fbb9 <arch_do_domctl>  
> -</pre>
> +    do_domctl:
> +    e8 4b b1 05 00          callq  ffff82d08015fbb9 <arch_do_domctl>
>  
>  with a new address for where the new `arch_do_domctl` would be (this
>  area would be allocated dynamically).
>  
>  Astute readers will wonder what we need to do if we were to patch `do_domctl`
>  - which is not called directly by hypervisor but on behalf of the guests via
> -the `compat_hypercall_table` and `hypercall_table`.
> -Patching the offset in `hypercall_table` for `do_domctl:
> -(ffff82d080103079 <do_domctl>:)
> +the `compat_hypercall_table` and `hypercall_table`.  Patching the offset in
> +`hypercall_table` for `do_domctl`:
>  
> -<pre>
> -
> - ffff82d08024d490:   79 30  
> - ffff82d08024d492:   10 80 d0 82 ff ff   
> -
> -</pre>
> +    ffff82d08024d490:   79 30
> +    ffff82d08024d492:   10 80 d0 82 ff ff
>  
>  with the new address where the new `do_domctl` is possible. The other
>  place where it is used is in `hvm_hypercall64_table` which would need
> @@ -139,10 +128,11 @@ to be patched in a similar way. This would require an in-place splicing
>  of the new virtual address of `arch_do_domctl`.
>  
>  In summary this example patched the callee of the affected function by
> - * allocating memory for the new code to live in,
> - * changing the virtual address in all the functions which called the old
> +
> + * Allocating memory for the new code to live in,
> + * Changing the virtual address in all the functions which called the old
>     code (computing the new offset, patching the callq with a new callq).
> - * changing the function pointer tables with the new virtual address of
> + * Changing the function pointer tables with the new virtual address of
>     the function (splicing in the new virtual address). Since this table
>     resides in the .rodata section we would need to temporarily change the
>     page table permissions during this part.
> @@ -162,21 +152,18 @@ existing function to be patched to jump directly to the new code. This
>  lessens the locations to be patched to one but it puts pressure on the
>  CPU branching logic (I-cache, but it is just one unconditional jump).
>  
> -For this example we will assume that the hypervisor has not been compiled
> -with fe2e079f642effb3d24a6e1a7096ef26e691d93e (XSA-125: *pre-fill structures
> -for certain HYPERVISOR_xen_version sub-ops*) which mem-sets an structure
> -in `xen_version` hypercall. This function is not called **anywhere** in
> -the hypervisor (it is called by the guest) but referenced in the
> -`compat_hypercall_table` and `hypercall_table` (and indirectly called
> -from that). Patching the offset in `hypercall_table` for the old
> -`do_xen_version` (ffff82d080112f9e <do_xen_version>)
> -
> -</pre>
> - ffff82d08024b270 <hypercall_table>:   
> - ...  
> - ffff82d08024b2f8:   9e 2f 11 80 d0 82 ff ff  
> +For this example we will assume that the hypervisor has not been compiled with
> +XSA-125 (see
> +[pre-fill structures for certain HYPERVISOR\_xen\_version sub-ops](http://xenbits.xen.org/gitweb/?p=xen.git;a=commitdiff;h=fe2e079f642effb3d24a6e1a7096ef26e691d93e))
> +which mem-sets an structure in `xen_version` hypercall. This function is not
> +called **anywhere** in the hypervisor (it is called by the guest) but
> +referenced in the `compat_hypercall_table` and `hypercall_table` (and
> +indirectly called from that). Patching the offset in `hypercall_table` for the
> +old `do_xen_version`:
>  
> -</pre>
> +    ffff82d08024b270 <hypercall_table>:
> +    ...
> +    ffff82d08024b2f8:   9e 2f 11 80 d0 82 ff ff
>  
>  with the new address where the new `do_xen_version` is possible. The other
>  place where it is used is in `hvm_hypercall64_table` which would need
> @@ -184,31 +171,28 @@ to be patched in a similar way. This would require an in-place splicing
>  of the new virtual address of `do_xen_version`.
>  
>  An alternative solution would be to patch insert a trampoline in the
> -old `do_xen_version' function to directly jump to the new `do_xen_version`.
> +old `do_xen_version` function to directly jump to the new `do_xen_version`:
>  
> -<pre>
> - ffff82d080112f9e do_xen_version:  
> - ffff82d080112f9e:       48 c7 c0 da ff ff ff    mov    $0xffffffffffffffda,%rax  
> - ffff82d080112fa5:       83 ff 09                cmp    $0x9,%edi  
> - ffff82d080112fa8:       0f 87 24 05 00 00       ja     ffff82d0801134d2 ; do_xen_version+0x534  
> -</pre>
> +    ffff82d080112f9e do_xen_version:
> +    ffff82d080112f9e:       48 c7 c0 da ff ff ff    mov    $0xffffffffffffffda,%rax
> +    ffff82d080112fa5:       83 ff 09                cmp    $0x9,%edi
> +    ffff82d080112fa8:       0f 87 24 05 00 00       ja     ffff82d0801134d2 ; do_xen_version+0x534
>  
>  with:
>  
> -<pre>
> - ffff82d080112f9e do_xen_version:  
> - ffff82d080112f9e:       e9 XX YY ZZ QQ          jmpq   [new do_xen_version]  
> -</pre>
> +    ffff82d080112f9e do_xen_version:
> +    ffff82d080112f9e:       e9 XX YY ZZ QQ          jmpq   [new do_xen_version]
>  
>  which would lessen the amount of patching to just one location.
>  
>  In summary this example patched the affected function to jump to the
>  new replacement function which required:
> - * allocating memory for the new code to live in,
> - * inserting trampoline with new offset in the old function to point to the
> +
> + * Allocating memory for the new code to live in,
> + * Inserting trampoline with new offset in the old function to point to the
>     new function.
>   * Optionally we can insert in the old function a trampoline jump to an function
> -   providing an BUG_ON to catch errant code.
> +   providing an BUG\_ON to catch errant code.
>  
>  The disadvantage of this are that the unconditional jump will consume a small
>  I-cache penalty. However the simplicity of the patching and higher chance
> @@ -260,7 +244,7 @@ Note that every structure has padding. This is added so that the hypervisor
>  can re-use those fields as it sees fit.
>  
>  Earlier design attempted to ineptly explain the relations of the ELF sections
> -to each other without using proper ELF mechanism (sh_info, sh_link, data
> +to each other without using proper ELF mechanism (sh\_info, sh\_link, data
>  structures using Elf types, etc). This design will explain the structures
>  and how they are used together and not dig in the ELF format - except mention
>  that the section names should match the structure names.
> @@ -285,60 +269,53 @@ like what the Linux kernel module loader does.
>  
>  The payload contains at least three sections:
>  
> - * `.livepatch.funcs` - which is an array of livepatch_func structures.
> + * `.livepatch.funcs` - which is an array of livepatch\_func structures.
>   * `.livepatch.depends` - which is an ELF Note that describes what the payload
>      depends on. **MUST** have one.
>   *  `.note.gnu.build-id` - the build-id of this payload. **MUST** have one.
>  
>  ### .livepatch.funcs
>  
> -The `.livepatch.funcs` contains an array of livepatch_func structures
> +The `.livepatch.funcs` contains an array of livepatch\_func structures
>  which describe the functions to be patched:
>  
> -<pre>
> -struct livepatch_func {  
> -    const char *name;  
> -    void *new_addr;  
> -    void *old_addr;  
> -    uint32_t new_size;  
> -    uint32_t old_size;  
> -    uint8_t version;  
> -    uint8_t opaque[31];  
> -};  
> -</pre>
> +    struct livepatch_func {
> +        const char *name;
> +        void *new_addr;
> +        void *old_addr;
> +        uint32_t new_size;
> +        uint32_t old_size;
> +        uint8_t version;
> +        uint8_t opaque[31];
> +    };
>  
>  The size of the structure is 64 bytes on 64-bit hypervisors. It will be
>  52 on 32-bit hypervisors.
>  
> -* `name` is the symbol name of the old function. Only used if `old_addr` is
> + * `name` is the symbol name of the old function. Only used if `old_addr` is
>     zero, otherwise will be used during dynamic linking (when hypervisor loads
>     the payload).
> -
> -* `old_addr` is the address of the function to be patched and is filled in at
> -  payload generation time if hypervisor function address is known. If unknown,
> -  the value *MUST* be zero and the hypervisor will attempt to resolve the address.
> -
> -* `new_addr` can either have a non-zero value or be zero.
> -  * If there is a non-zero value, then it is the address of the function that is
> -    replacing the old function and the address is recomputed during relocation.
> -    The value **MUST** be the address of the new function in the payload file.
> -
> -  * If the value is zero, then we NOPing out at the `old_addr` location
> + * `old_addr` is the address of the function to be patched and is filled in at
> +   payload generation time if hypervisor function address is known. If unknown,
> +   the value *MUST* be zero and the hypervisor will attempt to resolve the
> +   address.
> + * `new_addr` can either have a non-zero value or be zero.
> +   * If there is a non-zero value, then it is the address of the function that
> +    is replacing the old function and the address is recomputed during
> +    relocation.  The value **MUST** be the address of the new function in the
> +    payload file.
> +   * If the value is zero, then we NOPing out at the `old_addr` location
>      `new_size` bytes.
> -
> -* `old_size` contains the sizes of the respective `old_addr` function in bytes.
> -   The value of `old_size` **MUST** not be zero.
> -
> -* `new_size` depends on what `new_addr` contains:
> -  * If `new_addr` contains an non-zero value, then `new_size` has the size of
> -    the new function (which will replace the one at `old_addr`)  in bytes.
> -  * If the value of `new_addr` is zero then `new_size` determines how many
> + * `old_size` contains the sizes of the respective `old_addr` function in
> +    bytes.  The value of `old_size` **MUST** not be zero.
> + * `new_size` depends on what `new_addr` contains:
> +   * If `new_addr` contains an non-zero value, then `new_size` has the size of
> +    the new function (which will replace the one at `old_addr`) in bytes.
> +   * If the value of `new_addr` is zero then `new_size` determines how many
>      instruction bytes to NOP (up to opaque size modulo smallest platform
>      instruction - 1 byte x86 and 4 bytes on ARM).
> -
> -* `version` is to be one.
> -
> -* `opaque` **MUST** be zero.
> + * `version` is to be one.
> + * `opaque` **MUST** be zero.
>  
>  The size of the `livepatch_func` array is determined from the ELF section
>  size.
> @@ -362,38 +339,35 @@ being applied and after being reverted:
>  
>  A simple example of what a payload file can be:
>  
> -<pre>
> -/* MUST be in sync with hypervisor. */  
> -struct livepatch_func {  
> -    const char *name;  
> -    void *new_addr;  
> -    void *old_addr;  
> -    uint32_t new_size;  
> -    uint32_t old_size;  
> -    uint8_t version;
> -    uint8_t pad[31];  
> -};  
> -
> -/* Our replacement function for xen_extra_version. */  
> -const char *xen_hello_world(void)  
> -{  
> -    return "Hello World";  
> -}  
> -
> -static unsigned char patch_this_fnc[] = "xen_extra_version";  
> -
> -struct livepatch_func livepatch_hello_world = {  
> -    .version = LIVEPATCH_PAYLOAD_VERSION,
> -    .name = patch_this_fnc,  
> -    .new_addr = xen_hello_world,  
> -    .old_addr = (void *)0xffff82d08013963c, /* Extracted from xen-syms. */  
> -    .new_size = 13, /* To be be computed by scripts. */  
> -    .old_size = 13, /* -----------""---------------  */  
> -} __attribute__((__section__(".livepatch.funcs")));  
> -
> -</pre>
> -
> -Code must be compiled with -fPIC.
> +    /* MUST be in sync with hypervisor. */
> +    struct livepatch_func {
> +        const char *name;
> +        void *new_addr;
> +        void *old_addr;
> +        uint32_t new_size;
> +        uint32_t old_size;
> +        uint8_t version;
> +        uint8_t pad[31];
> +    };
> +
> +    /* Our replacement function for xen_extra_version. */
> +    const char *xen_hello_world(void)
> +    {
> +        return "Hello World";
> +    }
> +
> +    static unsigned char patch_this_fnc[] = "xen_extra_version";
> +
> +    struct livepatch_func livepatch_hello_world = {
> +        .version = LIVEPATCH_PAYLOAD_VERSION,
> +        .name = patch_this_fnc,
> +        .new_addr = xen_hello_world,
> +        .old_addr = (void *)0xffff82d08013963c, /* Extracted from xen-syms. */
> +        .new_size = 13, /* To be be computed by scripts. */
> +        .old_size = 13, /* -----------""---------------  */
> +    } __attribute__((__section__(".livepatch.funcs")));
> +
> +Code must be compiled with `-fPIC`.
>  
>  ### .livepatch.hooks.load and .livepatch.hooks.unload
>  
> @@ -406,10 +380,8 @@ Each entry in this array is eight bytes.
>  
>  The type definition of the function are as follow:
>  
> -<pre>
> -typedef void (*livepatch_loadcall_t)(void);  
> -typedef void (*livepatch_unloadcall_t)(void);   
> -</pre>
> +    typedef void (*livepatch_loadcall_t)(void);
> +    typedef void (*livepatch_unloadcall_t)(void);
>  
>  ### .livepatch.depends and .note.gnu.build-id
>  
> @@ -423,10 +395,10 @@ which follows the format of an ELF Note. The contents of this
>  build the hypevisor and payload.
>  
>  If GNU linker is used then the name is `GNU` and the description
> -is a NT_GNU_BUILD_ID type ID. The description can be an SHA1
> +is a NT\_GNU\_BUILD\_ID type ID. The description can be an SHA1
>  checksum, MD5 checksum or any unique value.
>  
> -The size of these structures varies with the --build-id linker option.
> +The size of these structures varies with the `--build-id` linker option.
>  
>  ## Hypercalls
>  
> @@ -454,22 +426,20 @@ Furthermore it is possible to have multiple different payloads for the same
>  function. As such an unique name per payload has to be visible to allow proper manipulation.
>  
>  The hypercall is part of the `xen_sysctl`. The top level structure contains
> -one uint32_t to determine the sub-operations and one padding field which
> +one uint32\_t to determine the sub-operations and one padding field which
>  *MUST* always be zero.
>  
> -<pre>
> -struct xen_sysctl_livepatch_op {  
> -    uint32_t cmd;                   /* IN: XEN_SYSCTL_LIVEPATCH_*. */  
> -    uint32_t pad;                   /* IN: Always zero. */  
> -	union {  
> -          ... see below ...  
> -        } u;  
> -};  
> +    struct xen_sysctl_livepatch_op {
> +        uint32_t cmd;                   /* IN: XEN_SYSCTL_LIVEPATCH_*. */
> +        uint32_t pad;                   /* IN: Always zero. */
> +	    union {
> +              ... see below ...
> +            } u;
> +    };
>  
> -</pre>
>  while the rest of hypercall specific structures are part of the this structure.
>  
> -### Basic type: struct xen_livepatch_name
> +### Basic type: struct xen\_livepatch\_name
>  
>  Most of the hypercalls employ an shared structure called `struct xen_livepatch_name`
>  which contains:
> @@ -480,26 +450,24 @@ which contains:
>  
>  The structure is as follow:
>  
> -<pre>
> -/*  
> - *  Uniquely identifies the payload.  Should be human readable.  
> - * Includes the NUL terminator  
> - */  
> -#define XEN_LIVEPATCH_NAME_SIZE 128  
> -struct xen_livepatch_name {  
> -    XEN_GUEST_HANDLE_64(char) name;         /* IN, pointer to name. */  
> -    uint16_t size;                          /* IN, size of name. May be upto   
> -                                               XEN_LIVEPATCH_NAME_SIZE. */  
> -    uint16_t pad[3];                        /* IN: MUST be zero. */ 
> -};  
> -</pre>
> -
> -### XEN_SYSCTL_LIVEPATCH_UPLOAD (0)
> +    /*
> +     *  Uniquely identifies the payload.  Should be human readable.
> +     * Includes the NUL terminator
> +     */
> +    #define XEN_LIVEPATCH_NAME_SIZE 128
> +    struct xen_livepatch_name {
> +        XEN_GUEST_HANDLE_64(char) name;         /* IN, pointer to name. */
> +        uint16_t size;                          /* IN, size of name. May be upto
> +                                                   XEN_LIVEPATCH_NAME_SIZE. */
> +        uint16_t pad[3];                        /* IN: MUST be zero. */
> +    };
> +
> +### XEN\_SYSCTL\_LIVEPATCH\_UPLOAD (0)
>  
>  Upload a payload to the hypervisor. The payload is verified
>  against basic checks and if there are any issues the proper return code
>  will be returned. The payload is not applied at this time - that is
> -controlled by *XEN_SYSCTL_LIVEPATCH_ACTION*.
> +controlled by *XEN\_SYSCTL\_LIVEPATCH\_ACTION*.
>  
>  The caller provides:
>  
> @@ -512,21 +480,19 @@ payload. It can be embedded into the ELF payload at creation time
>  and extracted by tools.
>  
>  The return value is zero if the payload was succesfully uploaded.
> -Otherwise an -XEN_EXX return value is provided. Duplicate `name` are not supported.
> +Otherwise an -XEN\_EXX return value is provided. Duplicate `name` are not supported.
>  
>  The `payload` is the ELF payload as mentioned in the `Payload format` section.
>  
>  The structure is as follow:
>  
> -<pre>
> -struct xen_sysctl_livepatch_upload {  
> -    xen_livepatch_name_t name;          /* IN, name of the patch. */  
> -    uint64_t size;                      /* IN, size of the ELF file. */  
> -    XEN_GUEST_HANDLE_64(uint8) payload; /* IN: ELF file. */  
> -};  
> -</pre>
> +    struct xen_sysctl_livepatch_upload {
> +        xen_livepatch_name_t name;          /* IN, name of the patch. */
> +        uint64_t size;                      /* IN, size of the ELF file. */
> +        XEN_GUEST_HANDLE_64(uint8) payload; /* IN: ELF file. */
> +    };
>  
> -### XEN_SYSCTL_LIVEPATCH_GET (1)
> +### XEN\_SYSCTL\_LIVEPATCH\_GET (1)
>  
>  Retrieve an status of an specific payload. This caller provides:
>  
> @@ -537,33 +503,29 @@ Retrieve an status of an specific payload. This caller provides:
>  Upon completion the `struct xen_livepatch_status` is updated.
>  
>   * `status` - indicates the current status of the payload:
> -   * *LIVEPATCH_STATUS_CHECKED*  (1) loaded and the ELF payload safety checks passed.
> -   * *LIVEPATCH_STATUS_APPLIED* (2) loaded, checked, and applied.
> +   * *LIVEPATCH\_STATUS\_CHECKED* (1) loaded and the ELF payload safety checks passed.
> +   * *LIVEPATCH\_STATUS\_APPLIED* (2) loaded, checked, and applied.
>     *  No other value is possible.
> - * `rc` - -XEN_EXX type errors encountered while performing the last
> -   LIVEPATCH_ACTION_* operation. The normal values can be zero or -XEN_EAGAIN which
> + * `rc` - -XEN\_EXX type errors encountered while performing the last
> +   LIVEPATCH\_ACTION\_\* operation. The normal values can be zero or -XEN\_EAGAIN which
>     respectively mean: success or operation in progress. Other values
>     imply an error occurred. If there is an error in `rc`, `status` will **NOT**
>     have changed.
>  
> -The return value of the hypercall is zero on success and -XEN_EXX on failure.
> -(Note that the `rc`` value can be different from the return value, as in
> -rc=-XEN_EAGAIN and return value can be 0).
> +The return value of the hypercall is zero on success and -XEN\_EXX on failure.
> +(Note that the `rc` value can be different from the return value, as in
> +rc=-XEN\_EAGAIN and return value can be 0).
>  
>  For example, supposing there is an payload:
>  
> -<pre>
> - status: LIVEPATCH_STATUS_CHECKED
> - rc: 0
> -</pre>
> +    status: LIVEPATCH_STATUS_CHECKED
> +    rc: 0
>  
> -We apply an action - LIVEPATCH_ACTION_REVERT - to revert it (which won't work
> +We apply an action - LIVEPATCH\_ACTION\_REVERT - to revert it (which won't work
>  as we have not even applied it. Afterwards we will have:
>  
> -<pre>
> - status: LIVEPATCH_STATUS_CHECKED
> - rc: -XEN_EINVAL
> -</pre>
> +    status: LIVEPATCH_STATUS_CHECKED
> +    rc: -XEN_EINVAL
>  
>  It has failed but it remains loaded.
>  
> @@ -571,21 +533,19 @@ This operation is synchronous and does not require preemption.
>  
>  The structure is as follow:
>  
> -<pre>
> -struct xen_livepatch_status {  
> -#define LIVEPATCH_STATUS_CHECKED      1  
> -#define LIVEPATCH_STATUS_APPLIED      2  
> -    uint32_t state;                 /* OUT: LIVEPATCH_STATE_*. */  
> -    int32_t rc;                     /* OUT: 0 if no error, otherwise -XEN_EXX. */  
> -};  
> +    struct xen_livepatch_status {
> +    #define LIVEPATCH_STATUS_CHECKED      1
> +    #define LIVEPATCH_STATUS_APPLIED      2
> +        uint32_t state;                 /* OUT: LIVEPATCH_STATE_*. */
> +        int32_t rc;                     /* OUT: 0 if no error, otherwise -XEN_EXX. */
> +    };
>  
> -struct xen_sysctl_livepatch_get {  
> -    xen_livepatch_name_t name;      /* IN, the name of the payload. */  
> -    xen_livepatch_status_t status;  /* IN/OUT: status of the payload. */  
> -};  
> -</pre>
> +    struct xen_sysctl_livepatch_get {
> +        xen_livepatch_name_t name;      /* IN, the name of the payload. */
> +        xen_livepatch_status_t status;  /* IN/OUT: status of the payload. */
> +    };
>  
> -### XEN_SYSCTL_LIVEPATCH_LIST (2)
> +### XEN\_SYSCTL\_LIVEPATCH\_LIST (2)
>  
>  Retrieve an array of abbreviated status and names of payloads that are loaded in the
>  hypervisor.
> @@ -594,32 +554,32 @@ The caller provides:
>  
>   * `version`. Version of the payload. Caller should re-use the field provided by
>      the hypervisor. If the value differs the data is stale.
> - * `idx` index iterator. The index into the hypervisor's payload count. It is
> + * `idx` Index iterator. The index into the hypervisor's payload count. It is
>      recommended that on first invocation zero be used so that `nr` (which the
>      hypervisor will update with the remaining payload count) be provided.
>      Also the hypervisor will provide `version` with the most current value.
> - * `nr` the max number of entries to populate. Can be zero which will result
> + * `nr` The max number of entries to populate. Can be zero which will result
>      in the hypercall being a probing one and return the number of payloads
>      (and update the `version`).
>   * `pad` - *MUST* be zero.
> - * `status` virtual address of where to write `struct xen_livepatch_status`
> + * `status` Virtual address of where to write `struct xen_livepatch_status`
>     structures. Caller *MUST* allocate up to `nr` of them.
> - * `name` - virtual address of where to write the unique name of the payload.
> + * `name` - Virtual address of where to write the unique name of the payload.
>     Caller *MUST* allocate up to `nr` of them. Each *MUST* be of
> -   **XEN_LIVEPATCH_NAME_SIZE** size. Note that **XEN_LIVEPATCH_NAME_SIZE** includes
> +   **XEN\_LIVEPATCH\_NAME\_SIZE** size. Note that **XEN\_LIVEPATCH\_NAME\_SIZE** includes
>     the NUL terminator.
> - * `len` - virtual address of where to write the length of each unique name
> + * `len` - Virtual address of where to write the length of each unique name
>     of the payload. Caller *MUST* allocate up to `nr` of them. Each *MUST* be
> -   of sizeof(uint32_t) (4 bytes).
> +   of sizeof(uint32\_t) (4 bytes).
>  
>  If the hypercall returns an positive number, it is the number (upto `nr`
>  provided to the hypercall) of the payloads returned, along with `nr` updated
>  with the number of remaining payloads, `version` updated (it may be the same
>  across hypercalls - if it varies the data is stale and further calls could
> -fail). The `status`, `name`, and `len`' are updated at their designed index
> +fail). The `status`, `name`, and `len` are updated at their designed index
>  value (`idx`) with the returned value of data.
>  
> -If the hypercall returns -XEN_E2BIG the `nr` is too big and should be
> +If the hypercall returns -XEN\_E2BIG the `nr` is too big and should be
>  lowered.
>  
>  If the hypercall returns an zero value there are no more payloads.
> @@ -634,62 +594,60 @@ data and start from scratch. It is OK for the toolstack to use the new
>  The `struct xen_livepatch_status` structure contains an status of payload which includes:
>  
>   * `status` - indicates the current status of the payload:
> -   * *LIVEPATCH_STATUS_CHECKED*  (1) loaded and the ELF payload safety checks passed.
> -   * *LIVEPATCH_STATUS_APPLIED* (2) loaded, checked, and applied.
> +   * *LIVEPATCH\_STATUS\_CHECKED* (1) loaded and the ELF payload safety checks passed.
> +   * *LIVEPATCH\_STATUS\_APPLIED* (2) loaded, checked, and applied.
>     *  No other value is possible.
> - * `rc` - -XEN_EXX type errors encountered while performing the last
> -   LIVEPATCH_ACTION_* operation. The normal values can be zero or -XEN_EAGAIN which
> + * `rc` - -XEN\_EXX type errors encountered while performing the last
> +   LIVEPATCH\_ACTION\_\* operation. The normal values can be zero or -XEN\_EAGAIN which
>     respectively mean: success or operation in progress. Other values
>     imply an error occurred. If there is an error in `rc`, `status` will **NOT**
>     have changed.
>  
>  The structure is as follow:
>  
> -<pre>
> -struct xen_sysctl_livepatch_list {  
> -    uint32_t version;                       /* OUT: Hypervisor stamps value.
> -                                               If varies between calls, we are  
> -                                               getting stale data. */  
> -    uint32_t idx;                           /* IN: Index into hypervisor list. */
> -    uint32_t nr;                            /* IN: How many status, names, and len  
> -                                               should be filled out. Can be zero to get  
> -                                               amount of payloads and version.  
> -                                               OUT: How many payloads left. */  
> -    uint32_t pad;                           /* IN: Must be zero. */  
> -    XEN_GUEST_HANDLE_64(xen_livepatch_status_t) status;  /* OUT. Must have enough  
> -                                               space allocate for nr of them. */  
> -    XEN_GUEST_HANDLE_64(char) id;           /* OUT: Array of names. Each member  
> -                                               MUST XEN_LIVEPATCH_NAME_SIZE in size.  
> -                                               Must have nr of them. */  
> -    XEN_GUEST_HANDLE_64(uint32) len;        /* OUT: Array of lengths of name's.  
> -                                               Must have nr of them. */  
> -};  
> -</pre>
> -
> -### XEN_SYSCTL_LIVEPATCH_ACTION (3)
> +    struct xen_sysctl_livepatch_list {
> +        uint32_t version;                       /* OUT: Hypervisor stamps value.
> +                                                   If varies between calls, we are
> +                                                   getting stale data. */
> +        uint32_t idx;                           /* IN: Index into hypervisor list. */
> +        uint32_t nr;                            /* IN: How many status, names, and len
> +                                                   should be filled out. Can be zero to get
> +                                                   amount of payloads and version.
> +                                                   OUT: How many payloads left. */
> +        uint32_t pad;                           /* IN: Must be zero. */
> +        XEN_GUEST_HANDLE_64(xen_livepatch_status_t) status;  /* OUT. Must have enough
> +                                                   space allocate for nr of them. */
> +        XEN_GUEST_HANDLE_64(char) id;           /* OUT: Array of names. Each member
> +                                                   MUST XEN_LIVEPATCH_NAME_SIZE in size.
> +                                                   Must have nr of them. */
> +        XEN_GUEST_HANDLE_64(uint32) len;        /* OUT: Array of lengths of name's.
> +                                                   Must have nr of them. */
> +    };
> +
> +### XEN\_SYSCTL\_LIVEPATCH\_ACTION (3)
>  
>  Perform an operation on the payload structure referenced by the `name` field.
>  The operation request is asynchronous and the status should be retrieved
> -by using either **XEN_SYSCTL_LIVEPATCH_GET** or **XEN_SYSCTL_LIVEPATCH_LIST** hypercall.
> +by using either **XEN\_SYSCTL\_LIVEPATCH\_GET** or **XEN\_SYSCTL\_LIVEPATCH\_LIST** hypercall.
>  
>  The caller provides:
>  
> - * A 'struct xen_livepatch_name` `name` containing the unique name.
> - * `cmd` the command requested:
> -  * *LIVEPATCH_ACTION_UNLOAD* (1) unload the payload.
> + * A `struct xen_livepatch_name` `name` containing the unique name.
> + * `cmd` The command requested:
> +  * *LIVEPATCH\_ACTION\_UNLOAD* (1) Unload the payload.
>     Any further hypercalls against the `name` will result in failure unless
> -   **XEN_SYSCTL_LIVEPATCH_UPLOAD** hypercall is perfomed with same `name`.
> -  * *LIVEPATCH_ACTION_REVERT* (2) revert the payload. If the operation takes
> -  more time than the upper bound of time the `rc` in `xen_livepatch_status'
> -  retrieved via **XEN_SYSCTL_LIVEPATCH_GET** will be -XEN_EBUSY.
> -  * *LIVEPATCH_ACTION_APPLY* (3) apply the payload. If the operation takes
> -  more time than the upper bound of time the `rc` in `xen_livepatch_status'
> -  retrieved via **XEN_SYSCTL_LIVEPATCH_GET** will be -XEN_EBUSY.
> -  * *LIVEPATCH_ACTION_REPLACE* (4) revert all applied payloads and apply this
> +   **XEN\_SYSCTL\_LIVEPATCH\_UPLOAD** hypercall is perfomed with same `name`.
> +  * *LIVEPATCH\_ACTION\_REVERT* (2) Revert the payload. If the operation takes
> +  more time than the upper bound of time the `rc` in `xen_livepatch_status`
> +  retrieved via **XEN\_SYSCTL\_LIVEPATCH\_GET** will be -XEN\_EBUSY.
> +  * *LIVEPATCH\_ACTION\_APPLY* (3) Apply the payload. If the operation takes
> +  more time than the upper bound of time the `rc` in `xen_livepatch_status`
> +  retrieved via **XEN\_SYSCTL\_LIVEPATCH\_GET** will be -XEN\_EBUSY.
> +  * *LIVEPATCH\_ACTION\_REPLACE* (4) Revert all applied payloads and apply this
>    payload. If the operation takes more time than the upper bound of time
> -  the `rc` in `xen_livepatch_status' retrieved via **XEN_SYSCTL_LIVEPATCH_GET**
> -  will be -XEN_EBUSY.
> - * `time` the upper bound of time (ns) the cmd should take. Zero means to use
> +  the `rc` in `xen_livepatch_status` retrieved via **XEN\_SYSCTL\_LIVEPATCH\_GET**
> +  will be -XEN\_EBUSY.
> + * `time` The upper bound of time (ns) the cmd should take. Zero means to use
>     the hypervisor default. If within the time the operation does not succeed
>     the operation would go in error state.
>   * `pad` - *MUST* be zero.
> @@ -698,71 +656,64 @@ The return value will be zero unless the provided fields are incorrect.
>  
>  The structure is as follow:
>  
> -<pre>
> -#define LIVEPATCH_ACTION_UNLOAD  1  
> -#define LIVEPATCH_ACTION_REVERT  2  
> -#define LIVEPATCH_ACTION_APPLY   3  
> -#define LIVEPATCH_ACTION_REPLACE 4  
> -struct xen_sysctl_livepatch_action {  
> -    xen_livepatch_name_t name;              /* IN, name of the patch. */  
> -    uint32_t cmd;                           /* IN: LIVEPATCH_ACTION_* */  
> -    uint32_t time;                          /* IN: If zero then uses */
> -                                            /* hypervisor default. */
> -                                            /* Or upper bound of time (ns) */
> -                                            /* for operation to take. */
> -};  
> +    #define LIVEPATCH_ACTION_UNLOAD  1
> +    #define LIVEPATCH_ACTION_REVERT  2
> +    #define LIVEPATCH_ACTION_APPLY   3
> +    #define LIVEPATCH_ACTION_REPLACE 4
> +    struct xen_sysctl_livepatch_action {
> +        xen_livepatch_name_t name;              /* IN, name of the patch. */
> +        uint32_t cmd;                           /* IN: LIVEPATCH_ACTION_* */
> +        uint32_t time;                          /* IN: If zero then uses */
> +                                                /* hypervisor default. */
> +                                                /* Or upper bound of time (ns) */
> +                                                /* for operation to take. */
> +    };
>  
> -</pre>
>  
> -## State diagrams of LIVEPATCH_ACTION commands.
> +## State diagrams of LIVEPATCH\_ACTION commands.
>  
>  There is a strict ordering state of what the commands can be.
> -The LIVEPATCH_ACTION prefix has been dropped to easy reading and
> -does not include the LIVEPATCH_STATES:
> +The LIVEPATCH\_ACTION prefix has been dropped to easy reading and
> +does not include the LIVEPATCH\_STATES:
>  
> -<pre>
> -              /->\  
> -              \  /  
> - UNLOAD <--- CHECK ---> REPLACE|APPLY --> REVERT --\  
> -                \                                  |  
> -                 \-------------------<-------------/  
> +                 /->\
> +                 \  /
> +    UNLOAD <--- CHECK ---> REPLACE|APPLY --> REVERT --\
> +                   \                                  |
> +                    \-------------------<-------------/
>  
> -</pre>
> -## State transition table of LIVEPATCH_ACTION commands and LIVEPATCH_STATUS.
> +## State transition table of LIVEPATCH\_ACTION commands and LIVEPATCH\_STATUS.
>  
>  Note that:
>  
> - - The CHECKED state is the starting one achieved with *XEN_SYSCTL_LIVEPATCH_UPLOAD* hypercall.
> + - The CHECKED state is the starting one achieved with *XEN\_SYSCTL\_LIVEPATCH\_UPLOAD* hypercall.
>   - The REVERT operation on success will automatically move to the CHECKED state.
>   - There are two STATES: CHECKED and APPLIED.
>   - There are four actions (aka commands): APPLY, REPLACE, REVERT, and UNLOAD.
>  
>  The state transition table of valid states and action states:
>  
> -<pre>
> -
> -+---------+---------+--------------------------------+-------+--------+
> -| ACTION  | Current | Result                         | Next STATE:    |
> -| ACTION  | STATE   |                                |CHECKED|APPLIED |
> -+---------+----------+-------------------------------+-------+--------+
> -| UNLOAD  | CHECKED | Unload payload. Always works.  |       |        |
> -|         |         | No next states.                |       |        |
> -+---------+---------+--------------------------------+-------+--------+
> -| APPLY   | CHECKED | Apply payload (success).       |       |   x    |
> -+---------+---------+--------------------------------+-------+--------+
> -| APPLY   | CHECKED | Apply payload (error|timeout)  |   x   |        |
> -+---------+---------+--------------------------------+-------+--------+
> -| REPLACE | CHECKED | Revert payloads and apply new  |       |   x    |
> -|         |         | payload with success.          |       |        |
> -+---------+---------+--------------------------------+-------+--------+
> -| REPLACE | CHECKED | Revert payloads and apply new  |   x   |        |
> -|         |         | payload with error.            |       |        |
> -+---------+---------+--------------------------------+-------+--------+
> -| REVERT  | APPLIED | Revert payload (success).      |   x   |        |
> -+---------+---------+--------------------------------+-------+--------+
> -| REVERT  | APPLIED | Revert payload (error|timeout) |       |   x    |
> -+---------+---------+--------------------------------+-------+--------+
> -</pre>
> +    +---------+---------+--------------------------------+-------+--------+
> +    | ACTION  | Current | Result                         |   Next STATE:  |
> +    | ACTION  | STATE   |                                |CHECKED|APPLIED |
> +    +---------+----------+-------------------------------+-------+--------+
> +    | UNLOAD  | CHECKED | Unload payload. Always works.  |       |        |
> +    |         |         | No next states.                |       |        |
> +    +---------+---------+--------------------------------+-------+--------+
> +    | APPLY   | CHECKED | Apply payload (success).       |       |   x    |
> +    +---------+---------+--------------------------------+-------+--------+
> +    | APPLY   | CHECKED | Apply payload (error|timeout)  |   x   |        |
> +    +---------+---------+--------------------------------+-------+--------+
> +    | REPLACE | CHECKED | Revert payloads and apply new  |       |   x    |
> +    |         |         | payload with success.          |       |        |
> +    +---------+---------+--------------------------------+-------+--------+
> +    | REPLACE | CHECKED | Revert payloads and apply new  |   x   |        |
> +    |         |         | payload with error.            |       |        |
> +    +---------+---------+--------------------------------+-------+--------+
> +    | REVERT  | APPLIED | Revert payload (success).      |   x   |        |
> +    +---------+---------+--------------------------------+-------+--------+
> +    | REVERT  | APPLIED | Revert payload (error|timeout) |       |   x    |
> +    +---------+---------+--------------------------------+-------+--------+
>  
>  All the other state transitions are invalid.
>  
> @@ -770,10 +721,10 @@ All the other state transitions are invalid.
>  
>  The normal sequence of events is to:
>  
> - 1. *XEN_SYSCTL_LIVEPATCH_UPLOAD* to upload the payload. If there are errors *STOP* here.
> - 2. *XEN_SYSCTL_LIVEPATCH_GET* to check the `->rc`. If *-XEN_EAGAIN* spin. If zero go to next step.
> - 3. *XEN_SYSCTL_LIVEPATCH_ACTION* with *LIVEPATCH_ACTION_APPLY* to apply the patch.
> - 4. *XEN_SYSCTL_LIVEPATCH_GET* to check the `->rc`. If in *-XEN_EAGAIN* spin. If zero exit with success.
> + 1. *XEN\_SYSCTL\_LIVEPATCH\_UPLOAD* to upload the payload. If there are errors *STOP* here.
> + 2. *XEN\_SYSCTL\_LIVEPATCH\_GET* to check the `->rc`. If *-XEN\_EAGAIN* spin. If zero go to next step.
> + 3. *XEN\_SYSCTL\_LIVEPATCH\_ACTION* with *LIVEPATCH\_ACTION\_APPLY* to apply the patch.
> + 4. *XEN\_SYSCTL\_LIVEPATCH\_GET* to check the `->rc`. If in *-XEN\_EAGAIN* spin. If zero exit with success.
>  
>  
>  ## Addendum
> @@ -807,18 +758,18 @@ minimize the chance of the patch not being applied due to safety
>  checks failing. Safety checks such as not patching code which
>  is on the stack - which can lead to corruption.
>  
> -#### Rendezvous code instead of stop_machine for patching
> +#### Rendezvous code instead of stop\_machine for patching
>  
>  The hypervisor's time rendezvous code runs synchronously across all CPUs
> -every second. Using the stop_machine to patch can stall the time rendezvous
> +every second. Using the `stop_machine` to patch can stall the time rendezvous
>  code and result in NMI. As such having the patching be done at the tail
>  of rendezvous code should avoid this problem.
>  
> -However the entrance point for that code is
> -do_softirq->timer_softirq_action->time_calibration
> -which ends up calling on_selected_cpus on remote CPUs.
> +However the entrance point for that code is `do_softirq ->
> +timer_softirq_action -> time_calibration` which ends up calling
> +`on_selected_cpus` on remote CPUs.
>  
> -The remote CPUs receive CALL_FUNCTION_VECTOR IPI and execute the
> +The remote CPUs receive CALL\_FUNCTION\_VECTOR IPI and execute the
>  desired function.
>  
>  #### Before entering the guest code.
> @@ -832,16 +783,16 @@ could be adjusted), combined with forcing all other CPUs through the
>  hypervisor with IPIs, can be utilized to execute lockstep instructions
>  on all CPUs.
>  
> -The approach is similar in concept to stop_machine and the time rendezvous
> +The approach is similar in concept to `stop_machine` and the time rendezvous
>  but is time-bound. However the local CPU stack is much shorter and
>  a lot more deterministic.
>  
> -This is implemented in the Xen Project hypervisor.
> +This is implemented in the Xen hypervisor.
>  
>  ### Compiling the hypervisor code
>  
>  Hotpatch generation often requires support for compiling the target
> -with -ffunction-sections / -fdata-sections.  Changes would have to
> +with `-ffunction-sections` / `-fdata-sections`.  Changes would have to
>  be done to the linker scripts to support this.
>  
>  ### Generation of Live Patch ELF payloads
> @@ -866,7 +817,7 @@ and reorder it afterwards.
>  As found almost every patch (XSA) to a non-trivial function requires
>  additional entries in the exception table and/or the bug frames.
>  
> -This is implemented in the Xen Project hypervisor.
> +This is implemented in the Xen hypervisor.
>  
>  ### .rodata sections
>  
> @@ -882,18 +833,18 @@ To guard against that we must be prepared to do patching similar to
>  trampoline patching or in-line depending on the flavour. If we can
>  do in-line patching we would need to:
>  
> - * alter `.rodata` to be writeable.
> - * inline patch.
> - * alter `.rodata` to be read-only.
> + * Alter `.rodata` to be writeable.
> + * Inline patch.
> + * Alter `.rodata` to be read-only.
>  
>  If are doing trampoline patching we would need to:
>  
> - * allocate a new memory location for the string.
> - * all locations which use this string will have to be updated to use the
> + * Allocate a new memory location for the string.
> + * All locations which use this string will have to be updated to use the
>     offset to the string.
> - * mark the region RO when we are done.
> + * Mark the region RO when we are done.
>  
> -The trampoline patching is implemented in the Xen Project hypervisor.
> +The trampoline patching is implemented in the Xen hypervisor.
>  
>  ### .bss and .data sections.
>  
> @@ -908,7 +859,7 @@ Patching in the new function will end up also patching in the new .rodata
>  section and the new function will reference the new string in the new
>  .rodata section.
>  
> -This is implemented in the Xen Project hypervisor.
> +This is implemented in the Xen hypervisor.
>  
>  ### Security
>  
> @@ -941,7 +892,7 @@ The old code allows much more flexibility and an additional guard,
>  but is more complex to implement.
>  
>  The second option which requires an build-id of the hypervisor
> -is implemented in the Xen Project hypervisor.
> +is implemented in the Xen hypervisor.
>  
>  Specifically each payload has two build-id ELF notes:
>   * The build-id of the payload itself (generated via --build-id).
> @@ -967,10 +918,10 @@ The implementation must also have a mechanism for (in no particular order):
>     the stack, make sure the payload is built with same compiler as hypervisor).
>     Specifically we want to make sure that live patching codepaths cannot be patched.
>   * NOP out the code sequence if `new_size` is zero.
> - * Deal with other relocation types:  R_X86_64_[8,16,32,32S], R_X86_64_PC[8,16,64]
> + * Deal with other relocation types:  R\_X86\_64\_[8,16,32,32S], R\_X86\_64\_PC[8,16,64]
>     in payload file.
>  
> -### Handle inlined __LINE__
> +### Handle inlined \_\_LINE\_\_
>  
>  This problem is related to hotpatch construction
>  and potentially has influence on the design of the hotpatching
> @@ -1030,7 +981,7 @@ Options:
>  For BUG(), WARN(), etc., the line number is embedded into the bug frame, not
>  the function itself.
>  
> -Similar considerations are true to a lesser extent for __FILE__, but it
> +Similar considerations are true to a lesser extent for \_\_FILE\_\_, but it
>  could be argued that file renaming should be done outside of hotpatches.
>  
>  ## Signature checking requirements.
> @@ -1042,49 +993,46 @@ expecting such that it can properly do signature verification.
>  
>  The signature is based on the all of the payloads continuously laid out
>  in memory. The signature is to be appended at the end of the ELF payload
> -prefixed with the string `'~Module signature appended~\n'`, followed by
> +prefixed with the string '`~Module signature appended~\n`', followed by
>  an signature header then followed by the signature, key identifier, and signers
>  name.
>  
>  Specifically the signature header would be:
>  
> -<pre>
> -#define PKEY_ALGO_DSA       0  
> -#define PKEY_ALGO_RSA       1  
> -
> -#define PKEY_ID_PGP         0 /* OpenPGP generated key ID */  
> -#define PKEY_ID_X509        1 /* X.509 arbitrary subjectKeyIdentifier */  
> -
> -#define HASH_ALGO_MD4          0  
> -#define HASH_ALGO_MD5          1  
> -#define HASH_ALGO_SHA1         2  
> -#define HASH_ALGO_RIPE_MD_160  3  
> -#define HASH_ALGO_SHA256       4  
> -#define HASH_ALGO_SHA384       5  
> -#define HASH_ALGO_SHA512       6  
> -#define HASH_ALGO_SHA224       7  
> -#define HASH_ALGO_RIPE_MD_128  8  
> -#define HASH_ALGO_RIPE_MD_256  9  
> -#define HASH_ALGO_RIPE_MD_320 10  
> -#define HASH_ALGO_WP_256      11  
> -#define HASH_ALGO_WP_384      12  
> -#define HASH_ALGO_WP_512      13  
> -#define HASH_ALGO_TGR_128     14  
> -#define HASH_ALGO_TGR_160     15  
> -#define HASH_ALGO_TGR_192     16  
> -
> -
> -struct elf_payload_signature {  
> -	u8	algo;		/* Public-key crypto algorithm PKEY_ALGO_*. */  
> -	u8	hash;		/* Digest algorithm: HASH_ALGO_*. */  
> -	u8	id_type;	/* Key identifier type PKEY_ID*. */  
> -	u8	signer_len;	/* Length of signer's name */  
> -	u8	key_id_len;	/* Length of key identifier */  
> -	u8	__pad[3];  
> -	__be32	sig_len;	/* Length of signature data */  
> -};
> -
> -</pre>
> +    #define PKEY_ALGO_DSA       0
> +    #define PKEY_ALGO_RSA       1
> +
> +    #define PKEY_ID_PGP         0 /* OpenPGP generated key ID */
> +    #define PKEY_ID_X509        1 /* X.509 arbitrary subjectKeyIdentifier */
> +
> +    #define HASH_ALGO_MD4          0
> +    #define HASH_ALGO_MD5          1
> +    #define HASH_ALGO_SHA1         2
> +    #define HASH_ALGO_RIPE_MD_160  3
> +    #define HASH_ALGO_SHA256       4
> +    #define HASH_ALGO_SHA384       5
> +    #define HASH_ALGO_SHA512       6
> +    #define HASH_ALGO_SHA224       7
> +    #define HASH_ALGO_RIPE_MD_128  8
> +    #define HASH_ALGO_RIPE_MD_256  9
> +    #define HASH_ALGO_RIPE_MD_320 10
> +    #define HASH_ALGO_WP_256      11
> +    #define HASH_ALGO_WP_384      12
> +    #define HASH_ALGO_WP_512      13
> +    #define HASH_ALGO_TGR_128     14
> +    #define HASH_ALGO_TGR_160     15
> +    #define HASH_ALGO_TGR_192     16
> +
> +    struct elf_payload_signature {
> +	    u8	algo;		/* Public-key crypto algorithm PKEY_ALGO_*. */
> +	    u8	hash;		/* Digest algorithm: HASH_ALGO_*. */
> +	    u8	id_type;	/* Key identifier type PKEY_ID*. */
> +	    u8	signer_len;	/* Length of signer's name */
> +	    u8	key_id_len;	/* Length of key identifier */
> +	    u8	__pad[3];
> +	    __be32	sig_len;	/* Length of signature data */
> +    };
> +
>  (Note that this has been borrowed from Linux module signature code.).
>  
>  
> @@ -1128,15 +1076,14 @@ at least five bytes if patching in trampoline.
>  Depending on compiler settings, there are several functions in Xen that
>  are smaller (without inter-function padding).
>  
> -<pre> 
> -readelf -sW xen-syms | grep " FUNC " | \
> -    awk '{ if ($3 < 5) print $3, $4, $5, $8 }'
> +    readelf -sW xen-syms | grep " FUNC " | \
> +        awk '{ if ($3 < 5) print $3, $4, $5, $8 }'
> +
> +    ...
> +    3 FUNC LOCAL wbinvd_ipi
> +    3 FUNC LOCAL shadow_l1_index
> +    ...
>  
> -...
> -3 FUNC LOCAL wbinvd_ipi
> -3 FUNC LOCAL shadow_l1_index
> -...
> -</pre>
>  A compile-time check for, e.g., a minimum alignment of functions or a
>  runtime check that verifies symbol size (+ padding to next symbols) for
>  that in the hypervisor is advised.


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel

Re: [PATCH for-4.11 v3.5 1/2] doc: correct livepatch.markdown syntax

[Wei Liu]

On Fri, May 18, 2018 at 06:35:07PM +0100, Andrew Cooper wrote:
> Sorry - it appears I mess the CC list up here.  CC'ing "The Rest" for
> this combined fixup and cleanup patch for livepatch.markdown, for
> inclusion into 4.11

Acked-by: Wei Liu <wei.liu2@citrix.com>

(I haven't reviewed the content in detail)

Wei.

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel

Re: [PATCH v3 1/2] doc: correct livepatch.markdown syntax

[George Dunlap]

On 05/08/2018 07:47 AM, Juergen Gross wrote:
> "make -C docs all" fails due to incorrect markdown syntax in
> livepatch.markdown. Correct it.
> 
> Signed-off-by: Juergen Gross <jgross@suse.com>
> Reviewed-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>

Git complains of trailing whitespace:

Importing patch "doc-correct-livepatch-markdown" ... <stdin>:69:
trailing whitespace.

<stdin>:72: trailing whitespace.

<stdin>:98: trailing whitespace.

<stdin>:232: trailing whitespace.

<stdin>:238: trailing whitespace.

Checking patch docs/misc/livepatch.markdown...
Applied patch docs/misc/livepatch.markdown cleanly.
warning: squelched 13 whitespace errors
warning: 18 lines add whitespace errors.


> ---
>  docs/misc/livepatch.markdown | 590 ++++++++++++++++++++-----------------------
>  1 file changed, 273 insertions(+), 317 deletions(-)
> 
> diff --git a/docs/misc/livepatch.markdown b/docs/misc/livepatch.markdown
> index 54a6b850cb..a4de44472a 100644
> --- a/docs/misc/livepatch.markdown
> +++ b/docs/misc/livepatch.markdown
> @@ -89,33 +89,27 @@ As example we will assume the hypervisor does not have XSA-132 (see
>  4ff3449f0e9d175ceb9551d3f2aecb59273f639d) and we would like to binary patch
>  the hypervisor with it. The original code looks as so:
>  
> -<pre>
> -   48 89 e0                  mov    %rsp,%rax  
> -   48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax  
> -</pre>
> +       48 89 e0                  mov    %rsp,%rax
> +       48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax
>  
>  while the new patched hypervisor would be:
>  
> -<pre>
> -   48 c7 45 b8 00 00 00 00   movq   $0x0,-0x48(%rbp)  
> -   48 c7 45 c0 00 00 00 00   movq   $0x0,-0x40(%rbp)  
> -   48 c7 45 c8 00 00 00 00   movq   $0x0,-0x38(%rbp)  
> -   48 89 e0                  mov    %rsp,%rax  
> -   48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax  
> -</pre>
> +       48 c7 45 b8 00 00 00 00   movq   $0x0,-0x48(%rbp)
> +       48 c7 45 c0 00 00 00 00   movq   $0x0,-0x40(%rbp)
> +       48 c7 45 c8 00 00 00 00   movq   $0x0,-0x38(%rbp)
> +       48 89 e0                  mov    %rsp,%rax
> +       48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax
>  
> -This is inside the arch_do_domctl. This new change adds 21 extra
> +This is inside the arch\_do\_domctl. This new change adds 21 extra

It seems like nearly all of these would be better served by making them
code blocks ( `arch_do_domctl`). It is:
* easier to read in text format (one of the  main points of markdown),
* fewer characters to type,
* looks better rendered into html or pdf, and
* doesn't require &lt; &gt; tags for < and >.

 -George

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel

Re: [PATCH v3 1/2] doc: correct livepatch.markdown syntax

[Konrad Rzeszutek Wilk]

On Tue, May 08, 2018 at 11:51:47AM +0100, George Dunlap wrote:
> On 05/08/2018 07:47 AM, Juergen Gross wrote:
> > "make -C docs all" fails due to incorrect markdown syntax in
> > livepatch.markdown. Correct it.
> > 
> > Signed-off-by: Juergen Gross <jgross@suse.com>
> > Reviewed-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
> 
> Git complains of trailing whitespace:
> 
> Importing patch "doc-correct-livepatch-markdown" ... <stdin>:69:
> trailing whitespace.
> 
> <stdin>:72: trailing whitespace.
> 
> <stdin>:98: trailing whitespace.
> 
> <stdin>:232: trailing whitespace.
> 
> <stdin>:238: trailing whitespace.

That is on purpose. That is you need those two spaces at the end to force
it to stay in 'code' mode.

> 
> Checking patch docs/misc/livepatch.markdown...
> Applied patch docs/misc/livepatch.markdown cleanly.
> warning: squelched 13 whitespace errors
> warning: 18 lines add whitespace errors.
> 
> 
> > ---
> >  docs/misc/livepatch.markdown | 590 ++++++++++++++++++++-----------------------
> >  1 file changed, 273 insertions(+), 317 deletions(-)
> > 
> > diff --git a/docs/misc/livepatch.markdown b/docs/misc/livepatch.markdown
> > index 54a6b850cb..a4de44472a 100644
> > --- a/docs/misc/livepatch.markdown
> > +++ b/docs/misc/livepatch.markdown
> > @@ -89,33 +89,27 @@ As example we will assume the hypervisor does not have XSA-132 (see
> >  4ff3449f0e9d175ceb9551d3f2aecb59273f639d) and we would like to binary patch
> >  the hypervisor with it. The original code looks as so:
> >  
> > -<pre>
> > -   48 89 e0                  mov    %rsp,%rax  
> > -   48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax  
> > -</pre>
> > +       48 89 e0                  mov    %rsp,%rax
> > +       48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax
> >  
> >  while the new patched hypervisor would be:
> >  
> > -<pre>
> > -   48 c7 45 b8 00 00 00 00   movq   $0x0,-0x48(%rbp)  
> > -   48 c7 45 c0 00 00 00 00   movq   $0x0,-0x40(%rbp)  
> > -   48 c7 45 c8 00 00 00 00   movq   $0x0,-0x38(%rbp)  
> > -   48 89 e0                  mov    %rsp,%rax  
> > -   48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax  
> > -</pre>
> > +       48 c7 45 b8 00 00 00 00   movq   $0x0,-0x48(%rbp)
> > +       48 c7 45 c0 00 00 00 00   movq   $0x0,-0x40(%rbp)
> > +       48 c7 45 c8 00 00 00 00   movq   $0x0,-0x38(%rbp)
> > +       48 89 e0                  mov    %rsp,%rax
> > +       48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax
> >  
> > -This is inside the arch_do_domctl. This new change adds 21 extra
> > +This is inside the arch\_do\_domctl. This new change adds 21 extra
> 
> It seems like nearly all of these would be better served by making them
> code blocks ( `arch_do_domctl`). It is:
> * easier to read in text format (one of the  main points of markdown),
> * fewer characters to type,
> * looks better rendered into html or pdf, and
> * doesn't require &lt; &gt; tags for < and >.
> 
>  -George

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel

Re: [PATCH v3 1/2] doc: correct livepatch.markdown syntax

[Andrew Cooper]

On 11/05/18 18:56, Konrad Rzeszutek Wilk wrote:
> On Tue, May 08, 2018 at 11:51:47AM +0100, George Dunlap wrote:
>> On 05/08/2018 07:47 AM, Juergen Gross wrote:
>>> "make -C docs all" fails due to incorrect markdown syntax in
>>> livepatch.markdown. Correct it.
>>>
>>> Signed-off-by: Juergen Gross <jgross@suse.com>
>>> Reviewed-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
>> Git complains of trailing whitespace:
>>
>> Importing patch "doc-correct-livepatch-markdown" ... <stdin>:69:
>> trailing whitespace.
>>
>> <stdin>:72: trailing whitespace.
>>
>> <stdin>:98: trailing whitespace.
>>
>> <stdin>:232: trailing whitespace.
>>
>> <stdin>:238: trailing whitespace.
> That is on purpose. That is you need those two spaces at the end to force
> it to stay in 'code' mode.

Please see my 3.5 which does a load of cleanup.  I've deleted all
trailing whitespace and the end result renders correctly in HTML and PDF.

~Andrew

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel

[PATCH v3 2/2] doc: correct intel_psr_cat_cdp.pandoc syntax

[Juergen Gross]

"make -C docs all" fails due to incorrect markdown syntax in
intel_psr_cat_cdp.pandoc. Correct it.

Signed-off-by: Juergen Gross <jgross@suse.com>
---
 docs/features/intel_psr_cat_cdp.pandoc | 562 ++++++++++++++++++---------------
 1 file changed, 300 insertions(+), 262 deletions(-)

diff --git a/docs/features/intel_psr_cat_cdp.pandoc b/docs/features/intel_psr_cat_cdp.pandoc
index 04fb256dd9..a076e8a755 100644
--- a/docs/features/intel_psr_cat_cdp.pandoc
+++ b/docs/features/intel_psr_cat_cdp.pandoc
@@ -1,5 +1,5 @@
 % Intel Cache Allocation Technology and Code and Data Prioritization Features
-% Revision 1.16
+% Revision 1.17
 
 \clearpage
 
@@ -35,64 +35,71 @@ Technology (CAT) and Code and Data Prioritization (CDP).
 CAT allows an OS or hypervisor to control allocation of a CPU's shared cache
 based on application/domain priority or Class of Service (COS). Each COS is
 configured using capacity bitmasks (CBMs) which represent cache capacity and
-indicate the degree of overlap and isolation between classes. Once CAT is co-
-nfigured, the processor allows access to portions of cache according to the
+indicate the degree of overlap and isolation between classes. Once CAT is
+configured, the processor allows access to portions of cache according to the
 established COS. Intel Xeon processor E5 v4 family (and some others) introduce
 capabilities to configure and make use of the CAT mechanism on the L3 cache.
 Intel Goldmont processor provides support for control over the L2 cache.
 
 Code and Data Prioritization (CDP) Technology is an extension of CAT. CDP
 enables isolation and separate prioritization of code and data fetches to
-the L3 cache in a SW configurable manner, which can enable workload priorit-
-ization and tuning of cache capacity to the characteristics of the workload.
-CDP extends CAT by providing separate code and data masks per Class of Service
-(COS). When SW configures to enable CDP, L3 CAT is disabled.
+the L3 cache in a SW configurable manner, which can enable workload
+prioritization and tuning of cache capacity to the characteristics of the
+workload. CDP extends CAT by providing separate code and data masks per Class
+of Service (COS). When SW configures to enable CDP, L3 CAT is disabled.
 
 # User details
 
 * Feature Enabling:
 
-  Add "psr=cat" to boot line parameter to enable all supported level CAT featu-
-  res. Add "psr=cdp" to enable L3 CDP but disables L3 CAT by SW.
+    Add "psr=cat" to boot line parameter to enable all supported level CAT
+    features. Add "psr=cdp" to enable L3 CDP but disables L3 CAT by SW.
 
 * xl interfaces:
 
-  1. `psr-cat-show [OPTIONS] domain-id`:
+    1. `psr-cat-show [OPTIONS] domain-id`:
 
-     Show L2 CAT or L3 CAT/CDP CBM of the domain designated by Xen domain-id.
+        Show L2 CAT or L3 CAT/CDP CBM of the domain designated by Xen domain-id.
 
-     Option `-l`:
-     `-l2`: Show cbm for L2 cache.
-     `-l3`: Show cbm for L3 cache.
+        Option `-l`:
 
-     If `-lX` is specified and LX is not supported, print error.
-     If no `-l` is specified, level 3 is the default option.
+        `-l2`: Show cbm for L2 cache.
 
-  2. `psr-cat-set [OPTIONS] domain-id cbm`:
+        `-l3`: Show cbm for L3 cache.
 
-     Set L2 CAT or L3 CAT/CDP CBM to the domain designated by Xen domain-id.
+        If `-lX` is specified and LX is not supported, print error.
+        If no `-l` is specified, level 3 is the default option.
 
-     Option `-s`: Specify the socket to process, otherwise all sockets are
-     processed.
+    2. `psr-cat-set [OPTIONS] domain-id cbm`:
 
-     Option `-l`:
-     `-l2`: Specify cbm for L2 cache.
-     `-l3`: Specify cbm for L3 cache.
+        Set L2 CAT or L3 CAT/CDP CBM to the domain designated by Xen domain-id.
 
-     If `-lX` is specified and LX is not supported, print error.
-     If no `-l` is specified, level 3 is the default option.
+        Option `-s`: Specify the socket to process, otherwise all sockets are
+        processed.
 
-     Option `-c` or `-d`:
-     `-c`: Set L3 CDP code cbm.
-     `-d`: Set L3 CDP data cbm.
+        Option `-l`:
 
-  3. `psr-hwinfo [OPTIONS]`:
+        `-l2`: Specify cbm for L2 cache.
 
-     Show CMT & L2 CAT & L3 CAT/CDP HW information on every socket.
+        `-l3`: Specify cbm for L3 cache.
 
-     Option `-m, --cmt`: Show Cache Monitoring Technology (CMT) hardware info.
+        If `-lX` is specified and LX is not supported, print error.
+        If no `-l` is specified, level 3 is the default option.
 
-     Option `-a, --cat`: Show CAT/CDP hardware info.
+        Option `-c` or `-d`:
+
+        `-c`: Set L3 CDP code cbm.
+
+        `-d`: Set L3 CDP data cbm.
+
+    3. `psr-hwinfo [OPTIONS]`:
+
+        Show CMT & L2 CAT & L3 CAT/CDP HW information on every socket.
+
+        Option `-m, --cmt`: Show Cache Monitoring Technology (CMT) hardware
+        info.
+
+        Option `-a, --cat`: Show CAT/CDP hardware info.
 
 # Technical details
 
@@ -101,305 +108,307 @@ PSR infrastructure in Xen.
 
 ## Hardware perspective
 
-  CAT/CDP defines a range of MSRs to assign different cache access patterns
-  which are known as CBMs, each CBM is associated with a COS.
-
-  ```
-  E.g. L2 CAT:
-                          +----------------------------+----------------+
-     IA32_PQR_ASSOC       | MSR (per socket)           |    Address     |
-   +----+---+-------+     +----------------------------+----------------+
-   |    |COS|       |     | IA32_L2_QOS_MASK_0         |     0xD10      |
-   +----+---+-------+     +----------------------------+----------------+
-          +-------------> | ...                        |  ...           |
-                          +----------------------------+----------------+
-                          | IA32_L2_QOS_MASK_n         | 0xD10+n (n<64) |
-                          +----------------------------+----------------+
-  ```
-
-  L3 CAT/CDP uses a range of MSRs from 0xC90 ~ 0xC90+n (n<128).
-
-  L2 CAT uses a range of MSRs from 0xD10 ~ 0xD10+n (n<64), following the L3
-  CAT/CDP MSRs, setting different L2 cache accessing patterns from L3 cache is
-  supported.
-
-  Every MSR stores a CBM value. A capacity bitmask (CBM) provides a hint to the
-  hardware indicating the cache space a domain should be limited to as well as
-  providing an indication of overlap and isolation in the CAT-capable cache from
-  other domains contending for the cache.
-
-  Sample cache capacity bitmasks for a bitlength of 8 are shown below. Please
-  note that all (and only) contiguous '1' combinations are allowed (e.g. FFFFH,
-  0FF0H, 003CH, etc.).
-
-  ```
-       +----+----+----+----+----+----+----+----+
-       | M7 | M6 | M5 | M4 | M3 | M2 | M1 | M0 |
-       +----+----+----+----+----+----+----+----+
-  COS0 | A  | A  | A  | A  | A  | A  | A  | A  | Default Bitmask
-       +----+----+----+----+----+----+----+----+
-  COS1 | A  | A  | A  | A  | A  | A  | A  | A  |
-       +----+----+----+----+----+----+----+----+
-  COS2 | A  | A  | A  | A  | A  | A  | A  | A  |
-       +----+----+----+----+----+----+----+----+
-
-       +----+----+----+----+----+----+----+----+
-       | M7 | M6 | M5 | M4 | M3 | M2 | M1 | M0 |
-       +----+----+----+----+----+----+----+----+
-  COS0 | A  | A  | A  | A  | A  | A  | A  | A  | Overlapped Bitmask
-       +----+----+----+----+----+----+----+----+
-  COS1 |    |    |    |    | A  | A  | A  | A  |
-       +----+----+----+----+----+----+----+----+
-  COS2 |    |    |    |    |    |    | A  | A  |
-       +----+----+----+----+----+----+----+----+
-
-       +----+----+----+----+----+----+----+----+
-       | M7 | M6 | M5 | M4 | M3 | M2 | M1 | M0 |
-       +----+----+----+----+----+----+----+----+
-  COS0 | A  | A  | A  | A  |    |    |    |    | Isolated Bitmask
-       +----+----+----+----+----+----+----+----+
-  COS1 |    |    |    |    | A  | A  |    |    |
-       +----+----+----+----+----+----+----+----+
-  COS2 |    |    |    |    |    |    | A  | A  |
-       +----+----+----+----+----+----+----+----+
-  ```
-
-  We can get the CBM length through CPUID. The default value of CBM is calcul-
-  ated by `(1ull << cbm_len) - 1`. That is a fully open bitmask, all ones bitm-
-  ask. The COS[0] always stores the default value without change.
-
-  There is a `IA32_PQR_ASSOC` register which stores the COS ID of the VCPU. HW
-  enforces cache allocation according to the corresponding CBM.
+CAT/CDP defines a range of MSRs to assign different cache access patterns
+which are known as CBMs, each CBM is associated with a COS.
+
+E.g. L2 CAT:
+
+                            +----------------------------+----------------+
+       IA32_PQR_ASSOC       | MSR (per socket)           |    Address     |
+     +----+---+-------+     +----------------------------+----------------+
+     |    |COS|       |     | IA32_L2_QOS_MASK_0         |     0xD10      |
+     +----+---+-------+     +----------------------------+----------------+
+            +-------------> | ...                        |  ...           |
+                            +----------------------------+----------------+
+                            | IA32_L2_QOS_MASK_n         | 0xD10+n (n<64) |
+                            +----------------------------+----------------+
+
+L3 CAT/CDP uses a range of MSRs from 0xC90 ~ 0xC90+n (n<128).
+
+L2 CAT uses a range of MSRs from 0xD10 ~ 0xD10+n (n<64), following the L3
+CAT/CDP MSRs, setting different L2 cache accessing patterns from L3 cache is
+supported.
+
+Every MSR stores a CBM value. A capacity bitmask (CBM) provides a hint to the
+hardware indicating the cache space a domain should be limited to as well as
+providing an indication of overlap and isolation in the CAT-capable cache from
+other domains contending for the cache.
+
+Sample cache capacity bitmasks for a bitlength of 8 are shown below. Please
+note that all (and only) contiguous '1' combinations are allowed (e.g. FFFFH,
+0FF0H, 003CH, etc.).
+
+           +----+----+----+----+----+----+----+----+
+           | M7 | M6 | M5 | M4 | M3 | M2 | M1 | M0 |
+           +----+----+----+----+----+----+----+----+
+      COS0 | A  | A  | A  | A  | A  | A  | A  | A  | Default Bitmask
+           +----+----+----+----+----+----+----+----+
+      COS1 | A  | A  | A  | A  | A  | A  | A  | A  |
+           +----+----+----+----+----+----+----+----+
+      COS2 | A  | A  | A  | A  | A  | A  | A  | A  |
+           +----+----+----+----+----+----+----+----+
+    
+           +----+----+----+----+----+----+----+----+
+           | M7 | M6 | M5 | M4 | M3 | M2 | M1 | M0 |
+           +----+----+----+----+----+----+----+----+
+      COS0 | A  | A  | A  | A  | A  | A  | A  | A  | Overlapped Bitmask
+           +----+----+----+----+----+----+----+----+
+      COS1 |    |    |    |    | A  | A  | A  | A  |
+           +----+----+----+----+----+----+----+----+
+      COS2 |    |    |    |    |    |    | A  | A  |
+           +----+----+----+----+----+----+----+----+
+    
+           +----+----+----+----+----+----+----+----+
+           | M7 | M6 | M5 | M4 | M3 | M2 | M1 | M0 |
+           +----+----+----+----+----+----+----+----+
+      COS0 | A  | A  | A  | A  |    |    |    |    | Isolated Bitmask
+           +----+----+----+----+----+----+----+----+
+      COS1 |    |    |    |    | A  | A  |    |    |
+           +----+----+----+----+----+----+----+----+
+      COS2 |    |    |    |    |    |    | A  | A  |
+           +----+----+----+----+----+----+----+----+
+
+We can get the CBM length through CPUID. The default value of CBM is calculated
+by `(1ull << cbm_len) - 1`. That is a fully open bitmask, all ones bitmask.
+The COS\[0\] always stores the default value without change.
+
+There is a `IA32_PQR_ASSOC` register which stores the COS ID of the VCPU. HW
+enforces cache allocation according to the corresponding CBM.
 
 ## The relationship between L3 CAT/CDP and L2 CAT
 
-  HW may support all features. By default, CDP is disabled on the processor.
-  If the L3 CAT MSRs are used without enabling CDP, the processor operates in
-  a traditional CAT-only mode. When CDP is enabled:
-  * the CAT mask MSRs are re-mapped into interleaved pairs of mask MSRs for
-    data or code fetches.
-  * the range of COS for CAT is re-indexed, with the lower-half of the COS
-    range available for CDP.
+HW may support all features. By default, CDP is disabled on the processor.
+If the L3 CAT MSRs are used without enabling CDP, the processor operates in
+a traditional CAT-only mode. When CDP is enabled:
 
-  L2 CAT is independent of L3 CAT/CDP, which means L2 CAT can be enabled while
-  L3 CAT/CDP is disabled, or L2 CAT and L3 CAT/CDP are both enabled.
+* the CAT mask MSRs are re-mapped into interleaved pairs of mask MSRs for
+  data or code fetches.
 
-  As a requirement, the bits of CBM of CAT/CDP must be continuous.
+* the range of COS for CAT is re-indexed, with the lower-half of the COS
+  range available for CDP.
 
-  N.B. L2 CAT and L3 CAT/CDP share the same COS field in the same associate
-  register `IA32_PQR_ASSOC`, which means one COS is associated with a pair of
-  L2 CAT CBM and L3 CAT/CDP CBM.
+L2 CAT is independent of L3 CAT/CDP, which means L2 CAT can be enabled while
+L3 CAT/CDP is disabled, or L2 CAT and L3 CAT/CDP are both enabled.
 
-  Besides, the max COS of L2 CAT may be different from L3 CAT/CDP (or other
-  PSR features in future). In some cases, a domain is permitted to have a COS
-  that is beyond one (or more) of PSR features but within the others. For
-  instance, let's assume the max COS of L2 CAT is 8 but the max COS of L3
-  CAT is 16, when a domain is assigned 9 as COS, the L3 CAT CBM associated to
-  COS 9 would be enforced, but for L2 CAT, the HW works as default value is
-  set since COS 9 is beyond the max COS (8) of L2 CAT.
+As a requirement, the bits of CBM of CAT/CDP must be continuous.
+
+N.B. L2 CAT and L3 CAT/CDP share the same COS field in the same associate
+register `IA32_PQR_ASSOC`, which means one COS is associated with a pair of
+L2 CAT CBM and L3 CAT/CDP CBM.
+
+Besides, the max COS of L2 CAT may be different from L3 CAT/CDP (or other
+PSR features in future). In some cases, a domain is permitted to have a COS
+that is beyond one (or more) of PSR features but within the others. For
+instance, let's assume the max COS of L2 CAT is 8 but the max COS of L3
+CAT is 16, when a domain is assigned 9 as COS, the L3 CAT CBM associated to
+COS 9 would be enforced, but for L2 CAT, the HW works as default value is
+set since COS 9 is beyond the max COS (8) of L2 CAT.
 
 ## Design Overview
 
 * Core COS/CBM association
 
-  When enforcing CAT/CDP, all cores of domains have the same default COS (COS0)
-  which is associated with the fully open CBM (all ones bitmask) to access all
-  cache. The default COS is used only in hypervisor and is transparent to tool
-  stack and user.
+    When enforcing CAT/CDP, all cores of domains have the same default COS
+    (COS0) which is associated with the fully open CBM (all ones bitmask) to
+    access all cache. The default COS is used only in hypervisor and is
+    transparent to tool stack and user.
 
-  System administrator can change PSR allocation policy at runtime by tool stack.
-  Since L2 CAT shares COS with L3 CAT/CDP, a COS corresponds to a 2-tuple, like
-  [L2 CBM, L3 CBM] with only-CAT enabled, when CDP is enabled, one COS correspo-
-  nds to a 3-tuple, like [L2 CBM, L3 Code_CBM, L3 Data_CBM]. If neither L3 CAT
-  nor L3 CDP is enabled, things would be easier, one COS corresponds to one L2
-  CBM.
+    System administrator can change PSR allocation policy at runtime by tool
+    stack. Since L2 CAT shares COS with L3 CAT/CDP, a COS corresponds to a
+    2-tuple, like \[L2 CBM, L3 CBM\] with only-CAT enabled, when CDP is
+    enabled, one COS corresponds to a 3-tuple, like \[L2 CBM, L3 Code_CBM,
+    L3 Data_CBM\]. If neither L3 CAT nor L3 CDP is enabled, things would be
+    easier, one COS corresponds to one L2 CBM.
 
 * VCPU schedule
 
-  When context switch happens, the COS of VCPU is written to per-thread MSR
-  `IA32_PQR_ASSOC`, and then hardware enforces cache allocation according to
-  the corresponding CBM.
+    When context switch happens, the COS of VCPU is written to per-thread MSR
+    `IA32_PQR_ASSOC`, and then hardware enforces cache allocation according to
+    the corresponding CBM.
 
 * Multi-sockets
 
-  Different sockets may have different CAT/CDP capability (e.g. max COS) alth-
-  ough it is consistent on the same socket. So the capability of per-socket CAT/
-  CDP is specified.
+    Different sockets may have different CAT/CDP capability (e.g. max COS)
+    although it is consistent on the same socket. So the capability of
+    per-socket CAT/CDP is specified.
 
-  'psr-cat-set' can set CBM for one domain per socket. On each socket, we main-
-  tain a COS array for all domains. One domain uses one COS at one time. One COS
-  stores the CBM of the domain to work. So, when a VCPU of the domain is migrat-
-  ed from socket 1 to socket 2, it follows configuration on socket 2.
+    'psr-cat-set' can set CBM for one domain per socket. On each socket, we
+    maintain a COS array for all domains. One domain uses one COS at one time.
+    One COS stores the CBM of the domain to work. So, when a VCPU of the domain
+    is migrated from socket 1 to socket 2, it follows configuration on socket 2.
 
-  E.g. user sets domain 1 CBM on socket 1 to 0x7f which uses COS 9 but sets do-
-  main 1 CBM on socket 2 to 0x3f which uses COS 7. When VCPU of this domain
-  is migrated from socket 1 to 2, the COS ID used is 7, that means 0x3f is the
-  CBM to work for this domain 1 now.
+    E.g. user sets domain 1 CBM on socket 1 to 0x7f which uses COS 9 but sets
+    domain 1 CBM on socket 2 to 0x3f which uses COS 7. When VCPU of this domain
+    is migrated from socket 1 to 2, the COS ID used is 7, that means 0x3f is the
+    CBM to work for this domain 1 now.
 
 ## Implementation Description
 
 * Hypervisor interfaces:
 
-  1. Boot line parameter "psr=cat" enables L2 CAT and L3 CAT if hardware suppo-
-     rted. "psr=cdp" enables CDP if hardware supported.
+    1. Boot line parameter "psr=cat" enables L2 CAT and L3 CAT if hardware
+       supported. "psr=cdp" enables CDP if hardware supported.
+
+    2. SYSCTL:
 
-  2. SYSCTL:
-          - XEN_SYSCTL_PSR_CAT_get_l3_info: Get L3 CAT/CDP information.
-          - XEN_SYSCTL_PSR_CAT_get_l2_info: Get L2 CAT information.
+        * XEN_SYSCTL_PSR_CAT_get_l3_info: Get L3 CAT/CDP information.
+        * XEN_SYSCTL_PSR_CAT_get_l2_info: Get L2 CAT information.
 
-  3. DOMCTL:
-          - XEN_DOMCTL_PSR_CAT_OP_GET_L3_CBM: Get L3 CBM for a domain.
-          - XEN_DOMCTL_PSR_CAT_OP_SET_L3_CBM: Set L3 CBM for a domain.
-          - XEN_DOMCTL_PSR_CAT_OP_GET_L3_CODE: Get CDP Code CBM for a domain.
-          - XEN_DOMCTL_PSR_CAT_OP_SET_L3_CODE: Set CDP Code CBM for a domain.
-          - XEN_DOMCTL_PSR_CAT_OP_GET_L3_DATA: Get CDP Data CBM for a domain.
-          - XEN_DOMCTL_PSR_CAT_OP_SET_L3_DATA: Set CDP Data CBM for a domain.
-          - XEN_DOMCTL_PSR_CAT_OP_GET_L2_CBM: Get L2 CBM for a domain.
-          - XEN_DOMCTL_PSR_CAT_OP_SET_L2_CBM: Set L2 CBM for a domain.
+    3. DOMCTL:
+
+        * XEN_DOMCTL_PSR_CAT_OP_GET_L3_CBM: Get L3 CBM for a domain.
+        * XEN_DOMCTL_PSR_CAT_OP_SET_L3_CBM: Set L3 CBM for a domain.
+        * XEN_DOMCTL_PSR_CAT_OP_GET_L3_CODE: Get CDP Code CBM for a domain.
+        * XEN_DOMCTL_PSR_CAT_OP_SET_L3_CODE: Set CDP Code CBM for a domain.
+        * XEN_DOMCTL_PSR_CAT_OP_GET_L3_DATA: Get CDP Data CBM for a domain.
+        * XEN_DOMCTL_PSR_CAT_OP_SET_L3_DATA: Set CDP Data CBM for a domain.
+        * XEN_DOMCTL_PSR_CAT_OP_GET_L2_CBM: Get L2 CBM for a domain.
+        * XEN_DOMCTL_PSR_CAT_OP_SET_L2_CBM: Set L2 CBM for a domain.
 
 * xl interfaces:
 
-  1. psr-cat-show -lX domain-id
-          Show LX cbm for a domain.
-          => XEN_SYSCTL_PSR_CAT_get_l3_info    /
-             XEN_SYSCTL_PSR_CAT_get_l2_info    /
-             XEN_DOMCTL_PSR_CAT_OP_GET_L3_CBM  /
-             XEN_DOMCTL_PSR_CAT_OP_GET_L3_CODE /
-             XEN_DOMCTL_PSR_CAT_OP_GET_L3_DATA /
-             XEN_DOMCTL_PSR_CAT_OP_GET_L2_CBM
-
-  2. psr-cat-set -lX domain-id cbm
-          Set LX cbm for a domain.
-          => XEN_DOMCTL_PSR_CAT_OP_SET_L3_CBM  /
-             XEN_DOMCTL_PSR_CAT_OP_SET_L3_CODE /
-             XEN_DOMCTL_PSR_CAT_OP_SET_L3_DATA /
-             XEN_DOMCTL_PSR_CAT_OP_SET_L2_CBM
-
-  3. psr-hwinfo
-          Show PSR HW information, including L3 CAT/CDP/L2 CAT
-          => XEN_SYSCTL_PSR_CAT_get_l3_info /
-             XEN_SYSCTL_PSR_CAT_get_l2_info
+    1. psr-cat-show -lX domain-id
+
+        Show LX cbm for a domain.
+
+                => XEN_SYSCTL_PSR_CAT_get_l3_info    /
+                   XEN_SYSCTL_PSR_CAT_get_l2_info    /
+                   XEN_DOMCTL_PSR_CAT_OP_GET_L3_CBM  /
+                   XEN_DOMCTL_PSR_CAT_OP_GET_L3_CODE /
+                   XEN_DOMCTL_PSR_CAT_OP_GET_L3_DATA /
+                   XEN_DOMCTL_PSR_CAT_OP_GET_L2_CBM
+
+    2. psr-cat-set -lX domain-id cbm
+
+        Set LX cbm for a domain.
+
+                => XEN_DOMCTL_PSR_CAT_OP_SET_L3_CBM  /
+                   XEN_DOMCTL_PSR_CAT_OP_SET_L3_CODE /
+                   XEN_DOMCTL_PSR_CAT_OP_SET_L3_DATA /
+                   XEN_DOMCTL_PSR_CAT_OP_SET_L2_CBM
+
+    3. psr-hwinfo
+
+        Show PSR HW information, including L3 CAT/CDP/L2 CAT
+
+                => XEN_SYSCTL_PSR_CAT_get_l3_info /
+                   XEN_SYSCTL_PSR_CAT_get_l2_info
 
 * Key data structure:
 
-   1. Feature properties
+    1. Feature properties
 
-      ```
-      static const struct feat_props {
-          unsigned int cos_num;
-          enum cbm_type type[PSR_MAX_COS_NUM];
-          enum cbm_type alt_type;
-          bool (*get_feat_info)(const struct feat_node *feat,
-                                uint32_t data[], unsigned int array_len);
-          void (*write_msr)(unsigned int cos, uint32_t val, enum cbm_type type);
-      } *feat_props[PSR_SOCKET_FEAT_NUM];
-      ```
+            static const struct feat_props {
+                unsigned int cos_num;
+                enum cbm_type type[PSR_MAX_COS_NUM];
+                enum cbm_type alt_type;
+                bool (*get_feat_info)(const struct feat_node *feat,
+                                      uint32_t data[], unsigned int array_len);
+                void (*write_msr)(unsigned int cos, uint32_t val,
+                                  enum cbm_type type);
+            } *feat_props[PSR_SOCKET_FEAT_NUM];
 
-      Every feature has its own properties, e.g. some data and actions. A
-      feature property pointer array is declared to save every feature's
-      properties.
+        Every feature has its own properties, e.g. some data and actions. A
+        feature property pointer array is declared to save every feature's
+        properties.
 
-      - Member `cos_num`
+        * Member `cos_num`
 
-        `cos_num` is the number of COS registers the feature uses, e.g. L3/L2
-        CAT uses 1 register but CDP uses 2 registers.
+            `cos_num` is the number of COS registers the feature uses, e.g.
+            L3/L2 CAT uses 1 register but CDP uses 2 registers.
 
-      - Member `type`
+        * Member `type`
 
-        `type` is an array to save all 'enum cbm_type' values of the feature.
-        It is used with cos_num together to get/write a feature's COS registers
-        values one by one.
+            `type` is an array to save all 'enum cbm_type' values of the
+            feature. It is used with cos_num together to get/write a feature's
+            COS registers values one by one.
 
-      - Member `alt_type`
+        * Member `alt_type`
 
-        `alt_type` is 'alternative type'. When this 'alt_type' is input, the
-        feature does some special operations.
+            `alt_type` is 'alternative type'. When this 'alt_type' is input,
+            the feature does some special operations.
 
-      - Member `get_feat_info`
+        * Member `get_feat_info`
 
-        `get_feat_info` is used to return feature HW info through sysctl.
+            `get_feat_info` is used to return feature HW info through sysctl.
 
-      - Member `write_msr`
+        * Member `write_msr`
 
-        `write_msr` is used to write out feature MSR register.
+            `write_msr` is used to write out feature MSR register.
 
-   2. Feature node
+    2. Feature node
 
-      ```
-      struct feat_node {
-          unsigned int cos_max;
-          unsigned int cbm_len;
-          uint32_t cos_reg_val[MAX_COS_REG_CNT];
-      };
-      ```
+            struct feat_node {
+                unsigned int cos_max;
+                unsigned int cbm_len;
+                uint32_t cos_reg_val[MAX_COS_REG_CNT];
+            };
 
-      When a PSR enforcement feature is enabled, it will be added into a
-      feature array.
+        When a PSR enforcement feature is enabled, it will be added into a
+        feature array.
 
-      - Member `cos_max`
+        * Member `cos_max`
 
-        `cos_max` is one of the hardware info of CAT. It means the max number
-        of COS registers. As L3 CAT/CDP/L2 CAT all have it, it is declared in
-        `feat_node`.
+            `cos_max` is one of the hardware info of CAT. It means the max
+            number of COS registers. As L3 CAT/CDP/L2 CAT all have it, it is
+            declared in `feat_node`.
 
-      - Member `cbm_len`
+        * Member `cbm_len`
 
-        `cbm_len` is one of the hardware info of CAT. It means the max number
-        of bits to set.
+            `cbm_len` is one of the hardware info of CAT. It means the max
+            number of bits to set.
 
-      - Member `cos_reg_val`
+        * Member `cos_reg_val`
 
-        `cos_reg_val` is an array to maintain the value set in all COS registers
-        of the feature. The array is indexed by COS ID.
+            `cos_reg_val` is an array to maintain the value set in all COS
+            registers of the feature. The array is indexed by COS ID.
 
-   3. Per-socket PSR features information structure
+    3. Per-socket PSR features information structure
 
-      ```
-      struct psr_socket_info {
-          bool feat_init;
-          struct feat_node *features[PSR_SOCKET_FEAT_NUM];
-          spinlock_t ref_lock;
-          unsigned int cos_ref[MAX_COS_REG_CNT];
-          DECLARE_BITMAP(dom_ids, DOMID_IDLE + 1);
-      };
-      ```
+            struct psr_socket_info {
+                bool feat_init;
+                struct feat_node *features[PSR_SOCKET_FEAT_NUM];
+                spinlock_t ref_lock;
+                unsigned int cos_ref[MAX_COS_REG_CNT];
+                DECLARE_BITMAP(dom_ids, DOMID_IDLE + 1);
+            };
 
-      We collect all PSR allocation features information of a socket in this
-      `struct psr_socket_info`.
+        We collect all PSR allocation features information of a socket in this
+        `struct psr_socket_info`.
 
-      - Member `feat_init`
+        * Member `feat_init`
 
-        `feat_init` is a flag, to indicate whether the CPU init on a socket
-        has been done.
+            feat_init` is a flag, to indicate whether the CPU init on a socket
+            has been done.
 
-      - Member `features`
+        * Member `features`
 
-        `features` is a pointer array to save all enabled features poniters
-        according to feature position defined in `enum psr_feat_type`.
+            `features` is a pointer array to save all enabled features pointers
+            according to feature position defined in `enum psr_feat_type`.
 
-      - Member `ref_lock`
+        * Member `ref_lock`
 
-        `ref_lock` is a spin lock to protect `cos_ref`.
+            `ref_lock` is a spin lock to protect `cos_ref`.
 
-      - Member `cos_ref`
+        * Member `cos_ref`
 
-        `cos_ref` is an array which maintains the reference of one COS. It maps
-        to cos_reg_val[MAX_COS_REG_NUM] in `struct feat_node`. If one COS is
-        used by one domain, the corresponding reference will increase by one. If
-        a domain releases the COS, the reference will decrease by one. The array
-        is indexed by COS ID.
+            `cos_ref` is an array which maintains the reference of one COS.
+            It maps to cos_reg_val\[MAX_COS_REG_NUM\] in `struct feat_node`.
+            If one COS is used by one domain, the corresponding reference will
+            increase by one. If a domain releases the COS, the reference will
+            decrease by one. The array is indexed by COS ID.
 
-      - Member `dom_ids`
+        * Member `dom_ids`
 
-        `dom_ids` is a bitmap, every bit corresponds to a domain. Index is
-        domain_id. It is used to help restore the cos_id of the domain to 0 when
-        a socket is offline and then online again.
+            `dom_ids` is a bitmap, every bit corresponds to a domain. Index is
+            domain_id. It is used to help restore the cos_id of the domain to 0
+            when a socket is offline and then online again.
 
 # Limitations
 
 CAT/CDP can only work on HW which enables it(check by CPUID). So far, there is
-no HW which enables both L2 CAT and L3 CAT/CDP. But SW implementation has cons-
-idered such scenario to enable both L2 CAT and L3 CAT/CDP.
+no HW which enables both L2 CAT and L3 CAT/CDP. But SW implementation has
+considered such scenario to enable both L2 CAT and L3 CAT/CDP.
 
 # Testing
 
@@ -407,6 +416,7 @@ We can execute above xl commands to verify L2 CAT and L3 CAT/CDP on different
 HWs support them.
 
 For example:
+
     root@:~$ xl psr-hwinfo --cat
     Cache Allocation Technology (CAT): L2
     Socket ID       : 0
@@ -425,11 +435,11 @@ For example:
 # Areas for improvement
 
 A hexadecimal number is used to set/show CBM for a domain now. Although this
-is convenient to cover overlap/isolated bitmask requirement, it is not user-
-friendly.
+is convenient to cover overlap/isolated bitmask requirement, it is not
+user-friendly.
 
 To improve this, the libxl interfaces can be wrapped in libvirt to provide more
-usr-friendly interfaces to user, e.g. a percentage number of the cache to set
+user-friendly interfaces to user, e.g. a percentage number of the cache to set
 and show.
 
 # Known issues
@@ -446,29 +456,57 @@ N/A
 Date       Revision Version  Notes
 ---------- -------- -------- -------------------------------------------
 2016-08-12 1.0      Xen 4.9  Design document written
+
 2017-02-13 1.7      Xen 4.9  Changes:
+
                              1. Modify the design document to cover L3
                                 CAT/CDP and L2 CAT;
+
                              2. Fix typos;
+
                              3. Amend description of `feat_mask` to make
                                 it clearer;
+
                              4. Other minor changes.
+
 2017-02-15 1.8      Xen 4.9  Changes:
+
                              1. Add content in 'Areas for improvement';
+
                              2. Adjust revision number.
+
 2017-03-16 1.9      Xen 4.9  Changes:
+
                              1. Add 'CMT' in 'Terminology';
+
                              2. Change 'feature list' to 'feature array'.
+
                              3. Modify data structure descriptions.
+
                              4. Adjust revision number.
+
 2017-05-03 1.11     Xen 4.9  Changes:
+
                              1. Modify data structure descriptions.
+
                              2. Adjust revision number.
+
 2017-07-13 1.14     Xen 4.10 Changes:
+
                              1. Fix a typo.
+
 2017-08-01 1.15     Xen 4.10 Changes:
+
                              1. Add 'alt_type' in 'feat_props' structure.
+
 2017-08-04 1.16     Xen 4.10 Changes:
+
                              1. Remove special character which may cause
                                 html creation failure.
+
+2018-05-08 1.17     Xen 4.11 Changes:
+
+                             1. Reformat complete document to enable PDF
+                                creation.
+
 ---------- -------- -------- -------------------------------------------
-- 
2.13.6


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel

Re: [PATCH v3 2/2] doc: correct intel_psr_cat_cdp.pandoc syntax

[George Dunlap]

On 05/08/2018 07:47 AM, Juergen Gross wrote:
> "make -C docs all" fails due to incorrect markdown syntax in
> intel_psr_cat_cdp.pandoc. Correct it.
> 
> Signed-off-by: Juergen Gross <jgross@suse.com>
> ---
>  docs/features/intel_psr_cat_cdp.pandoc | 562 ++++++++++++++++++---------------
>  1 file changed, 300 insertions(+), 262 deletions(-)
> 
> diff --git a/docs/features/intel_psr_cat_cdp.pandoc b/docs/features/intel_psr_cat_cdp.pandoc
> index 04fb256dd9..a076e8a755 100644
> --- a/docs/features/intel_psr_cat_cdp.pandoc
> +++ b/docs/features/intel_psr_cat_cdp.pandoc
> @@ -1,5 +1,5 @@
>  % Intel Cache Allocation Technology and Code and Data Prioritization Features
> -% Revision 1.16
> +% Revision 1.17

Do we really need to bump the revision number just to fix markdown
formatting?

Other than that, looks good to me:

Reviewed-by: George Dunlap <george.dunlap@citrix.com>

(I'm tempted to bikeshed about removing the ```, but I'll refrain.)

 -George

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel

Re: [PATCH v3 2/2] doc: correct intel_psr_cat_cdp.pandoc syntax

[Juergen Gross]

On 08/05/18 14:56, George Dunlap wrote:
> On 05/08/2018 07:47 AM, Juergen Gross wrote:
>> "make -C docs all" fails due to incorrect markdown syntax in
>> intel_psr_cat_cdp.pandoc. Correct it.
>>
>> Signed-off-by: Juergen Gross <jgross@suse.com>
>> ---
>>  docs/features/intel_psr_cat_cdp.pandoc | 562 ++++++++++++++++++---------------
>>  1 file changed, 300 insertions(+), 262 deletions(-)
>>
>> diff --git a/docs/features/intel_psr_cat_cdp.pandoc b/docs/features/intel_psr_cat_cdp.pandoc
>> index 04fb256dd9..a076e8a755 100644
>> --- a/docs/features/intel_psr_cat_cdp.pandoc
>> +++ b/docs/features/intel_psr_cat_cdp.pandoc
>> @@ -1,5 +1,5 @@
>>  % Intel Cache Allocation Technology and Code and Data Prioritization Features
>> -% Revision 1.16
>> +% Revision 1.17
> 
> Do we really need to bump the revision number just to fix markdown
> formatting?

I just followed the example of version 1.16 which was a much smaller
syntactical change.


Juergen

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel

Re: [PATCH v3 2/2] doc: correct intel_psr_cat_cdp.pandoc syntax

[Juergen Gross]

On 08/05/18 15:06, Juergen Gross wrote:
> On 08/05/18 14:56, George Dunlap wrote:
>> On 05/08/2018 07:47 AM, Juergen Gross wrote:
>>> "make -C docs all" fails due to incorrect markdown syntax in
>>> intel_psr_cat_cdp.pandoc. Correct it.
>>>
>>> Signed-off-by: Juergen Gross <jgross@suse.com>
>>> ---
>>>  docs/features/intel_psr_cat_cdp.pandoc | 562 ++++++++++++++++++---------------
>>>  1 file changed, 300 insertions(+), 262 deletions(-)
>>>
>>> diff --git a/docs/features/intel_psr_cat_cdp.pandoc b/docs/features/intel_psr_cat_cdp.pandoc
>>> index 04fb256dd9..a076e8a755 100644
>>> --- a/docs/features/intel_psr_cat_cdp.pandoc
>>> +++ b/docs/features/intel_psr_cat_cdp.pandoc
>>> @@ -1,5 +1,5 @@
>>>  % Intel Cache Allocation Technology and Code and Data Prioritization Features
>>> -% Revision 1.16
>>> +% Revision 1.17
>>
>> Do we really need to bump the revision number just to fix markdown
>> formatting?
> 
> I just followed the example of version 1.16 which was a much smaller
> syntactical change.

Ping?


Juergen

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel

Re: [PATCH v3 2/2] doc: correct intel_psr_cat_cdp.pandoc syntax

[Wei Liu]

On Tue, Jul 10, 2018 at 03:24:33PM +0200, Juergen Gross wrote:
> On 08/05/18 15:06, Juergen Gross wrote:
> > On 08/05/18 14:56, George Dunlap wrote:
> >> On 05/08/2018 07:47 AM, Juergen Gross wrote:
> >>> "make -C docs all" fails due to incorrect markdown syntax in
> >>> intel_psr_cat_cdp.pandoc. Correct it.
> >>>
> >>> Signed-off-by: Juergen Gross <jgross@suse.com>
> >>> ---
> >>>  docs/features/intel_psr_cat_cdp.pandoc | 562 ++++++++++++++++++---------------
> >>>  1 file changed, 300 insertions(+), 262 deletions(-)
> >>>
> >>> diff --git a/docs/features/intel_psr_cat_cdp.pandoc b/docs/features/intel_psr_cat_cdp.pandoc
> >>> index 04fb256dd9..a076e8a755 100644
> >>> --- a/docs/features/intel_psr_cat_cdp.pandoc
> >>> +++ b/docs/features/intel_psr_cat_cdp.pandoc
> >>> @@ -1,5 +1,5 @@
> >>>  % Intel Cache Allocation Technology and Code and Data Prioritization Features
> >>> -% Revision 1.16
> >>> +% Revision 1.17
> >>
> >> Do we really need to bump the revision number just to fix markdown
> >> formatting?
> > 
> > I just followed the example of version 1.16 which was a much smaller
> > syntactical change.
> 
> Ping?

The doc looks fine, but do you maybe want to adjust the changelog? It
has passed 4.11 now -- I can do that for you while committing.

Wei.

> 
> 
> Juergen

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel

Re: [PATCH v3 0/2] fix several issues in documentation

[George Dunlap]

On 05/08/2018 07:47 AM, Juergen Gross wrote:
> Some documents contain invalid pandoc syntax leading to failures when
> creating PDFs from them, e.g. when calling "make all" in the docs
> directory.
> 
> Correct those by using proper lists, code blocks and special character
> escaping.

It's probably worth discussing at some point exactly which dialect(s) of
Markdown we'll support, and what we should call the resulting files.

I'd be in favor of standardizing on pandoc markdown, and naming all the
files '.md'.  Then we could, for instance, use `~~~` to indicate longer
code blocks, rather than four-space indentations (which are slightly
annoying if you're copy-and-pasting from other code).

But maybe that's a discussion to have when we open the 4.12 development
window.

 -George

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel

Re: [PATCH v3 0/2] fix several issues in documentation

[Juergen Gross]

On 08/05/18 11:25, George Dunlap wrote:
> On 05/08/2018 07:47 AM, Juergen Gross wrote:
>> Some documents contain invalid pandoc syntax leading to failures when
>> creating PDFs from them, e.g. when calling "make all" in the docs
>> directory.
>>
>> Correct those by using proper lists, code blocks and special character
>> escaping.
> 
> It's probably worth discussing at some point exactly which dialect(s) of
> Markdown we'll support, and what we should call the resulting files.
> 
> I'd be in favor of standardizing on pandoc markdown, and naming all the
> files '.md'.  Then we could, for instance, use `~~~` to indicate longer
> code blocks, rather than four-space indentations (which are slightly
> annoying if you're copy-and-pasting from other code).
> 
> But maybe that's a discussion to have when we open the 4.12 development
> window.

Another point is to add a call of "make -C docs all" to the OSStest
smoke test after my patches have gone in.


Juergen

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel

Re: [PATCH v3 0/2] fix several issues in documentation

[Ian Jackson]

Juergen Gross writes ("Re: [Xen-devel] [PATCH v3 0/2] fix several issues in documentation"):
> On 08/05/18 11:25, George Dunlap wrote:
> > But maybe that's a discussion to have when we open the 4.12 development
> > window.
> 
> Another point is to add a call of "make -C docs all" to the OSStest
> smoke test after my patches have gone in.

We should add it to all of the tests.

Ian.

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel

Re: [PATCH v3 0/2] fix several issues in documentation

[George Dunlap]

On 05/08/2018 02:08 PM, Ian Jackson wrote:
> Juergen Gross writes ("Re: [Xen-devel] [PATCH v3 0/2] fix several issues in documentation"):
>> On 08/05/18 11:25, George Dunlap wrote:
>>> But maybe that's a discussion to have when we open the 4.12 development
>>> window.
>>
>> Another point is to add a call of "make -C docs all" to the OSStest
>> smoke test after my patches have gone in.
> 
> We should add it to all of the tests.

NB you not only have to add that test command, you have to make sure
(for instance) that pdflatex is installed, or you don't trip over these
particular issues.

 -George

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel