Re: [Xen-devel] [PATCH 4/5] SUPPORT.md: Move descriptions up before Status info

[Lars Kurth]

On 17/04/2018, 14:22, "Ian Jackson"  wrote:

Lars Kurth writes ("Re: [PATCH 4/5] SUPPORT.md: Move descriptions up before 
Status info"):
> There were a couple of minor text changes for grammar reasons, which I 
noticed and highlighted.

Thanks.

> I also checked the code motions. There are some things which need to be 
pointed out, but they should not prevent this series from being checked in.
> 
> However, a couple were missed
> * ### PV Console (frontend) => missed moving the note (which is a 
definition)

That's one, not a couple.  I have fixed it.

> I also spotted a few other inconsistencies, which we probably should fix, 
but these need backporting
> * ARM: 16K and 64K page granularity in guests
> * ARM: Guest Device Tree support
> * ARM: Guest ACPI support
> In all the other section headers we use x86/ or ARM/

I think "x86:" and "ARM:" are more natural so I would prefer that
bikeshed purple rather than blue.  I think the "/" came from the
example of the guest types, which are indeed in some sense "x86/HVM"
rather than "x86: HVM".

I think we should treat that as a separate issue from this series.

Agreed

> -### x86/PVH
> -
>  Status, domU: Supported
> -Status, dom0: Experimental
> +
> +### x86/PVH
>  
>  PVH is a next-generation paravirtualized mode
>  designed to take advantage of hardware virtualization support when 
possible.
> 
> Looks correct from a mere refactoring perspective, but generates some odd 
behaviour in 
https://xenbits.xen.org/people/iwj/2018/support-matrix-example-B-v1/t.html
> 
> The underlying reason is that we had some headline re-names between 4.10 
and 4.11. e.g.
> ARM guest => ARM
> 
> And some support statement changes, e.g. in x86/HVM guest
> Status: Supported => Status, domU: Supported

The rendering is indeed not ideal.  Our options are:

 (a) Live with it and document it.

 (b) Make it our practice to go always back and backport a name
 change for a feature to all versions.  I'm not sure this is worth
 the effort.

 (c) Invent some new equivalency metadata to put into SUPPORT.md or
 even into some other file in-tree.  Urgh, I don't want to do
 that.

I chose (a). You will see a paragraph about this at the top of the
html page:

  Sometimes the same feature, or a similar feature, is named
  differently in the documentation for different releases.  In such
  cases the table will show it as two separate features, with a
  discontinuity in support, even though support may have been
  continuous.

I can live with this approach

> We probably need to go through some of these in 4.10 and fix them
> But for 4.11 this is correct

I think the 4.10 documentation is not wrong, just differently
expressed.

> The implication is that we need to minimize unnecessary changes to 
> a) headings
> b) clarifications to status before the colon
> or backport them to older versions of SUPPORT.md. Otherwise the generated 
table will become confusing

See above.  If you want to backport the heading changes, I'll ack your
patches :-).

Happy to pick this up

>  ### Direct-boot kernel image format
>  
> +Format which the toolstack accepts for direct-boot kernels
> +
>  Supported, x86: bzImage, ELF
>  Supported, ARM32: zImage
>  Supported, ARM64: Image
>  
> -Format which the toolstack accepts for direct-boot kernels
> -
> 
> Note: the format here is wrong in both 4.10 and 4.11, this should be 
something like
> 
>  Status, zImage (ARM32): Supported
> 
> Lars will submit a separate patch

This is not a blocker because I added parsing code for this format.
If you fix it, we can drop that, too, once the change is backported.

>  ## Scalability
>  
>  ### Super page support
>  
> -Status, x86 HVM/PVH, HAP: Supported
> -Status, x86 HVM/PVH, Shadow, 2MiB: Supported
> -Status, ARM: Supported
> -
>  NB that this refers to the ability of guests
> 
> The beginning of this sentence should probably be changed to
> "This feature refers to the ability of guests ..."

Or even just "The ability of guests ..." since we don't normally lead
each thing with "this is".  I think this is not very important.  If
you want to improve it I will ack your patch.

Sure, I can roll this up with the other changes on my list

>  ## Virtual Hardware, QEMU
>  
> -These are devices available in HVM mode using a qemu devicemodel 
(the default).
> +This 

Re: [Xen-devel] [PATCH 4/5] SUPPORT.md: Move descriptions up before Status info

[Ian Jackson]

Lars Kurth writes ("Re: [PATCH 4/5] SUPPORT.md: Move descriptions up before 
Status info"):
> There were a couple of minor text changes for grammar reasons, which I 
> noticed and highlighted.

Thanks.

> I also checked the code motions. There are some things which need to be 
> pointed out, but they should not prevent this series from being checked in.
> 
> However, a couple were missed
> * ### PV Console (frontend) => missed moving the note (which is a definition)

That's one, not a couple.  I have fixed it.

> I also spotted a few other inconsistencies, which we probably should fix, but 
> these need backporting
> * ARM: 16K and 64K page granularity in guests
> * ARM: Guest Device Tree support
> * ARM: Guest ACPI support
> In all the other section headers we use x86/ or ARM/

I think "x86:" and "ARM:" are more natural so I would prefer that
bikeshed purple rather than blue.  I think the "/" came from the
example of the guest types, which are indeed in some sense "x86/HVM"
rather than "x86: HVM".

I think we should treat that as a separate issue from this series.

> -### x86/PVH
> -
>  Status, domU: Supported
> -Status, dom0: Experimental
> +
> +### x86/PVH
>  
>  PVH is a next-generation paravirtualized mode
>  designed to take advantage of hardware virtualization support when 
> possible.
> 
> Looks correct from a mere refactoring perspective, but generates some odd 
> behaviour in 
> https://xenbits.xen.org/people/iwj/2018/support-matrix-example-B-v1/t.html
> 
> The underlying reason is that we had some headline re-names between 4.10 and 
> 4.11. e.g.
> ARM guest => ARM
> 
> And some support statement changes, e.g. in x86/HVM guest
> Status: Supported => Status, domU: Supported

The rendering is indeed not ideal.  Our options are:

 (a) Live with it and document it.

 (b) Make it our practice to go always back and backport a name
 change for a feature to all versions.  I'm not sure this is worth
 the effort.

 (c) Invent some new equivalency metadata to put into SUPPORT.md or
 even into some other file in-tree.  Urgh, I don't want to do
 that.

I chose (a). You will see a paragraph about this at the top of the
html page:

  Sometimes the same feature, or a similar feature, is named
  differently in the documentation for different releases.  In such
  cases the table will show it as two separate features, with a
  discontinuity in support, even though support may have been
  continuous.

> We probably need to go through some of these in 4.10 and fix them
> But for 4.11 this is correct

I think the 4.10 documentation is not wrong, just differently
expressed.

> The implication is that we need to minimize unnecessary changes to 
> a) headings
> b) clarifications to status before the colon
> or backport them to older versions of SUPPORT.md. Otherwise the generated 
> table will become confusing

See above.  If you want to backport the heading changes, I'll ack your
patches :-).

>  ### Direct-boot kernel image format
>  
> +Format which the toolstack accepts for direct-boot kernels
> +
>  Supported, x86: bzImage, ELF
>  Supported, ARM32: zImage
>  Supported, ARM64: Image
>  
> -Format which the toolstack accepts for direct-boot kernels
> -
> 
> Note: the format here is wrong in both 4.10 and 4.11, this should be 
> something like
> 
>  Status, zImage (ARM32): Supported
> 
> Lars will submit a separate patch

This is not a blocker because I added parsing code for this format.
If you fix it, we can drop that, too, once the change is backported.

>  ## Scalability
>  
>  ### Super page support
>  
> -Status, x86 HVM/PVH, HAP: Supported
> -Status, x86 HVM/PVH, Shadow, 2MiB: Supported
> -Status, ARM: Supported
> -
>  NB that this refers to the ability of guests
> 
> The beginning of this sentence should probably be changed to
> "This feature refers to the ability of guests ..."

Or even just "The ability of guests ..." since we don't normally lead
each thing with "this is".  I think this is not very important.  If
you want to improve it I will ack your patch.

>  ## Virtual Hardware, QEMU
>  
> -These are devices available in HVM mode using a qemu devicemodel (the 
> default).
> +This section describes supported devices available in HVM mode using a
> +qemu devicemodel (the default).
> +
> +Status: Support scope restricted 
> +
>  Note that other devices are available but not security supported.
> 
> This is causing a rendering issue: the footnote is not generated in the right 
> place. It is added to " stgvga". Presumably a corner case in the table 
> generation tool

Yes.  It is generating semantically invalid html which renders very
oddly, too.  I will fix it.

Thanks,
Ian.

___
Xen-devel mailing list
Xen-devel@lists.xenproject.org

[Xen-devel] [PATCH 4/5] SUPPORT.md: Move descriptions up before Status info

[Ian Jackson]

This turns all the things which were treated as caveats, but which
don't need to be footnoted in the matrix, into descriptions.

For the benefit of the support matrix generator, this patch (or a
version of it) should be backported to 4.10.

Signed-off-by: Ian Jackson 
---
 SUPPORT.md | 213 -
 1 file changed, 111 insertions(+), 102 deletions(-)

diff --git a/SUPPORT.md b/SUPPORT.md
index 264b23f..5ae84cf 100644
--- a/SUPPORT.md
+++ b/SUPPORT.md
@@ -58,32 +58,29 @@ for the definitions of the support status levels etc.
 
 ### ARM/GICv3 ITS
 
-Status: Experimental
-
 Extension to the GICv3 interrupt controller to support MSI.
 
+Status: Experimental
+
 ## Guest Type
 
 ### x86/PV
 
-Status: Supported
-
 Traditional Xen PV guest
 
 No hardware requirements
 
-### x86/HVM
+Status: Supported
 
-Status, domU: Supported
+### x86/HVM
 
 Fully virtualised guest using hardware virtualisation extensions
 
 Requires hardware virtualisation support (Intel VMX / AMD SVM)
 
-### x86/PVH
-
 Status, domU: Supported
-Status, dom0: Experimental
+
+### x86/PVH
 
 PVH is a next-generation paravirtualized mode
 designed to take advantage of hardware virtualization support when possible.
@@ -93,12 +90,15 @@ Requires hardware virtualisation support (Intel VMX / AMD 
SVM).
 
 Dom0 support requires an IOMMU (Intel VT-d / AMD IOMMU).
 
-### ARM
+Status, domU: Supported
+Status, dom0: Experimental
 
-Status: Supported
+### ARM
 
 ARM only has one guest type at the moment
 
+Status: Supported
+
 ## Toolstack
 
 ### xl
@@ -107,12 +107,12 @@ ARM only has one guest type at the moment
 
 ### Direct-boot kernel image format
 
+Format which the toolstack accepts for direct-boot kernels
+
 Supported, x86: bzImage, ELF
 Supported, ARM32: zImage
 Supported, ARM64: Image
 
-Format which the toolstack accepts for direct-boot kernels
-
 ### Dom0 init support for xl
 
 Status, SysV: Supported
@@ -121,10 +121,10 @@ Format which the toolstack accepts for direct-boot kernels
 
 ### JSON output support for xl
 
-Status: Experimental
-
 Output of information in machine-parseable JSON format
 
+Status: Experimental
+
 ### Open vSwitch integration for xl
 
 Status, Linux: Supported
@@ -157,17 +157,18 @@ Output of information in machine-parseable JSON format
 
 ### Hypervisor 'debug keys'
 
-Status: Supported, not security supported
-
 These are functions triggered either from the host serial console,
 or via the xl 'debug-keys' command,
 which cause Xen to dump various hypervisor state to the console.
 
+Status: Supported, not security supported
+
 ### Hypervisor synchronous console output (sync_console)
 
+Xen command-line flag to force synchronous console output.
+
 Status: Supported, not security supported
 
-Xen command-line flag to force synchronous console output.
 Useful for debugging, but not suitable for production environments
 due to incurred overhead.
 
@@ -179,56 +180,54 @@ Debugger to debug ELF guests
 
 ### Soft-reset for PV guests
 
-Status: Supported
-
 Soft-reset allows a new kernel to start 'from scratch' with a fresh VM state,
 but with all the memory from the previous state of the VM intact.
 This is primarily designed to allow "crash kernels",
 which can do core dumps of memory to help with debugging in the event of a 
crash.
 
-### xentrace
+Status: Supported
 
-Status, x86: Supported
+### xentrace
 
 Tool to capture Xen trace buffer data
 
-### gcov
+Status, x86: Supported
 
-Status: Supported, Not security supported
+### gcov
 
 Export hypervisor coverage data suitable for analysis by gcov or lcov.
 
+Status: Supported, Not security supported
+
 ## Memory Management
 
 ### Dynamic memory control
 
-Status: Supported
-
 Allows a guest to add or remove memory after boot-time.
 This is typically done by a guest kernel agent known as a "balloon driver".
 
-### Populate-on-demand memory
+Status: Supported
 
-Status, x86 HVM: Supported
+### Populate-on-demand memory
 
 This is a mechanism that allows normal operating systems with only a balloon 
driver
 to boot with memory < maxmem.
 
-### Memory Sharing
+Status, x86 HVM: Supported
 
-Status, x86 HVM: Expermental
+### Memory Sharing
 
 Allow sharing of identical pages between guests
 
-### Memory Paging
+Status, x86 HVM: Expermental
 
-Status, x86 HVM: Experimenal
+### Memory Paging
 
 Allow pages belonging to guests to be paged to disk
 
-### Transcendent Memory
+Status, x86 HVM: Experimenal
 
-Status: Experimental
+### Transcendent Memory
 
 Transcendent Memory (tmem) allows the creation of hypervisor memory pools
 which guests can use to store memory
@@ -236,96 +235,100 @@ rather than caching in its own memory or swapping to 
disk.
 Having these in the hypervisor
 can allow more efficient aggregate use of memory across VMs.
 
-### Alternative p2m
+