[PATCH for-4.7 1/3] docs/build: Avoid using multi-target pattern rules

[PATCH for-4.7 1/3] docs/build: Avoid using multi-target pattern rules

[Andrew Cooper]

Multi-target non-pattern rules and Multi-target pattern rules behave rather
differently.  From `Pattern Intro':

  Pattern rules may have more than one target.  Unlike normal rules, this does
  not act as many different rules with the same prerequisites and commands.
  If a pattern rule has multiple targets, `make' knows that the rule's
  commands are responsible for making all of the targets.  The commands are
  executed only once to make all the targets.

The intended use of the multi-target pattern rules was to avoid repeating the
identical recipe multiple times.  The issue can be demonstrated with the
generation of documentation from pandoc source.

  ./xen.git$ touch docs/features/template.pandoc
  ./xen.git$ make -C docs/
  # Regenerates html/features/template.html
  ./xen.git$ make -C docs/
  # Regenerates txt/features/template.txt
  ./xen.git$ make -C docs/
  # Regenerates pdf/features/template.pdf

To work around this, there need to be three distinct rules, so the execution
of one recipe doesn't short ciruit the others.  To avoid copy&paste
duplication, introduce a metarule, and evalute it for each document target.

As $(PANDOC) is used to generate documentation from different source types,
the metarule can be extended to also encompas the rule to create pdfs from
markdown.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
Release-acked-by: Wei Liu <wei.liu2@citrix.com>
---
 docs/Makefile | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index b9da605..e2537e8 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -180,22 +180,24 @@ txt/%.txt: %.markdown
 	@$(INSTALL_DIR) $(@D)
 	$(INSTALL_DATA) $< $@
 
-pdf/%.pdf: %.markdown
-ifneq ($(PANDOC),)
-	@$(INSTALL_DIR) $(@D)
-	$(PANDOC) --number-sections --toc --standalone $< --output $@
-else
-	@echo "pandoc not installed; skipping $@"
-endif
+# Metarule for generating pandoc rules.
+define GENERATE_PANDOC_RULE
+# $(1) is the target documentation format. $(2) is the source format.
 
-pdf/%.pdf txt/%.txt html/%.html: %.pandoc
+$(1)/%.$(1): %.$(2)
 ifneq ($(PANDOC),)
-	@$(INSTALL_DIR) $(@D)
-	$(PANDOC) --number-sections --toc --standalone $< --output $@
+	@$(INSTALL_DIR) $$(@D)
+	$(PANDOC) --number-sections --toc --standalone $$< --output $$@
 else
-	@echo "pandoc not installed; skipping $@"
+	@echo "pandoc not installed; skipping $$@"
 endif
 
+endef
+$(eval $(call GENERATE_PANDOC_RULE,pdf,pandoc))   # pdf/%.pdf: %.pandoc
+$(eval $(call GENERATE_PANDOC_RULE,txt,pandoc))   # txt/%.txt: %.pandoc
+$(eval $(call GENERATE_PANDOC_RULE,html,pandoc))  # html/%.html: %.pandoc
+$(eval $(call GENERATE_PANDOC_RULE,pdf,markdown)) # pdf/%.pdf: %.markdown
+
 ifeq (,$(findstring clean,$(MAKECMDGOALS)))
 $(XEN_ROOT)/config/Docs.mk:
 	$(error You have to run ./configure before building docs)
-- 
2.1.4


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

[PATCH for-4.7 2/3] docs/xsplice: Fix syntax when compiling to pdf with pandoc

[Andrew Cooper]

Pandoc (version 1.12.4.2 from Debian Jessie) complains at the embedded \n in
the signature checking paragraph.

  /usr/bin/pandoc --number-sections --toc --standalone misc/xsplice.markdown
    --output pdf/misc/xsplice.pdf
  ! Undefined control sequence.
  l.1085 appended\textasciitilde{}\n

Surround the string in backticks to make it verbatim text.

While altering this file, strip the substantial quantity of trailing
whitespace.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
---
CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
CC: Wei Liu <wei.liu2@citrix.com>
CC: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
---
 docs/misc/xsplice.markdown | 304 ++++++++++++++++++++++-----------------------
 1 file changed, 152 insertions(+), 152 deletions(-)

diff --git a/docs/misc/xsplice.markdown b/docs/misc/xsplice.markdown
index 4a98be1..80f8bc7 100644
--- a/docs/misc/xsplice.markdown
+++ b/docs/misc/xsplice.markdown
@@ -90,18 +90,18 @@ As example we will assume the hypervisor does not have XSA-132 (see
 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  
+   48 89 e0                  mov    %rsp,%rax
+   48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax
 </pre>
 
 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  
+   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>
 
 This is inside the arch_do_domctl. This new change adds 21 extra
@@ -113,8 +113,8 @@ As such we could simplify this problem by only patching the site
 which calls arch_do_domctl:
 
 <pre>
-do_domctl:  
- e8 4b b1 05 00          callq  ffff82d08015fbb9 <arch_do_domctl>  
+do_domctl:
+ e8 4b b1 05 00          callq  ffff82d08015fbb9 <arch_do_domctl>
 </pre>
 
 with a new address for where the new `arch_do_domctl` would be (this
@@ -128,8 +128,8 @@ Patching the offset in `hypercall_table` for `do_domctl:
 
 <pre>
 
- ffff82d08024d490:   79 30  
- ffff82d08024d492:   10 80 d0 82 ff ff   
+ ffff82d08024d490:   79 30
+ ffff82d08024d492:   10 80 d0 82 ff ff
 
 </pre>
 
@@ -172,9 +172,9 @@ 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  
+ ffff82d08024b270 <hypercall_table>:
+ ...
+ ffff82d08024b2f8:   9e 2f 11 80 d0 82 ff ff
 
 </pre>
 
@@ -187,17 +187,17 @@ 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`.
 
 <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  
+ 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>
 
 with:
 
 <pre>
- ffff82d080112f9e do_xen_version:  
- ffff82d080112f9e:       e9 XX YY ZZ QQ          jmpq   [new do_xen_version]  
+ ffff82d080112f9e do_xen_version:
+ ffff82d080112f9e:       e9 XX YY ZZ QQ          jmpq   [new do_xen_version]
 </pre>
 
 which would lessen the amount of patching to just one location.
@@ -296,15 +296,15 @@ The `.xsplice.funcs` contains an array of xsplice_patch_func structures
 which describe the functions to be patched:
 
 <pre>
-struct xsplice_patch_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];  
-};  
+struct xsplice_patch_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>
 
 The size of the structure is 64 bytes on 64-bit hypervisors. It will be
@@ -345,33 +345,33 @@ to `old_addr`.
 A simple example of what a payload file can be:
 
 <pre>
-/* MUST be in sync with hypervisor. */  
-struct xsplice_patch_func {  
-    const char *name;  
-    void *new_addr;  
-    void *old_addr;  
-    uint32_t new_size;  
-    uint32_t old_size;  
+/* MUST be in sync with hypervisor. */
+struct xsplice_patch_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];  
-};  
+    uint8_t pad[31];
+};
 
-/* Our replacement function for xen_extra_version. */  
-const char *xen_hello_world(void)  
-{  
-    return "Hello World";  
-}  
+/* 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";  
+static unsigned char patch_this_fnc[] = "xen_extra_version";
 
-struct xsplice_patch_func xsplice_hello_world = {  
+struct xsplice_patch_func xsplice_hello_world = {
     .version = XSPLICE_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__(".xsplice.funcs")));  
+    .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__(".xsplice.funcs")));
 
 </pre>
 
@@ -424,13 +424,13 @@ one uint32_t to determine the sub-operations and one padding field which
 *MUST* always be zero.
 
 <pre>
-struct xen_sysctl_xsplice_op {  
-    uint32_t cmd;                   /* IN: XEN_SYSCTL_XSPLICE_*. */  
-    uint32_t pad;                   /* IN: Always zero. */  
-	union {  
-          ... see below ...  
-        } u;  
-};  
+struct xen_sysctl_xsplice_op {
+    uint32_t cmd;                   /* IN: XEN_SYSCTL_XSPLICE_*. */
+    uint32_t pad;                   /* IN: Always zero. */
+	union {
+          ... see below ...
+        } u;
+};
 
 </pre>
 while the rest of hypercall specific structures are part of the this structure.
@@ -447,17 +447,17 @@ which contains:
 The structure is as follow:
 
 <pre>
-/*  
- *  Uniquely identifies the payload.  Should be human readable.  
- * Includes the NUL terminator  
- */  
-#define XEN_XSPLICE_NAME_SIZE 128  
-struct xen_xsplice_name {  
-    XEN_GUEST_HANDLE_64(char) name;         /* IN, pointer to name. */  
-    uint16_t size;                          /* IN, size of name. May be upto   
-                                               XEN_XSPLICE_NAME_SIZE. */  
-    uint16_t pad[3];                        /* IN: MUST be zero. */ 
-};  
+/*
+ *  Uniquely identifies the payload.  Should be human readable.
+ * Includes the NUL terminator
+ */
+#define XEN_XSPLICE_NAME_SIZE 128
+struct xen_xsplice_name {
+    XEN_GUEST_HANDLE_64(char) name;         /* IN, pointer to name. */
+    uint16_t size;                          /* IN, size of name. May be upto
+                                               XEN_XSPLICE_NAME_SIZE. */
+    uint16_t pad[3];                        /* IN: MUST be zero. */
+};
 </pre>
 
 ### XEN_SYSCTL_XSPLICE_UPLOAD (0)
@@ -485,11 +485,11 @@ The `payload` is the ELF payload as mentioned in the `Payload format` section.
 The structure is as follow:
 
 <pre>
-struct xen_sysctl_xsplice_upload {  
-    xen_xsplice_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. */  
-};  
+struct xen_sysctl_xsplice_upload {
+    xen_xsplice_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>
 
 ### XEN_SYSCTL_XSPLICE_GET (1)
@@ -538,17 +538,17 @@ This operation is synchronous and does not require preemption.
 The structure is as follow:
 
 <pre>
-struct xen_xsplice_status {  
-#define XSPLICE_STATUS_CHECKED      1  
-#define XSPLICE_STATUS_APPLIED      2  
-    uint32_t state;                 /* OUT: XSPLICE_STATE_*. */  
-    int32_t rc;                     /* OUT: 0 if no error, otherwise -XEN_EXX. */  
-};  
-
-struct xen_sysctl_xsplice_get {  
-    xen_xsplice_name_t name;        /* IN, the name of the payload. */  
-    xen_xsplice_status_t status;    /* IN/OUT: status of the payload. */  
-};  
+struct xen_xsplice_status {
+#define XSPLICE_STATUS_CHECKED      1
+#define XSPLICE_STATUS_APPLIED      2
+    uint32_t state;                 /* OUT: XSPLICE_STATE_*. */
+    int32_t rc;                     /* OUT: 0 if no error, otherwise -XEN_EXX. */
+};
+
+struct xen_sysctl_xsplice_get {
+    xen_xsplice_name_t name;        /* IN, the name of the payload. */
+    xen_xsplice_status_t status;    /* IN/OUT: status of the payload. */
+};
 </pre>
 
 ### XEN_SYSCTL_XSPLICE_LIST (2)
@@ -612,24 +612,24 @@ The `struct xen_xsplice_status` structure contains an status of payload which in
 The structure is as follow:
 
 <pre>
-struct xen_sysctl_xsplice_list {  
+struct xen_sysctl_xsplice_list {
     uint32_t version;                       /* OUT: Hypervisor stamps value.
-                                               If varies between calls, we are  
-                                               getting stale data. */  
+                                               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_xsplice_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_XSPLICE_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. */  
-};  
+    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_xsplice_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_XSPLICE_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_XSPLICE_ACTION (3)
@@ -665,17 +665,17 @@ The return value will be zero unless the provided fields are incorrect.
 The structure is as follow:
 
 <pre>
-#define XSPLICE_ACTION_UNLOAD  1  
-#define XSPLICE_ACTION_REVERT  2  
-#define XSPLICE_ACTION_APPLY   3  
-#define XSPLICE_ACTION_REPLACE 4  
-struct xen_sysctl_xsplice_action {  
-    xen_xsplice_name_t name;                /* IN, name of the patch. */  
-    uint32_t cmd;                           /* IN: XSPLICE_ACTION_* */  
-    uint32_t time;                          /* IN: Zero if no timeout. */   
-                                            /* Or upper bound of time (ms) */   
-                                            /* for operation to take. */  
-};  
+#define XSPLICE_ACTION_UNLOAD  1
+#define XSPLICE_ACTION_REVERT  2
+#define XSPLICE_ACTION_APPLY   3
+#define XSPLICE_ACTION_REPLACE 4
+struct xen_sysctl_xsplice_action {
+    xen_xsplice_name_t name;                /* IN, name of the patch. */
+    uint32_t cmd;                           /* IN: XSPLICE_ACTION_* */
+    uint32_t time;                          /* IN: Zero if no timeout. */
+                                            /* Or upper bound of time (ms) */
+                                            /* for operation to take. */
+};
 
 </pre>
 
@@ -686,11 +686,11 @@ The XSPLICE_ACTION prefix has been dropped to easy reading and
 does not include the XSPLICE_STATES:
 
 <pre>
-              /->\  
-              \  /  
- UNLOAD <--- CHECK ---> REPLACE|APPLY --> REVERT --\  
-                \                                  |  
-                 \-------------------<-------------/  
+              /->\
+              \  /
+ UNLOAD <--- CHECK ---> REPLACE|APPLY --> REVERT --\
+                \                                  |
+                 \-------------------<-------------/
 
 </pre>
 ## State transition table of XSPLICE_ACTION commands and XSPLICE_STATUS.
@@ -1007,46 +1007,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 */  
+#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>
@@ -1085,7 +1085,7 @@ this means 5 bytes are required.
 Depending on compiler settings, there are several functions in Xen that
 are smaller (without inter-function padding).
 
-<pre> 
+<pre>
 readelf -sW xen-syms | grep " FUNC " | \
     awk '{ if ($3 < 5) print $3, $4, $5, $8 }'
 
-- 
2.1.4


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH for-4.7 2/3] docs/xsplice: Fix syntax when compiling to pdf with pandoc

[Konrad Rzeszutek Wilk]

On Thu, May 19, 2016 at 03:29:45PM +0100, Andrew Cooper wrote:
> Pandoc (version 1.12.4.2 from Debian Jessie) complains at the embedded \n in
> the signature checking paragraph.
> 
>   /usr/bin/pandoc --number-sections --toc --standalone misc/xsplice.markdown
>     --output pdf/misc/xsplice.pdf
>   ! Undefined control sequence.
>   l.1085 appended\textasciitilde{}\n
> 
> Surround the string in backticks to make it verbatim text.

Ok, where is that change?
> 
> While altering this file, strip the substantial quantity of trailing
> whitespace.

Please do not. That was added specifically there otherwise
markdown messes it up when doing HTML and the lines get mangled up.

> 
> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
> ---
> CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
> CC: Wei Liu <wei.liu2@citrix.com>
> CC: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
> ---
>  docs/misc/xsplice.markdown | 304 ++++++++++++++++++++++-----------------------
>  1 file changed, 152 insertions(+), 152 deletions(-)
> 
> diff --git a/docs/misc/xsplice.markdown b/docs/misc/xsplice.markdown
> index 4a98be1..80f8bc7 100644
> --- a/docs/misc/xsplice.markdown
> +++ b/docs/misc/xsplice.markdown
> @@ -90,18 +90,18 @@ As example we will assume the hypervisor does not have XSA-132 (see
>  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  
> +   48 89 e0                  mov    %rsp,%rax
> +   48 25 00 80 ff ff         and    $0xffffffffffff8000,%rax
>  </pre>
>  
>  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  
> +   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>
>  
>  This is inside the arch_do_domctl. This new change adds 21 extra
> @@ -113,8 +113,8 @@ As such we could simplify this problem by only patching the site
>  which calls arch_do_domctl:
>  
>  <pre>
> -do_domctl:  
> - e8 4b b1 05 00          callq  ffff82d08015fbb9 <arch_do_domctl>  
> +do_domctl:
> + e8 4b b1 05 00          callq  ffff82d08015fbb9 <arch_do_domctl>
>  </pre>
>  
>  with a new address for where the new `arch_do_domctl` would be (this
> @@ -128,8 +128,8 @@ Patching the offset in `hypercall_table` for `do_domctl:
>  
>  <pre>
>  
> - ffff82d08024d490:   79 30  
> - ffff82d08024d492:   10 80 d0 82 ff ff   
> + ffff82d08024d490:   79 30
> + ffff82d08024d492:   10 80 d0 82 ff ff
>  
>  </pre>
>  
> @@ -172,9 +172,9 @@ 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  
> + ffff82d08024b270 <hypercall_table>:
> + ...
> + ffff82d08024b2f8:   9e 2f 11 80 d0 82 ff ff
>  
>  </pre>
>  
> @@ -187,17 +187,17 @@ 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`.
>  
>  <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  
> + 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>
>  
>  with:
>  
>  <pre>
> - ffff82d080112f9e do_xen_version:  
> - ffff82d080112f9e:       e9 XX YY ZZ QQ          jmpq   [new do_xen_version]  
> + ffff82d080112f9e do_xen_version:
> + ffff82d080112f9e:       e9 XX YY ZZ QQ          jmpq   [new do_xen_version]
>  </pre>
>  
>  which would lessen the amount of patching to just one location.
> @@ -296,15 +296,15 @@ The `.xsplice.funcs` contains an array of xsplice_patch_func structures
>  which describe the functions to be patched:
>  
>  <pre>
> -struct xsplice_patch_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];  
> -};  
> +struct xsplice_patch_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>
>  
>  The size of the structure is 64 bytes on 64-bit hypervisors. It will be
> @@ -345,33 +345,33 @@ to `old_addr`.
>  A simple example of what a payload file can be:
>  
>  <pre>
> -/* MUST be in sync with hypervisor. */  
> -struct xsplice_patch_func {  
> -    const char *name;  
> -    void *new_addr;  
> -    void *old_addr;  
> -    uint32_t new_size;  
> -    uint32_t old_size;  
> +/* MUST be in sync with hypervisor. */
> +struct xsplice_patch_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];  
> -};  
> +    uint8_t pad[31];
> +};
>  
> -/* Our replacement function for xen_extra_version. */  
> -const char *xen_hello_world(void)  
> -{  
> -    return "Hello World";  
> -}  
> +/* 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";  
> +static unsigned char patch_this_fnc[] = "xen_extra_version";
>  
> -struct xsplice_patch_func xsplice_hello_world = {  
> +struct xsplice_patch_func xsplice_hello_world = {
>      .version = XSPLICE_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__(".xsplice.funcs")));  
> +    .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__(".xsplice.funcs")));
>  
>  </pre>
>  
> @@ -424,13 +424,13 @@ one uint32_t to determine the sub-operations and one padding field which
>  *MUST* always be zero.
>  
>  <pre>
> -struct xen_sysctl_xsplice_op {  
> -    uint32_t cmd;                   /* IN: XEN_SYSCTL_XSPLICE_*. */  
> -    uint32_t pad;                   /* IN: Always zero. */  
> -	union {  
> -          ... see below ...  
> -        } u;  
> -};  
> +struct xen_sysctl_xsplice_op {
> +    uint32_t cmd;                   /* IN: XEN_SYSCTL_XSPLICE_*. */
> +    uint32_t pad;                   /* IN: Always zero. */
> +	union {
> +          ... see below ...
> +        } u;
> +};
>  
>  </pre>
>  while the rest of hypercall specific structures are part of the this structure.
> @@ -447,17 +447,17 @@ which contains:
>  The structure is as follow:
>  
>  <pre>
> -/*  
> - *  Uniquely identifies the payload.  Should be human readable.  
> - * Includes the NUL terminator  
> - */  
> -#define XEN_XSPLICE_NAME_SIZE 128  
> -struct xen_xsplice_name {  
> -    XEN_GUEST_HANDLE_64(char) name;         /* IN, pointer to name. */  
> -    uint16_t size;                          /* IN, size of name. May be upto   
> -                                               XEN_XSPLICE_NAME_SIZE. */  
> -    uint16_t pad[3];                        /* IN: MUST be zero. */ 
> -};  
> +/*
> + *  Uniquely identifies the payload.  Should be human readable.
> + * Includes the NUL terminator
> + */
> +#define XEN_XSPLICE_NAME_SIZE 128
> +struct xen_xsplice_name {
> +    XEN_GUEST_HANDLE_64(char) name;         /* IN, pointer to name. */
> +    uint16_t size;                          /* IN, size of name. May be upto
> +                                               XEN_XSPLICE_NAME_SIZE. */
> +    uint16_t pad[3];                        /* IN: MUST be zero. */
> +};
>  </pre>
>  
>  ### XEN_SYSCTL_XSPLICE_UPLOAD (0)
> @@ -485,11 +485,11 @@ The `payload` is the ELF payload as mentioned in the `Payload format` section.
>  The structure is as follow:
>  
>  <pre>
> -struct xen_sysctl_xsplice_upload {  
> -    xen_xsplice_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. */  
> -};  
> +struct xen_sysctl_xsplice_upload {
> +    xen_xsplice_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>
>  
>  ### XEN_SYSCTL_XSPLICE_GET (1)
> @@ -538,17 +538,17 @@ This operation is synchronous and does not require preemption.
>  The structure is as follow:
>  
>  <pre>
> -struct xen_xsplice_status {  
> -#define XSPLICE_STATUS_CHECKED      1  
> -#define XSPLICE_STATUS_APPLIED      2  
> -    uint32_t state;                 /* OUT: XSPLICE_STATE_*. */  
> -    int32_t rc;                     /* OUT: 0 if no error, otherwise -XEN_EXX. */  
> -};  
> -
> -struct xen_sysctl_xsplice_get {  
> -    xen_xsplice_name_t name;        /* IN, the name of the payload. */  
> -    xen_xsplice_status_t status;    /* IN/OUT: status of the payload. */  
> -};  
> +struct xen_xsplice_status {
> +#define XSPLICE_STATUS_CHECKED      1
> +#define XSPLICE_STATUS_APPLIED      2
> +    uint32_t state;                 /* OUT: XSPLICE_STATE_*. */
> +    int32_t rc;                     /* OUT: 0 if no error, otherwise -XEN_EXX. */
> +};
> +
> +struct xen_sysctl_xsplice_get {
> +    xen_xsplice_name_t name;        /* IN, the name of the payload. */
> +    xen_xsplice_status_t status;    /* IN/OUT: status of the payload. */
> +};
>  </pre>
>  
>  ### XEN_SYSCTL_XSPLICE_LIST (2)
> @@ -612,24 +612,24 @@ The `struct xen_xsplice_status` structure contains an status of payload which in
>  The structure is as follow:
>  
>  <pre>
> -struct xen_sysctl_xsplice_list {  
> +struct xen_sysctl_xsplice_list {
>      uint32_t version;                       /* OUT: Hypervisor stamps value.
> -                                               If varies between calls, we are  
> -                                               getting stale data. */  
> +                                               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_xsplice_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_XSPLICE_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. */  
> -};  
> +    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_xsplice_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_XSPLICE_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_XSPLICE_ACTION (3)
> @@ -665,17 +665,17 @@ The return value will be zero unless the provided fields are incorrect.
>  The structure is as follow:
>  
>  <pre>
> -#define XSPLICE_ACTION_UNLOAD  1  
> -#define XSPLICE_ACTION_REVERT  2  
> -#define XSPLICE_ACTION_APPLY   3  
> -#define XSPLICE_ACTION_REPLACE 4  
> -struct xen_sysctl_xsplice_action {  
> -    xen_xsplice_name_t name;                /* IN, name of the patch. */  
> -    uint32_t cmd;                           /* IN: XSPLICE_ACTION_* */  
> -    uint32_t time;                          /* IN: Zero if no timeout. */   
> -                                            /* Or upper bound of time (ms) */   
> -                                            /* for operation to take. */  
> -};  
> +#define XSPLICE_ACTION_UNLOAD  1
> +#define XSPLICE_ACTION_REVERT  2
> +#define XSPLICE_ACTION_APPLY   3
> +#define XSPLICE_ACTION_REPLACE 4
> +struct xen_sysctl_xsplice_action {
> +    xen_xsplice_name_t name;                /* IN, name of the patch. */
> +    uint32_t cmd;                           /* IN: XSPLICE_ACTION_* */
> +    uint32_t time;                          /* IN: Zero if no timeout. */
> +                                            /* Or upper bound of time (ms) */
> +                                            /* for operation to take. */
> +};
>  
>  </pre>
>  
> @@ -686,11 +686,11 @@ The XSPLICE_ACTION prefix has been dropped to easy reading and
>  does not include the XSPLICE_STATES:
>  
>  <pre>
> -              /->\  
> -              \  /  
> - UNLOAD <--- CHECK ---> REPLACE|APPLY --> REVERT --\  
> -                \                                  |  
> -                 \-------------------<-------------/  
> +              /->\
> +              \  /
> + UNLOAD <--- CHECK ---> REPLACE|APPLY --> REVERT --\
> +                \                                  |
> +                 \-------------------<-------------/
>  
>  </pre>
>  ## State transition table of XSPLICE_ACTION commands and XSPLICE_STATUS.
> @@ -1007,46 +1007,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 */  
> +#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>
> @@ -1085,7 +1085,7 @@ this means 5 bytes are required.
>  Depending on compiler settings, there are several functions in Xen that
>  are smaller (without inter-function padding).
>  
> -<pre> 
> +<pre>
>  readelf -sW xen-syms | grep " FUNC " | \
>      awk '{ if ($3 < 5) print $3, $4, $5, $8 }'
>  
> -- 
> 2.1.4
> 

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH for-4.7 2/3] docs/xsplice: Fix syntax when compiling to pdf with pandoc

[Andrew Cooper]

On 19/05/16 15:36, Konrad Rzeszutek Wilk wrote:
> On Thu, May 19, 2016 at 03:29:45PM +0100, Andrew Cooper wrote:
>> Pandoc (version 1.12.4.2 from Debian Jessie) complains at the embedded \n in
>> the signature checking paragraph.
>>
>>   /usr/bin/pandoc --number-sections --toc --standalone misc/xsplice.markdown
>>     --output pdf/misc/xsplice.pdf
>>   ! Undefined control sequence.
>>   l.1085 appended\textasciitilde{}\n
>>
>> Surround the string in backticks to make it verbatim text.
> Ok, where is that change?

> @@ -1007,46 +1007,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.

^ Here.

>> While altering this file, strip the substantial quantity of trailing
>> whitespace.
> Please do not. That was added specifically there otherwise
> markdown messes it up when doing HTML and the lines get mangled up.

Markdown isn't whitespace sensitive, so that really shouldn't be doing
anything.  If you want a verbatim text block, indent it by 4 characters.

~Andrew

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH for-4.7 2/3] docs/xsplice: Fix syntax when compiling to pdf with pandoc

[Konrad Rzeszutek Wilk]

On Thu, May 19, 2016 at 03:41:49PM +0100, Andrew Cooper wrote:
> On 19/05/16 15:36, Konrad Rzeszutek Wilk wrote:
> > On Thu, May 19, 2016 at 03:29:45PM +0100, Andrew Cooper wrote:
> >> Pandoc (version 1.12.4.2 from Debian Jessie) complains at the embedded \n in
> >> the signature checking paragraph.
> >>
> >>   /usr/bin/pandoc --number-sections --toc --standalone misc/xsplice.markdown
> >>     --output pdf/misc/xsplice.pdf
> >>   ! Undefined control sequence.
> >>   l.1085 appended\textasciitilde{}\n
> >>
> >> Surround the string in backticks to make it verbatim text.
> > Ok, where is that change?
> 
> > @@ -1007,46 +1007,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.
> 
> ^ Here.

Thank you!
> 
> >> While altering this file, strip the substantial quantity of trailing
> >> whitespace.
> > Please do not. That was added specifically there otherwise
> > markdown messes it up when doing HTML and the lines get mangled up.
> 
> Markdown isn't whitespace sensitive, so that really shouldn't be doing
> anything.  If you want a verbatim text block, indent it by 4 characters.

https://daringfireball.net/projects/markdown/syntax

"When you do want to insert a <br /> break tag using Markdown, you end a
line with two or more spaces, then type return."

But if this can be done with indenting it with 4 characters that would
work too.

> 
> ~Andrew

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH for-4.7 2/3] docs/xsplice: Fix syntax when compiling to pdf with pandoc

[Andrew Cooper]

On 19/05/16 15:56, Konrad Rzeszutek Wilk wrote:
> On Thu, May 19, 2016 at 03:41:49PM +0100, Andrew Cooper wrote:
>> On 19/05/16 15:36, Konrad Rzeszutek Wilk wrote:
>>> On Thu, May 19, 2016 at 03:29:45PM +0100, Andrew Cooper wrote:
>>>> Pandoc (version 1.12.4.2 from Debian Jessie) complains at the embedded \n in
>>>> the signature checking paragraph.
>>>>
>>>>   /usr/bin/pandoc --number-sections --toc --standalone misc/xsplice.markdown
>>>>     --output pdf/misc/xsplice.pdf
>>>>   ! Undefined control sequence.
>>>>   l.1085 appended\textasciitilde{}\n
>>>>
>>>> Surround the string in backticks to make it verbatim text.
>>> Ok, where is that change?
>>> @@ -1007,46 +1007,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.
>> ^ Here.
> Thank you!
>>>> While altering this file, strip the substantial quantity of trailing
>>>> whitespace.
>>> Please do not. That was added specifically there otherwise
>>> markdown messes it up when doing HTML and the lines get mangled up.
>> Markdown isn't whitespace sensitive, so that really shouldn't be doing
>> anything.  If you want a verbatim text block, indent it by 4 characters.
> https://daringfireball.net/projects/markdown/syntax
>
> "When you do want to insert a <br /> break tag using Markdown, you end a
> line with two or more spaces, then type return."

(You learn something every day), and eww... That is nasty.

>
> But if this can be done with indenting it with 4 characters that would
> work too.

I recommend https://daringfireball.net/projects/markdown/syntax#precode

~Andrew

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH for-4.7 2/3] docs/xsplice: Fix syntax when compiling to pdf with pandoc

[Wei Liu]

On Thu, May 19, 2016 at 10:56:06AM -0400, Konrad Rzeszutek Wilk wrote:
> On Thu, May 19, 2016 at 03:41:49PM +0100, Andrew Cooper wrote:
> > On 19/05/16 15:36, Konrad Rzeszutek Wilk wrote:
> > > On Thu, May 19, 2016 at 03:29:45PM +0100, Andrew Cooper wrote:
> > >> Pandoc (version 1.12.4.2 from Debian Jessie) complains at the embedded \n in
> > >> the signature checking paragraph.
> > >>
> > >>   /usr/bin/pandoc --number-sections --toc --standalone misc/xsplice.markdown
> > >>     --output pdf/misc/xsplice.pdf
> > >>   ! Undefined control sequence.
> > >>   l.1085 appended\textasciitilde{}\n
> > >>
> > >> Surround the string in backticks to make it verbatim text.
> > > Ok, where is that change?
> > 
> > > @@ -1007,46 +1007,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.
> > 
> > ^ Here.
> 
> Thank you!
> > 
> > >> While altering this file, strip the substantial quantity of trailing
> > >> whitespace.
> > > Please do not. That was added specifically there otherwise
> > > markdown messes it up when doing HTML and the lines get mangled up.
> > 
> > Markdown isn't whitespace sensitive, so that really shouldn't be doing
> > anything.  If you want a verbatim text block, indent it by 4 characters.
> 
> https://daringfireball.net/projects/markdown/syntax
> 
> "When you do want to insert a <br /> break tag using Markdown, you end a
> line with two or more spaces, then type return."
> 
> But if this can be done with indenting it with 4 characters that would
> work too.
> 

I take it you're happy with this change? Do you want to test it and
report back?

Wei.

> > 
> > ~Andrew

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH for-4.7 2/3] docs/xsplice: Fix syntax when compiling to pdf with pandoc

[Konrad Rzeszutek Wilk]

On Thu, May 19, 2016 at 04:07:00PM +0100, Wei Liu wrote:
> On Thu, May 19, 2016 at 10:56:06AM -0400, Konrad Rzeszutek Wilk wrote:
> > On Thu, May 19, 2016 at 03:41:49PM +0100, Andrew Cooper wrote:
> > > On 19/05/16 15:36, Konrad Rzeszutek Wilk wrote:
> > > > On Thu, May 19, 2016 at 03:29:45PM +0100, Andrew Cooper wrote:
> > > >> Pandoc (version 1.12.4.2 from Debian Jessie) complains at the embedded \n in
> > > >> the signature checking paragraph.
> > > >>
> > > >>   /usr/bin/pandoc --number-sections --toc --standalone misc/xsplice.markdown
> > > >>     --output pdf/misc/xsplice.pdf
> > > >>   ! Undefined control sequence.
> > > >>   l.1085 appended\textasciitilde{}\n
> > > >>
> > > >> Surround the string in backticks to make it verbatim text.
> > > > Ok, where is that change?
> > > 
> > > > @@ -1007,46 +1007,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.
> > > 
> > > ^ Here.
> > 
> > Thank you!
> > > 
> > > >> While altering this file, strip the substantial quantity of trailing
> > > >> whitespace.
> > > > Please do not. That was added specifically there otherwise
> > > > markdown messes it up when doing HTML and the lines get mangled up.
> > > 
> > > Markdown isn't whitespace sensitive, so that really shouldn't be doing
> > > anything.  If you want a verbatim text block, indent it by 4 characters.
> > 
> > https://daringfireball.net/projects/markdown/syntax
> > 
> > "When you do want to insert a <br /> break tag using Markdown, you end a
> > line with two or more spaces, then type return."
> > 
> > But if this can be done with indenting it with 4 characters that would
> > work too.
> > 
> 
> I take it you're happy with this change? Do you want to test it and
> report back?

No, this patch as is won't do.

The
'~Module signature appended~\n',
change to
`'~Module signature appended~\n'`,

Albeit part is good!

I can respin this patch with that simple change.
> 
> Wei.
> 
> > > 
> > > ~Andrew

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

[PATCH v2 for-4.7] docs/xsplice: Fix syntax when compiling to pdf with pandoc

[Andrew Cooper]

Pandoc (version 1.12.4.2 from Debian Jessie) complains at the embedded \n in
the signature checking paragraph.

  /usr/bin/pandoc --number-sections --toc --standalone misc/xsplice.markdown
    --output pdf/misc/xsplice.pdf
  ! Undefined control sequence.
  l.1085 appended\textasciitilde{}\n

Surround the string in backticks to make it verbatim text.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
---
CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
CC: Wei Liu <wei.liu2@citrix.com>
CC: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>

v2: Don't strip whitespace.  (That issue can be fixed later)
---
 docs/misc/xsplice.markdown | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/misc/xsplice.markdown b/docs/misc/xsplice.markdown
index 4a98be1..05c1a55 100644
--- a/docs/misc/xsplice.markdown
+++ b/docs/misc/xsplice.markdown
@@ -1007,7 +1007,7 @@ 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.
 
-- 
2.1.4


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH v2 for-4.7] docs/xsplice: Fix syntax when compiling to pdf with pandoc

[Konrad Rzeszutek Wilk]

On Fri, May 20, 2016 at 07:09:42PM +0100, Andrew Cooper wrote:
> Pandoc (version 1.12.4.2 from Debian Jessie) complains at the embedded \n in
> the signature checking paragraph.
> 
>   /usr/bin/pandoc --number-sections --toc --standalone misc/xsplice.markdown
>     --output pdf/misc/xsplice.pdf
>   ! Undefined control sequence.
>   l.1085 appended\textasciitilde{}\n
> 
> Surround the string in backticks to make it verbatim text.
> 
> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
> ---
> CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
> CC: Wei Liu <wei.liu2@citrix.com>
> CC: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>

Reviewed-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>

Thanks!
> 
> v2: Don't strip whitespace.  (That issue can be fixed later)
> ---
>  docs/misc/xsplice.markdown | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/docs/misc/xsplice.markdown b/docs/misc/xsplice.markdown
> index 4a98be1..05c1a55 100644
> --- a/docs/misc/xsplice.markdown
> +++ b/docs/misc/xsplice.markdown
> @@ -1007,7 +1007,7 @@ 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.
>  
> -- 
> 2.1.4
> 

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

[PATCH for-4.7 3/3] docs/feature: Tweaks to the feature document template

[Andrew Cooper]

During review of the migration feature doc, some changes were made which
should have been reflected in the template.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
---
CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
CC: Wei Liu <wei.liu2@citrix.com>
---
 docs/features/template.pandoc | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/features/template.pandoc b/docs/features/template.pandoc
index 7698291..82881e3 100644
--- a/docs/features/template.pandoc
+++ b/docs/features/template.pandoc
@@ -29,22 +29,22 @@ Architecture(s): e.g. x86, arm
 A short description the feature, similar to an abstract for a
 paper/presentation.
 
-# User information
+# User details
 
 Information for a user attempting to use the feature.  Should include
 how to enable the feature (is it enabled by default? If not, how to turn
 it on?), and how to interact with the feature (typically via `xl`).
 
+# Technical details
+
+Information for a developer or power user.  Should include where to look
+in-tree for detailed documents and code.
+
 # Limitations
 
 Information concerning incompatibilities with other features or hardware
 combinations.
 
-# Technical information
-
-Information for a developer or power user.  Should include where to look
-in-tree for detailed documents and code.
-
 # Testing
 
 Information concerning how to properly test changes affecting this feature.
-- 
2.1.4


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH for-4.7 1/3] docs/build: Avoid using multi-target pattern rules

[Wei Liu]

Whole series:

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

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel