broken build on staging docs

broken build on staging docs

[Doug Goldstein]

[-- Attachment #1.1.1: Type: text/plain, Size: 671 bytes --]

Since change 7782db9260d4c6499458de4e8d9866bc0427e143 the build has been
broken. See https://gitlab.com/xen-project/xen/pipelines/20403549 for
logs. Ultimately its because HTML::TreeBuilder::XPath is now a required
Perl module. Previously the only necessary Perl modules where those
shipped in the core of Perl. While I've got no problem updating all the
containers to include it, there is a bit of a conundrum where
CentOS/RHEL don't actually package and include it. I've also checked
EPEL and its not included. Not sure what approach folks would like to
take as this will require people to bust out CPAN for RHEL/CentOS based
builds.

-- 
Doug Goldstein


[-- Attachment #1.2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 963 bytes --]

[-- Attachment #2: Type: text/plain, Size: 157 bytes --]

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

[PATCH] docs/gen-html-index: Make HTML::TreeBuilder::XPath optional again

[Ian Jackson]

7782db9260d4 "docs/gen-html-index: Extract titles from HTML documents"
requires HTML::TreeBuilder::XPath.

This is sadly not as widely available as I had hoped.  Work around
this problem by making the use of this module optional: instead of
`use'ing at the toplevel, we `require' it in the eval.  If it's not
present, then the title is simply not extracted and the filename is
used as before, which is tolerable.

Reported-by: Doug Goldstein <cardoe@cardoe.com>
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
---
 docs/gen-html-index | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/docs/gen-html-index b/docs/gen-html-index
index 8258e2b..4fad6db 100644
--- a/docs/gen-html-index
+++ b/docs/gen-html-index
@@ -10,7 +10,6 @@ use warnings;
 use Getopt::Long;
 use IO::File;
 use File::Basename;
-use HTML::TreeBuilder::XPath;
 
 Getopt::Long::Configure('bundling');
 
@@ -21,8 +20,10 @@ our @dirs;
 our %index;
 
 our $outdir;
+our $debug;
 
-GetOptions("i=s" => sub { read_index(@_);} )
+GetOptions("i=s" => sub { read_index(@_);},
+           "D" => \$debug)
     or die;
 
 ($outdir,@docs) = @ARGV;
@@ -68,6 +69,7 @@ sub make_linktext ($) {
 
     my $from_html;
     eval {
+        require HTML::TreeBuilder::XPath;
         my $tree = new HTML::TreeBuilder::XPath;
         my $f = "$outdir/$l.html";
         open F, '<', $f or die "$l $f $!";
@@ -75,6 +77,7 @@ sub make_linktext ($) {
         close F;
         $from_html = $tree->findvalue("/html/head/title");
     };
+    print "$l: get title: $@" if $@ && $debug;
     return $from_html if $from_html;
 
     return basename($l);
-- 
2.1.4


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

Re: broken build on staging docs

[Ian Jackson]

Doug Goldstein writes ("broken build on staging docs"):
> Since change 7782db9260d4c6499458de4e8d9866bc0427e143 the build has been
> broken. See https://gitlab.com/xen-project/xen/pipelines/20403549 for
> logs. Ultimately its because HTML::TreeBuilder::XPath is now a required
> Perl module. Previously the only necessary Perl modules where those
> shipped in the core of Perl. While I've got no problem updating all the
> containers to include it, there is a bit of a conundrum where
> CentOS/RHEL don't actually package and include it. I've also checked
> EPEL and its not included. Not sure what approach folks would like to
> take as this will require people to bust out CPAN for RHEL/CentOS based
> builds.

I've just posted a patch which I think will fix this for you.  Can you
try it please ?

 [PATCH] docs/gen-html-index: Make HTML::TreeBuilder::XPath optional again

Thanks,
Ian.

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

Re: [PATCH] docs/gen-html-index: Make HTML::TreeBuilder::XPath optional again

[Doug Goldstein]

On 4/13/18 8:58 AM, Ian Jackson wrote:
> 7782db9260d4 "docs/gen-html-index: Extract titles from HTML documents"
> requires HTML::TreeBuilder::XPath.
> 
> This is sadly not as widely available as I had hoped.  Work around
> this problem by making the use of this module optional: instead of
> `use'ing at the toplevel, we `require' it in the eval.  If it's not
> present, then the title is simply not extracted and the filename is
> used as before, which is tolerable.
> 
> Reported-by: Doug Goldstein <cardoe@cardoe.com>
> Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>

Reviewed-by: Doug Goldstein <cardoe@cardoe.com>
Tested-by: Doug Goldstein <cardoe@cardoe.com>

The test run is here: https://gitlab.com/cardoe/xen/pipelines/20462270

-- 
Doug Goldstein

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

Re: [PATCH] docs/gen-html-index: Make HTML::TreeBuilder::XPath optional again

[Ian Jackson]

Doug Goldstein writes ("Re: [PATCH] docs/gen-html-index: Make HTML::TreeBuilder::XPath optional again"):
> Reviewed-by: Doug Goldstein <cardoe@cardoe.com>
> Tested-by: Doug Goldstein <cardoe@cardoe.com>
> 
> The test run is here: https://gitlab.com/cardoe/xen/pipelines/20462270

Thanks.  Since this bug was blocking the smoke test, I have pushed
this fix.

Ian.

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

[PATCH v2 0/7] SUPPORT.md: Distinguish descriptions from caveats

[Ian Jackson]

The new support matrix output puts a [*] after each entry in the
support matrix in many cases where the linked-to text is simply a
longer description of the feature.

Remedy this by distinguishing text which expands on a feature
description from text which qualifies its support status.

There are 3 patches to processing machinery, followed by two patches
to SUPPORT.md (one to make the distinction, throughout, and one to
document it); followed by two patches to fix a bug (logically these
should come first, but rebasing them is annoying).

The patches to SUPPORT.md would ideally go to 4.10 too.

Example output:
  https://xenbits.xen.org/people/iwj/2018/support-matrix-example-B-v2/t.html

   r 1/7  docs/parse-support-md: internals: Introduce docref_a
   r 2/7  docs/parse-support-md: internals: Rename HasText to
   r 3/7  SUPPORT.md, support matrix: Treat commentary before
  *r 4/7  SUPPORT.md: Move descriptions up before Status info
 a r 5/7  SUPPORT.md: Document the new text ordering rule
  +  6/7  docs/parse-support.md: Add some newlines to the table
  +  7/7  docs/parse-support-md: Correctly handle footnotes for

 + = New patch in v2
 * = Amended patch in v2
 r = Release-acked
 a = Acked by appropriate maintainer and/or community manager


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

[PATCH 1/7] docs/parse-support-md: internals: Introduce docref_a

[Ian Jackson]

No functional change.

Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
Release-acked-by: Juergen Gross <jgross@suse.com>
---
 docs/parse-support-md | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/docs/parse-support-md b/docs/parse-support-md
index decda33..5bf8405 100755
--- a/docs/parse-support-md
+++ b/docs/parse-support-md
@@ -318,6 +318,12 @@ sub o { print @_ or die $!; }
 
 our @pending_headings;
 
+sub docref_a ($$) {
+    my ($i, $realsect) = @_;
+    return sprintf '<a href="%s#%s">',
+        $version_urls[$i], $realsect->{Anchor};
+}
+
 sub write_output_row ($) {
     my ($sectnode) = @_;
 #    print STDERR 'WOR ', Dumper($d, $sectnode);
@@ -364,8 +370,8 @@ sub write_output_row ($) {
                 && $sectnode->{RealSect}{Anchor}) {
                 my $rows = $sectnode->{RealSect}{Rows};
                 $nextcell = sprintf '<td rowspan=%d>', $rows;
-                $nextcell .= sprintf '<a href="%s#%s">[*]</a>',
-                    $version_urls[$i], $sectnode->{RealSect}{Anchor};
+                $nextcell .= docref_a $i, $sectnode->{RealSect};
+                $nextcell .= '[*]</a>';
                 $nextcell .= '</td>';
                 $colspan = '';
             }
-- 
2.1.4


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

[PATCH 2/7] docs/parse-support-md: internals: Rename HasText to HasCaveat

[Ian Jackson]

No functional change.

Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
Release-acked-by: Juergen Gross <jgross@suse.com>
---
 docs/parse-support-md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/parse-support-md b/docs/parse-support-md
index 5bf8405..6953930 100755
--- a/docs/parse-support-md
+++ b/docs/parse-support-md
@@ -34,7 +34,7 @@ our $toplevel_sectlist = new_sectlist();
 # $sectlist->{KEY}{Children} = a further $sectlist
 # $sectlist->{KEY}{Key} = KEY
 # $sectlist->{KEY}{RealSect} = containing real section in @insections, so
-# $sectlist->{KEY}{RealSect}{HasText}[VI] = trueish iff there was a Para
+# $sectlist->{KEY}{RealSect}{HasCaveat}[VI] = trueish iff other in a Para
 # $sectlist->{KEY}{RealSect}{Anchor} = value for < id="" > in the pandoc html
 # A $sectnode represents a single section from the original markdown
 # document.  Its subsections are in Children.
@@ -57,7 +57,7 @@ our @insections;
 # $insections[]{Headline} = markdown content
 # these next are only defined for real sections, not Status elements
 # $insections[]{Anchor} = string
-# $insections[]{HasText} = array, $sectlist->{HasText} will refer to this
+# $insections[]{HasCaveat} = array, $sectlist->{HasCaveat} will refer to this
 
 our $had_unknown;
 # adding new variable ?  it must be reset in r_toplevel
@@ -77,14 +77,14 @@ sub ri_Header {
          Key => $id,
          Anchor => $id,
          Headline => $hl,
-         HasText => [],
+         HasCaveat => [],
         };
 #print STDERR Dumper(\@insections);
 }
 
 sub ri_Para {
     if (@insections) {
-        $insections[$#insections]{HasText}[$version_index] = 1;
+        $insections[$#insections]{HasCaveat}[$version_index] = 1;
     }
 };
 
@@ -366,7 +366,7 @@ sub write_output_row ($) {
         my $nextcell = '';
         if (!defined $colspan) { # first row of this RealSect
             $colspan= ' colspan="2"';
-            if ($sectnode->{RealSect}{HasText}[$i] && $st
+            if ($sectnode->{RealSect}{HasCaveat}[$i] && $st
                 && $sectnode->{RealSect}{Anchor}) {
                 my $rows = $sectnode->{RealSect}{Rows};
                 $nextcell = sprintf '<td rowspan=%d>', $rows;
-- 
2.1.4


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

[PATCH 3/7] SUPPORT.md, support matrix: Treat commentary before status as description

[Ian Jackson]

Running text in feature sections in the markdown document currently
might be (i) a caveat, qualifying or clarifying the support statement
(ii) a plain description of the feature.

Caveats can be version-specific and deserve the [*] annotation in the
relevant feature matrix cell.  They must link to SUPPORT.html for the
specific version.

Descriptions are not version specific.  In that case the [*]
annotation is visusal noise.  Rather, it is better to make a hyperlink
out of the text which is being expanded on.  The hyperlink can point
to any appropriate version.

There is a question about how to notate this distinction in
SUPPORT.md.  After IRL discussion with George and Lars I propose that
we should put text which helps describe a feature (ie, which expands
on a section heading) after the heading but before the Status
indications; whereas, caveats and supplementary information about
the actual status, should follow the Status block.

This patch implements this distinction in the support matrix
generator.  Only paragraphs containing _only_ italic content count as
descriptive; anything else is treated as a caveat.

In the code:

 * Add a new entry to RealSect, HasDescription

 * When parsing, track whether we are before or after the first Status
   block in a new variable $has_feature.

 * In ri_Para, set HasDescription set to the input document index
   when we encounter text before the first feature.

 * When writing a `heading' (ie, the table cell for a feature name)
   look for HasDescription and make an appropriate hyperlink.

Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
Release-acked-by: Juergen Gross <jgross@suse.com>
---
 docs/parse-support-md | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/docs/parse-support-md b/docs/parse-support-md
index 6953930..653d216 100755
--- a/docs/parse-support-md
+++ b/docs/parse-support-md
@@ -35,6 +35,7 @@ our $toplevel_sectlist = new_sectlist();
 # $sectlist->{KEY}{Key} = KEY
 # $sectlist->{KEY}{RealSect} = containing real section in @insections, so
 # $sectlist->{KEY}{RealSect}{HasCaveat}[VI] = trueish iff other in a Para
+# $sectlist->{KEY}{RealSect}{HasDescription} = VI for some Emph in Para
 # $sectlist->{KEY}{RealSect}{Anchor} = value for < id="" > in the pandoc html
 # A $sectnode represents a single section from the original markdown
 # document.  Its subsections are in Children.
@@ -58,8 +59,10 @@ our @insections;
 # these next are only defined for real sections, not Status elements
 # $insections[]{Anchor} = string
 # $insections[]{HasCaveat} = array, $sectlist->{HasCaveat} will refer to this
+# $insections[]{HasDescription} VI, likewise
 
 our $had_unknown;
+our $had_feature;
 # adding new variable ?  it must be reset in r_toplevel
 
 #---------- parsing ----------
@@ -78,13 +81,20 @@ sub ri_Header {
          Anchor => $id,
          Headline => $hl,
          HasCaveat => [],
+         HasDescription => undef,
         };
 #print STDERR Dumper(\@insections);
+    $had_feature = 0;
 }
 
 sub ri_Para {
-    if (@insections) {
-        $insections[$#insections]{HasCaveat}[$version_index] = 1;
+    return unless @insections;
+    my $insection = $insections[$#insections];
+
+    if ($had_feature) {
+        $insection->{HasCaveat}[$version_index] = 1;
+    } else {
+        $insection->{HasDescription} //= $version_index;
     }
 };
 
@@ -92,6 +102,8 @@ sub parse_feature_entry ($) {
     my ($value) = @_;
     die unless @insections;
 
+    $had_feature = 1;
+
     my $sectnode;
     my $realsect;
     foreach my $s (@insections) {
@@ -183,6 +195,7 @@ sub r_toplevel ($) {
 
     @insections = ();
     $had_unknown = undef;
+    $had_feature = undef;
 
     foreach my $e (@$i) {
         next unless ref $e eq 'ARRAY';
@@ -346,7 +359,14 @@ sub write_output_row ($) {
         $span->('col', $maxdepth - $heading->{Depth} + 1)
             if !%{ $heading->{Children} };
         o(' align="left">');
+        my $end_a = '';
+        my $desc_i = $heading->{RealSect}{HasDescription};
+        if (defined $desc_i) {
+            o(docref_a $desc_i, $heading->{RealSect});
+            $end_a= '</a>';
+        }
         o($heading->{Headline});
+        o($end_a);
         o('</th>');
     }
     if (%{ $sectnode->{Children} }) {
-- 
2.1.4


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

[PATCH 4/7] 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 <Ian.Jackson@eu.citrix.com>
Release-acked-by: Juergen Gross <jgross@suse.com>
---
v2: Move definition of "PV Console (frontend) too"
---
 SUPPORT.md | 217 ++++++++++++++++++++++++++++++++-----------------------------
 1 file changed, 113 insertions(+), 104 deletions(-)

diff --git a/SUPPORT.md b/SUPPORT.md
index 264b23f..3e3890b 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
+    Status: Experimental
 
-    Status, x86 HVM: Tech Preview
-    Status, ARM: Tech Preview
+### Alternative p2m
 
 Allows external monitoring of hypervisor memory
 by maintaining multiple physical to machine (p2m) memory mappings.
 
+    Status, x86 HVM: Tech Preview
+    Status, ARM: Tech Preview
+
 ## Resource Management
 
 ### CPU Pools
 
-    Status: Supported
-
 Groups physical cpus into distinct groups called "cpupools",
 with each pool having the capability
 of using different schedulers and scheduling properties.
 
-### Credit Scheduler
-
     Status: Supported
 
+### Credit Scheduler
+
 A weighted proportional fair share virtual CPU scheduler.
 This is the default scheduler.
 
-### Credit2 Scheduler
-
     Status: Supported
 
+### Credit2 Scheduler
+
 A general purpose scheduler for Xen,
 designed with particular focus on fairness, responsiveness, and scalability
 
-### RTDS based Scheduler
+    Status: Supported
 
-    Status: Experimental
+### RTDS based Scheduler
 
 A soft real-time CPU scheduler
 built to provide guaranteed CPU capacity to guest VMs on SMP hosts
 
+    Status: Experimental
+
 ### ARINC653 Scheduler
 
+A periodically repeating fixed timeslice scheduler.
+
     Status: Supported
 
-A periodically repeating fixed timeslice scheduler.
 Currently only single-vcpu domains are supported.
 
 ### Null Scheduler
 
-    Status: Experimental
-
 A very simple, very static scheduling policy
 that always schedules the same vCPU(s) on the same pCPU(s).
 It is designed for maximum determinism and minimum overhead
 on embedded platforms.
 
-### NUMA scheduler affinity
+    Status: Experimental
 
-    Status, x86: Supported
+### NUMA scheduler affinity
 
 Enables NUMA aware scheduling in Xen
 
+    Status, x86: Supported
+
 ## 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
 to have higher-level page table entries point directly to memory,
 improving TLB performance.
 On ARM, and on x86 in HAP mode,
 the guest has whatever support is enabled by the hardware.
+
+This feature is independent
+of the ARM "page granularity" feature (see below).
+
+    Status, x86 HVM/PVH, HAP: Supported
+    Status, x86 HVM/PVH, Shadow, 2MiB: Supported
+    Status, ARM: Supported
+
 On x86 in shadow mode, only 2MiB (L2) superpages are available;
 furthermore, they do not have the performance characteristics
 of hardware superpages.
 
-Also note is feature independent
-of the ARM "page granularity" feature (see below).
-
 ### x86/PVHVM
 
-    Status: Supported
-
 This is a useful label for a set of hypervisor features
 which add paravirtualized functionality to HVM guests
 for improved performance and scalability.
 This includes exposing event channels to HVM guests.
 
+    Status: Supported
+
 ## High Availability and Fault Tolerance
 
 ### Remus Fault Tolerance
@@ -338,54 +341,54 @@ This includes exposing event channels to HVM guests.
 
 ### x86/vMCE
 
-    Status: Supported
-
 Forward Machine Check Exceptions to appropriate guests
 
+    Status: Supported
+
 ## Virtual driver support, guest side
 
 ### Blkfront
 
+Guest-side driver capable of speaking the Xen PV block protocol
+
     Status, Linux: Supported
     Status, FreeBSD: Supported, Security support external
     Status, NetBSD: Supported, Security support external
     Status, OpenBSD: Supported, Security support external
     Status, Windows: Supported
 
-Guest-side driver capable of speaking the Xen PV block protocol
-
 ### Netfront
 
+Guest-side driver capable of speaking the Xen PV networking protocol
+
     Status, Linux: Supported
     Status, FreeBSD: Supported, Security support external
     Status, NetBSD: Supported, Security support external
     Status, OpenBSD: Supported, Security support external
     Status, Windows: Supported
 
-Guest-side driver capable of speaking the Xen PV networking protocol
-
 ### PV Framebuffer (frontend)
 
-    Status, Linux (xen-fbfront): Supported
-
 Guest-side driver capable of speaking the Xen PV Framebuffer protocol
 
+    Status, Linux (xen-fbfront): Supported
+
 ### PV Console (frontend)
 
+Guest-side driver capable of speaking the Xen PV console protocol
+
     Status, Linux (hvc_xen): Supported
     Status, FreeBSD: Supported, Security support external
     Status, NetBSD: Supported, Security support external
     Status, Windows: Supported
 
-Guest-side driver capable of speaking the Xen PV console protocol
-
 ### PV keyboard (frontend)
 
-    Status, Linux (xen-kbdfront): Supported
-
 Guest-side driver capable of speaking the Xen PV keyboard protocol.
 Note that the "keyboard protocol" includes mouse / pointer support as well.
 
+    Status, Linux (xen-kbdfront): Supported
+
 ### PV USB (frontend)
 
     Status, Linux: Supported
@@ -399,22 +402,22 @@ there is currently no xl support.
 
 ### PV TPM (frontend)
 
-    Status, Linux (xen-tpmfront): Tech Preview
-
 Guest-side driver capable of speaking the Xen PV TPM protocol
 
-### PV 9pfs frontend
+    Status, Linux (xen-tpmfront): Tech Preview
 
-    Status, Linux: Tech Preview
+### PV 9pfs frontend
 
 Guest-side driver capable of speaking the Xen 9pfs protocol
 
-### PVCalls (frontend)
-
     Status, Linux: Tech Preview
 
+### PVCalls (frontend)
+
 Guest-side driver capable of making pv system calls
 
+    Status, Linux: Tech Preview
+
 ## Virtual device support, host side
 
 For host-side virtual device support,
@@ -423,6 +426,8 @@ unless otherwise noted.
 
 ### Blkback
 
+Host-side implementations of the Xen PV block protocol.
+
     Status, Linux (xen-blkback): Supported
     Status, QEMU (xen_disk), raw format: Supported
     Status, QEMU (xen_disk), qcow format: Supported
@@ -433,42 +438,41 @@ unless otherwise noted.
     Status, Blktap2, raw format: Deprecated
     Status, Blktap2, vhd format: Deprecated
 
-Host-side implementations of the Xen PV block protocol.
 Backends only support raw format unless otherwise specified.
 
 ### Netback
 
+Host-side implementations of Xen PV network protocol
+
     Status, Linux (xen-netback): Supported
     Status, FreeBSD (netback): Supported, Security support external
     Status, NetBSD (xennetback): Supported, Security support external
 
-Host-side implementations of Xen PV network protocol
-
 ### PV Framebuffer (backend)
 
-    Status, QEMU: Supported
-
 Host-side implementation of the Xen PV framebuffer protocol
 
-### PV Console (xenconsoled)
+    Status, QEMU: Supported
 
-    Status: Supported
+### PV Console (xenconsoled)
 
 Host-side implementation of the Xen PV console protocol
 
-### PV keyboard (backend)
+    Status: Supported
 
-    Status, QEMU: Supported
+### PV keyboard (backend)
 
 Host-side implementation of the Xen PV keyboard protocol.
 Note that the "keyboard protocol" includes mouse / pointer support as well.
 
-### PV USB (backend)
-
     Status, QEMU: Supported
 
+### PV USB (backend)
+
 Host-side implementation of the Xen PV USB protocol
 
+    Status, QEMU: Supported
+
 ### PV SCSI protocol (backend)
 
     Status, Linux: Experimental
@@ -499,11 +503,11 @@ but has no xl support.
 
 ### Driver Domains
 
-    Status: Supported, with caveats
-
 "Driver domains" means allowing non-Domain 0 domains
 with access to physical devices to act as back-ends.
 
+    Status: Supported, with caveats
+
 See the appropriate "Device Passthrough" section
 for more information about security support.
 
@@ -553,13 +557,13 @@ with dom0, driver domains, stub domains, domUs, and so on.
 
 ### x86/Nested PV
 
-    Status, x86 Xen HVM: Tech Preview
-
 This means running a Xen hypervisor inside an HVM domain on a Xen system,
 with support for PV L2 guests only
 (i.e., hardware virtualization extensions not provided
 to the guest).
 
+    Status, x86 Xen HVM: Tech Preview
+
 This works, but has performance limitations
 because the L1 dom0 can only access emulated L1 devices.
 
@@ -568,19 +572,19 @@ but nobody has reported on performance.
 
 ### x86/Nested HVM
 
-    Status, x86 HVM: Experimental
-
 This means providing hardware virtulization support to guest VMs
 allowing, for instance, a nested Xen to support both PV and HVM guests.
 It also implies support for other hypervisors,
 such as KVM, Hyper-V, Bromium, and so on as guests.
 
-### vPMU
+    Status, x86 HVM: Experimental
 
-    Status, x86: Supported, Not security supported
+### vPMU
 
 Virtual Performance Management Unit for HVM guests
 
+    Status, x86: Supported, Not security supported
+
 Disabled by default (enable with hypervisor command line option).
 This feature is not security supported: see http://xenbits.xen.org/xsa/advisory-163.html
 
@@ -604,14 +608,14 @@ when used to remove drivers and backends from domain 0
 
 ### x86/Multiple IOREQ servers
 
-	Status: Experimental
-
 An IOREQ server provides emulated devices to HVM and PVH guests.
 QEMU is normally the only IOREQ server,
 but Xen has support for multiple IOREQ servers.
 This allows for custom or proprietary device emulators
 to be used in addition to QEMU.
 
+	Status: Experimental
+
 ### ARM/Non-PCI device passthrough
 
     Status: Supported, not security supported
@@ -635,7 +639,11 @@ No support for QEMU backends in a 16K or 64K domain.
 
 ## 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.
 
 ### x86/Emulated platform devices (QEMU):
@@ -685,9 +693,10 @@ See the section **Blkback** for image formats supported by QEMU.
 
 ### x86/HVM iPXE
 
+Booting a guest via PXE.
+
     Status: Supported, with caveats
 
-Booting a guest via PXE.
 PXE inherently places full trust of the guest in the network,
 and so should only be used
 when the guest network is under the same administrative control
@@ -695,17 +704,17 @@ as the guest itself.
 
 ### x86/HVM BIOS
 
+Booting a guest via guest BIOS firmware
+
     Status, SeaBIOS (qemu-xen): Supported
     Status, ROMBIOS (qemu-xen-traditional): Supported
 
-Booting a guest via guest BIOS firmware
-
 ### x86/HVM OVMF
 
-    Status, qemu-xen: Supported
-
 OVMF firmware implements the UEFI boot protocol.
 
+    Status, qemu-xen: Supported
+
 # Format and definitions
 
 This file contains prose, and machine-readable fragments.
-- 
2.1.4


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

[PATCH 5/7] SUPPORT.md: Document the new text ordering rule

[Ian Jackson]

Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
Release-acked-by: Juergen Gross <jgross@suse.com>
---
 SUPPORT.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/SUPPORT.md b/SUPPORT.md
index 3e3890b..9eb6958 100644
--- a/SUPPORT.md
+++ b/SUPPORT.md
@@ -725,6 +725,11 @@ The file is in markdown format.
 The machine-readable fragments are markdown literals
 containing RFC-822-like (deb822-like) data.
 
+In each case, descriptions which expand on the name of a feature as
+provided in the section heading, precede the Status indications.
+Any paragraphs which follow the Status indication are caveats or
+qualifications of the information provided in Status fields.
+
 ## Keys found in the Feature Support subsections
 
 ### Status
-- 
2.1.4


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

[PATCH 6/7] docs/parse-support.md: Add some newlines to the table output

[Ian Jackson]

This makes the result easier for humans to read.

Signed-off-by: Ian Jackson <ian.jackson@eu.citrix.com>
---
v2: New patch
---
 docs/parse-support-md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/parse-support-md b/docs/parse-support-md
index 653d216..bbbb615 100755
--- a/docs/parse-support-md
+++ b/docs/parse-support-md
@@ -399,7 +399,7 @@ sub write_output_row ($) {
         }
 
         $st //= '-';
-        o("<td$colspan>");
+        o("\n<td$colspan>");
         my $end_a = '';
         if ($sectnode->{Key} eq 'release-support--xen-version') {
             o(sprintf '<a href="%s">', $version_urls[$i]);
-- 
2.1.4


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

[PATCH 7/7] docs/parse-support-md: Correctly handle footnotes for non-leaf sections

[Ian Jackson]

Non-leaf sections with footnotes must have a row of their own, for
just that section, because footnotes only appear if there is status
information.

In that case, the footnote applies to only the rows for that section
in the markdown document, ie that RealSect.

And of course for a leaf section that is true too.

So for footnoes we always want to use a rowspan of the number of
Status elements in the section.  So (i) calculate this in
count_rows_sectlist and (ii) use it, instead of the total number of
rows including all the subsections', when writing out the footnote
ref.

This bug has been present in this script since the beginning.

Also, while we're here, suppress the rowspan if it would be 1.

Reported-by: Lars Kurth <lars.kurth@citrix.com>
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
---
v2: New patch

Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
---
 docs/parse-support-md | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/docs/parse-support-md b/docs/parse-support-md
index bbbb615..218e12b 100755
--- a/docs/parse-support-md
+++ b/docs/parse-support-md
@@ -296,7 +296,11 @@ sub count_rows_sectlist ($);
 sub count_rows_sectnode ($) {
     my ($sectnode) = @_;
     my $rows = 0;
-    $rows++ if $sectnode->{Status};
+    $sectnode->{RealSect}{OwnRows} //= 0;
+    if ($sectnode->{Status}) {
+        $rows++;
+        $sectnode->{RealSect}{OwnRows}++;
+    }
     $rows += count_rows_sectlist $sectnode->{Children};
     $sectnode->{Rows} = $rows;
     $sectnode->{RealSect}{Rows} = $rows;
@@ -306,6 +310,7 @@ sub count_rows_sectnode ($) {
 # Now we have
 #   $sectnode->{Rows}
 #   $sectnode->{RealSect}{Rows}
+#   $sectnode->{RealSect}{OwnRows}
 
 sub count_rows_sectlist ($) {
     my ($sectlist) = @_;
@@ -388,8 +393,10 @@ sub write_output_row ($) {
             $colspan= ' colspan="2"';
             if ($sectnode->{RealSect}{HasCaveat}[$i] && $st
                 && $sectnode->{RealSect}{Anchor}) {
-                my $rows = $sectnode->{RealSect}{Rows};
-                $nextcell = sprintf '<td rowspan=%d>', $rows;
+                my $rows = $sectnode->{RealSect}{OwnRows};
+                $nextcell = '<td';
+                $nextcell .= sprintf ' rowspan=%d', $rows if $rows>1;
+                $nextcell .= '>';
                 $nextcell .= docref_a $i, $sectnode->{RealSect};
                 $nextcell .= '[*]</a>';
                 $nextcell .= '</td>';
-- 
2.1.4


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

Re: [PATCH 6/7] docs/parse-support.md: Add some newlines to the table output

[Juergen Gross]

On 17/04/18 16:47, Ian Jackson wrote:
> This makes the result easier for humans to read.
> 
> Signed-off-by: Ian Jackson <ian.jackson@eu.citrix.com>

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


Juergen

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

Re: [PATCH 7/7] docs/parse-support-md: Correctly handle footnotes for non-leaf sections

[Juergen Gross]

On 17/04/18 16:47, Ian Jackson wrote:
> Non-leaf sections with footnotes must have a row of their own, for
> just that section, because footnotes only appear if there is status
> information.
> 
> In that case, the footnote applies to only the rows for that section
> in the markdown document, ie that RealSect.
> 
> And of course for a leaf section that is true too.
> 
> So for footnoes we always want to use a rowspan of the number of
> Status elements in the section.  So (i) calculate this in
> count_rows_sectlist and (ii) use it, instead of the total number of
> rows including all the subsections', when writing out the footnote
> ref.
> 
> This bug has been present in this script since the beginning.
> 
> Also, while we're here, suppress the rowspan if it would be 1.
> 
> Reported-by: Lars Kurth <lars.kurth@citrix.com>
> Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>

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


Juergen

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