Skip to contentSkip to conversation

HMP: hxtool sanity checks

PATCH Superseded [email protected] 3 participants 12 messages Jan 15 – Jan 16

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

cover HMP: hxtool sanity checks

From: "Dr. David Alan Gilbert" <[email protected]>

Hi,
This adds a couple of sanity checks to hxtool to try and catch the type of mistake that Markus' patch fixes.
(Included Markus' patch since otherwise the script correctly fails)

Dave

Dr. David Alan Gilbert (3):
hmp*hx: Move info docs
hxtool: Split srst/erst add checks
hxtool: Error on missing docs

Markus Armbruster (1):
hmp-commands-info.hx: Move definition of "info accel"

 hmp-commands-info.hx | 33 +++++++++++++--------------------
 hmp-commands.hx      | 27 +++++++++++++++++----------
 scripts/hxtool       | 38 +++++++++++++++++++++++++++++++++++---
 3 files changed, 65 insertions(+), 33 deletions(-)
Signature · 1 line
2.52.0
#1 lore raw

PATCH 1/4 hmp-commands-info.hx: Move definition of "info accel"

From: Markus Armbruster <[email protected]>

Commit c10eb740108 (accel/system: Add 'info accel' on human monitor) inserted "info accel" in the middle of "info sync-profile". Move it behind "info sync-profile".

---
 hmp-commands-info.hx | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)
hmp-commands-info.hx +12 -12
index 41674dcbe1..74c741f80e 100644
@@ -267,18 +267,6 @@ ERST
         .cmd        = hmp_info_sync_profile,
     },
 
-    {
-        .name       = "accel",
-        .args_type  = "",
-        .params     = "",
-        .help       = "show accelerator statistics",
-    },
-
-SRST
-  ``info accel``
-    Show accelerator statistics.
-ERST
-
 SRST
   ``info sync-profile [-m|-n]`` [*max*]
     Show synchronization profiling info, up to *max* entries (default: 10),
@@ -294,6 +282,18 @@ SRST
     being coalesced.
 ERST
 
+    {
+        .name       = "accel",
+        .args_type  = "",
+        .params     = "",
+        .help       = "show accelerator statistics",
+    },
+
+SRST
+  ``info accel``
+    Show accelerator statistics.
+ERST
+
     {
         .name       = "kvm",
         .args_type  = "",
Signature · 1 line
2.52.0
#2 lore raw

PATCH 2/4 hmp*hx: Move info docs

In reply to [email protected]

From: "Dr. David Alan Gilbert" <[email protected]>

Move the docs for the info subcommand from the separate hx into the top level file next to the 'info' command itself. That makes every command in the top level file have a RST section.

---
 hmp-commands-info.hx |  9 +--------
 hmp-commands.hx      | 27 +++++++++++++++++----------
 2 files changed, 18 insertions(+), 18 deletions(-)
hmp-commands-info.hx +1 -8
index 74c741f80e..964eed004c 100644
@@ -8,14 +8,7 @@ HXCOMM
 HXCOMM In this file, generally SRST fragments should have two extra
 HXCOMM spaces of indent, so that the documentation list item for "info foo"
 HXCOMM appears inside the documentation list item for the top level
-HXCOMM "info" documentation entry. The exception is the first SRST
-HXCOMM fragment that defines that top level entry.
-
-SRST
-``info`` *subcommand*
-  Show various information about the system state.
-
-ERST
+HXCOMM "info" documentation entry.
 
     {
         .name       = "version",
hmp-commands.hx +17 -10
index 5cc4788f12..f4a6eeda93 100644
@@ -1814,16 +1814,6 @@ SRST
   command.
 ERST
 
-    {
-        .name       = "info",
-        .args_type  = "item:s?",
-        .params     = "[subcommand]",
-        .help       = "show various information about the system state",
-        .cmd        = hmp_info_help,
-        .sub_table  = hmp_info_cmds,
-        .flags      = "p",
-    },
-
 #if defined(CONFIG_FDT)
     {
         .name       = "dumpdtb",
@@ -1867,3 +1857,20 @@ SRST
   List event channels in the guest
 ERST
 #endif
+
+HXCOMM *** MUST BE LAST ENTRY **
+    {
+        .name       = "info",
+        .args_type  = "item:s?",
+        .params     = "[subcommand]",
+        .help       = "show various information about the system state",
+        .cmd        = hmp_info_help,
+        .sub_table  = hmp_info_cmds,
+        .flags      = "p",
+    },
+
+SRST
+``info`` *subcommand*
+  Show various information about the system state.
+ERST
+HXCOMM *** MUST BE LAST ENTRY **
Signature · 1 line
2.52.0
#3 lore raw

Re: [PATCH 2/4] hmp*hx: Move info docs

Quoted 7 lines · [email protected] writes:

From: "Dr. David Alan Gilbert" <[email protected]>

Move the docs for the info subcommand from the separate hx into the top level file next to the 'info' command itself. That makes every command in the top level file have a RST section.

Generated HTML changes slightly, diff appended. Shows as vertical space differences in Firefox. Do we care?

docs/manual/system/monitor.html renamed from docs.old/manual/system/monitor.html +7 -7
@@ -601,10 +601,11 @@ command.</p>
 </dd>
 <dt><code class="docutils literal notranslate"><span class="pre">xen-event-list</span></code></dt><dd><p>List event channels in the guest</p>
 </dd>
-</dl>
-<dl>
 <dt><code class="docutils literal notranslate"><span class="pre">info</span></code> <em>subcommand</em></dt><dd><p>Show various information about the system state.</p>
-<dl>
+</dd>
+</dl>
+<blockquote>
+<div><dl>
 <dt><code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">version</span></code></dt><dd><p>Show the version of QEMU.</p>
 </dd>
 <dt><code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">network</span></code></dt><dd><p>Show the network state.</p>
@@ -639,8 +640,6 @@ command.</p>
 </dd>
 <dt><code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">jit</span></code></dt><dd><p>Show dynamic compiler info.</p>
 </dd>
-<dt><code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">accel</span></code></dt><dd><p>Show accelerator statistics.</p>
-</dd>
 <dt><code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">sync-profile</span> <span class="pre">[-m|-n]</span></code> [<em>max</em>]</dt><dd><p>Show synchronization profiling info, up to <em>max</em> entries (default: 10),
 sorted by total wait time.</p>
 <dl class="simple">
@@ -653,6 +652,8 @@ sorted by total wait time.</p>
 the “Object” field shows—enclosed in brackets—the number of objects
 being coalesced.</p>
 </dd>
+<dt><code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">accel</span></code></dt><dd><p>Show accelerator statistics.</p>
+</dd>
 <dt><code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">kvm</span></code></dt><dd><p>Show KVM information.</p>
 </dd>
 <dt><code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">accelerators</span></code></dt><dd><p>Show which accelerators are compiled into a QEMU binary, and what accelerator
@@ -765,8 +766,7 @@ enabled) memory in bytes.</p>
 <dt><code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">firmware-log</span></code></dt><dd><p>Show the firmware (ovmf) debug log.</p>
 </dd>
 </dl>
-</dd>
-</dl>
+</div></blockquote>
 </section>
 <section id="integer-expressions">
 <h2>Integer expressions<a class="headerlink" href="#integer-expressions" title="Link to this heading"></a></h2>
#4 lore raw

Re: [PATCH 2/4] hmp*hx: Move info docs

Quoted 4 lines · * Markus Armbruster ([email protected]) wrote:
Quoted 2 lines · [email protected] writes:

From: "Dr. David Alan Gilbert" <[email protected]>

Quoted 8 lines
Quoted 5 lines

Move the docs for the info subcommand from the separate hx into the top level file next to the 'info' command itself. That makes every command in the top level file have a RST section.

Generated HTML changes slightly, diff appended. Shows as vertical space differences in Firefox. Do we care?

It looked OK to me in Firefox, is there a bit that looks wrong/bad to you?

Dave

Quoted 47 lines
docs/manual/system/monitor.html renamed from docs.old/manual/system/monitor.html +7 -7
@@ -601,10 +601,11 @@ command.</p>
 </dd>
 <dt><code class="docutils literal notranslate"><span class="pre">xen-event-list</span></code></dt><dd><p>List event channels in the guest</p>
 </dd>
-</dl>
-<dl>
 <dt><code class="docutils literal notranslate"><span class="pre">info</span></code> <em>subcommand</em></dt><dd><p>Show various information about the system state.</p>
-<dl>
+</dd>
+</dl>
+<blockquote>
+<div><dl>
 <dt><code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">version</span></code></dt><dd><p>Show the version of QEMU.</p>
 </dd>
 <dt><code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">network</span></code></dt><dd><p>Show the network state.</p>
@@ -639,8 +640,6 @@ command.</p>
 </dd>
 <dt><code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">jit</span></code></dt><dd><p>Show dynamic compiler info.</p>
 </dd>
-<dt><code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">accel</span></code></dt><dd><p>Show accelerator statistics.</p>
-</dd>
 <dt><code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">sync-profile</span> <span class="pre">[-m|-n]</span></code> [<em>max</em>]</dt><dd><p>Show synchronization profiling info, up to <em>max</em> entries (default: 10),
 sorted by total wait time.</p>
 <dl class="simple">
@@ -653,6 +652,8 @@ sorted by total wait time.</p>
 the “Object” field shows—enclosed in brackets—the number of objects
 being coalesced.</p>
 </dd>
+<dt><code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">accel</span></code></dt><dd><p>Show accelerator statistics.</p>
+</dd>
 <dt><code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">kvm</span></code></dt><dd><p>Show KVM information.</p>
 </dd>
 <dt><code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">accelerators</span></code></dt><dd><p>Show which accelerators are compiled into a QEMU binary, and what accelerator
@@ -765,8 +766,7 @@ enabled) memory in bytes.</p>
 <dt><code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">firmware-log</span></code></dt><dd><p>Show the firmware (ovmf) debug log.</p>
 </dd>
 </dl>
-</dd>
-</dl>
+</div></blockquote>
 </section>
 <section id="integer-expressions">
 <h2>Integer expressions<a class="headerlink" href="#integer-expressions" title="Link to this heading"></a></h2>
Signature · 4 lines
 -----Open up your eyes, open up your mind, open up your code -------   
/ Dr. David Alan Gilbert    |       Running GNU/Linux       | Happy  \ 
\        dave @ treblig.org |                               | In Hex /
 \ _________________________|_____ http://www.treblig.org   |_______/
#5 lore raw

Re: [PATCH 2/4] hmp*hx: Move info docs

Quoted 9 lines · Dr. David Alan Gilbert
Quoted 8 lines · * Markus Armbruster ([email protected]) wrote:
Quoted 6 lines · [email protected] writes:

From: "Dr. David Alan Gilbert" <[email protected]>

Move the docs for the info subcommand from the separate hx into the top level file next to the 'info' command itself. That makes every command in the top level file have a RST section.

Quoted 6 lines
Quoted 4 lines
Quoted 1 line

Generated HTML changes slightly, diff appended. Shows as vertical space differences in Firefox. Do we care?

It looked OK to me in Firefox, is there a bit that looks wrong/bad to you?

The vertical spacing around "info subcommand" changes.

Old: extra space between "xen-event-list" and "info subcommand" compared to between other commands.

New: extra space between "info subcommand"'s doc text and "info version".

Hypothesis: the extra space is at the boundary between hmp-commands.hx and hmp-commands-info.hx.

I dislike the old extra space a bit less, but no big deal either way.

[...]

#6 lore raw

PATCH 3/4 hxtool: Split srst/erst add checks

In reply to [email protected]

From: "Dr. David Alan Gilbert" <[email protected]>

Split the SRST/ERST case and add some checks.
This is mainly to make it easier to add some checks in following patches.

---
 scripts/hxtool | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)
scripts/hxtool +17 -3
index 80516b9437..ea2accef98 100755
@@ -2,15 +2,29 @@
 
 hxtoh()
 {
-    flag=1
+    outsiderst=1
     while read -r str; do
         case $str in
             HXCOMM*)
             ;;
-            SRST*|ERST*) flag=$(($flag^1))
+            SRST*)
+              if [ $outsiderst -eq 0 ]
+              then
+                echo "Error: SRST inside another RST" >&2
+                exit 1
+              fi
+              outsiderst=0
+            ;;
+            ERST*)
+              if [ $outsiderst -eq 1 ]
+              then
+                echo "Error: ERST already outside RST" >&2
+                exit 1
+              fi
+              outsiderst=1
             ;;
             *)
-            test $flag -eq 1 && printf "%s\n" "$str"
+            test $outsiderst -eq 1 && printf "%s\n" "$str"
             ;;
         esac
     done
Signature · 1 line
2.52.0
#7 lore raw

Re: [PATCH 3/4] hxtool: Split srst/erst add checks

Quoted 16 lines · [email protected] writes:

From: "Dr. David Alan Gilbert" <[email protected]>

Split the SRST/ERST case and add some checks.
This is mainly to make it easier to add some checks in following patches.

---
 scripts/hxtool | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)
scripts/hxtool +0 -0
index 80516b9437..ea2accef98 100755

scripts/hxtool line 5

Quoted 5 lines
scripts/hxtool +1 -1
@@ -2,15 +2,29 @@
 
 hxtoh()
 {
-    flag=1
+    outsiderst=1

I parsed this "outsider st" and went "WAT? Backtrack... aha". Name it outside_rst? in_h? Or revert sense and call it in_rst?

Quoted 27 lines
scripts/hxtool +16 -2
     while read -r str; do
         case $str in
             HXCOMM*)
             ;;
-            SRST*|ERST*) flag=$(($flag^1))
+            SRST*)
+              if [ $outsiderst -eq 0 ]
+              then
+                echo "Error: SRST inside another RST" >&2
+                exit 1
+              fi
+              outsiderst=0
+            ;;
+            ERST*)
+              if [ $outsiderst -eq 1 ]
+              then
+                echo "Error: ERST already outside RST" >&2
+                exit 1
+              fi
+              outsiderst=1
             ;;
             *)
-            test $flag -eq 1 && printf "%s\n" "$str"
+            test $outsiderst -eq 1 && printf "%s\n" "$str"
             ;;
         esac
     done
#8 lore raw

PATCH 4/4 hxtool: Error on missing docs

In reply to [email protected]

From: "Dr. David Alan Gilbert" <[email protected]>

Error if a '.name' is seen after another '.name' without an intervening SRST, this normally indicates missing or misplaced docs.

We can't check DEF (as used in command line options) because those often have multiple DEF per doc.

---
 scripts/hxtool | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)
scripts/hxtool +19 -1
index ea2accef98..f310071daa 100755
@@ -1,8 +1,14 @@
 #!/bin/sh
 
+printifnotrst()
+{
+    test $outsiderst -eq 1 && printf "%s\n" "$str"
+}
 hxtoh()
 {
     outsiderst=1
+    # .name for HMP
+    seenname=0
     while read -r str; do
         case $str in
             HXCOMM*)
@@ -13,6 +19,8 @@ hxtoh()
                 echo "Error: SRST inside another RST" >&2
                 exit 1
               fi
+              # consume the name
+              seenname=0
               outsiderst=0
             ;;
             ERST*)
@@ -23,8 +31,18 @@ hxtoh()
               fi
               outsiderst=1
             ;;
+            # Note the space at the start - we need to exclude something.name
+             .name*)
+              if [ $seenname -eq 1 ]
+              then
+                echo "Error: Seen another .name, maybe missing docs?" >&2
+                exit 1
+              fi
+              seenname=1
+              printifnotrst
+            ;;
             *)
-            test $outsiderst -eq 1 && printf "%s\n" "$str"
+            printifnotrst
             ;;
         esac
     done
Signature · 1 line
2.52.0
#9 lore raw

Re: [PATCH 4/4] hxtool: Error on missing docs

Quoted 7 lines · [email protected] writes:

From: "Dr. David Alan Gilbert" <[email protected]>

Error if a '.name' is seen after another '.name' without an intervening SRST, this normally indicates missing or misplaced docs.

We can't check DEF (as used in command line options) because those often have multiple DEF per doc.

Pity.

scripts/hxtool line 3

Quoted 13 lines
---
 scripts/hxtool | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)
scripts/hxtool +1 -0
index ea2accef98..f310071daa 100755
@@ -1,8 +1,14 @@
 #!/bin/sh
 
+printifnotrst()

print_if_not_rst()? print_h()?

scripts/hxtool line 11

Quoted 8 lines
scripts/hxtool +5 -0
+{
+    test $outsiderst -eq 1 && printf "%s\n" "$str"
+}
 hxtoh()
 {
     outsiderst=1
+    # .name for HMP
+    seenname=0

I'd prefer seen_name.

Quoted 13 lines
scripts/hxtool +2 -0
     while read -r str; do
         case $str in
             HXCOMM*)
@@ -13,6 +19,8 @@ hxtoh()
                 echo "Error: SRST inside another RST" >&2
                 exit 1
               fi
+              # consume the name
+              seenname=0
               outsiderst=0
             ;;
             ERST*)

scripts/hxtool hxtoh() · line 35

Quoted 5 lines
scripts/hxtool +2 -0
@@ -23,8 +31,18 @@ hxtoh()
               fi
               outsiderst=1
             ;;
+            # Note the space at the start - we need to exclude something.name
+             .name*)

This works?!? It does in my testing. I'm amazed.

Quoted 4 lines
scripts/hxtool +4 -0
+              if [ $seenname -eq 1 ]
+              then
+                echo "Error: Seen another .name, maybe missing docs?" >&2
+                exit 1

scripts/hxtool hxtoh() · line 48

Quoted 10 lines
scripts/hxtool +5 -1
+              fi
+              seenname=1
+              printifnotrst
+            ;;
             *)
-            test $outsiderst -eq 1 && printf "%s\n" "$str"
+            printifnotrst
             ;;
         esac
     done

Could move the printing behind the case, and continue the loop in the case SRST* and ERST*. No need for the function then. Matter of taste, up to you.

#10 lore raw

Re: [PATCH 4/4] hxtool: Error on missing docs

Quoted 11 lines · * Markus Armbruster ([email protected]) wrote:
Quoted 7 lines · [email protected] writes:

From: "Dr. David Alan Gilbert" <[email protected]>

Error if a '.name' is seen after another '.name' without an intervening SRST, this normally indicates missing or misplaced docs.

We can't check DEF (as used in command line options) because those often have multiple DEF per doc.

Pity.

Yeh, I added the code to do it and then realised it was broken in too many places.

Quoted 12 lines
Quoted 12 lines
---
 scripts/hxtool | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)
scripts/hxtool +0 -0
index ea2accef98..f310071daa 100755
@@ -1,8 +1,14 @@
 #!/bin/sh
 
Quoted 3 lines

scripts/hxtool line 3

Quoted 1 line
scripts/hxtool +1 -0
+printifnotrst()

print_if_not_rst()? print_h()?

OK, I'll add the _'s and renames as suggested in the others as well

Quoted 23 lines

scripts/hxtool line 11

Quoted 8 lines
scripts/hxtool +5 -0
+{
+    test $outsiderst -eq 1 && printf "%s\n" "$str"
+}
 hxtoh()
 {
     outsiderst=1
+    # .name for HMP
+    seenname=0

I'd prefer seen_name.

Quoted 12 lines
scripts/hxtool +2 -0
     while read -r str; do
         case $str in
             HXCOMM*)
@@ -13,6 +19,8 @@ hxtoh()
                 echo "Error: SRST inside another RST" >&2
                 exit 1
               fi
+              # consume the name
+              seenname=0
               outsiderst=0
             ;;
             ERST*)
Quoted 8 lines

scripts/hxtool hxtoh() · line 35

Quoted 6 lines
scripts/hxtool +2 -0
@@ -23,8 +31,18 @@ hxtoh()
               fi
               outsiderst=1
             ;;
+            # Note the space at the start - we need to exclude something.name
+             .name*)

This works?!? It does in my testing. I'm amazed.

To my amazement as well, but I couldn't find a clearer way of writing that also worked.

Quoted 15 lines
Quoted 4 lines
scripts/hxtool +4 -0
+              if [ $seenname -eq 1 ]
+              then
+                echo "Error: Seen another .name, maybe missing docs?" >&2
+                exit 1

scripts/hxtool hxtoh() · line 48

Quoted 10 lines
scripts/hxtool +5 -1
+              fi
+              seenname=1
+              printifnotrst
+            ;;
             *)
-            test $outsiderst -eq 1 && printf "%s\n" "$str"
+            printifnotrst
             ;;
         esac
     done
Quoted 3 lines

Could move the printing behind the case, and continue the loop in the case SRST* and ERST*. No need for the function then. Matter of taste, up to you.

Yeh I prefer the function than clever continues and stuff.

Dave

Signature · 4 lines
 -----Open up your eyes, open up your mind, open up your code -------   
/ Dr. David Alan Gilbert    |       Running GNU/Linux       | Happy  \ 
\        dave @ treblig.org |                               | In Hex /
 \ _________________________|_____ http://www.treblig.org   |_______/
Reviewed-by on the v1 series
#11 lore raw
In reply to [email protected]

Hi

Quoted 18 lines · On Thu, Jan 15, 2026 at 6:05 AM <[email protected]> wrote:

From: "Dr. David Alan Gilbert" <[email protected]>

Hi,
This adds a couple of sanity checks to hxtool to try and catch the type of mistake that Markus' patch fixes.
(Included Markus' patch since otherwise the script correctly fails)

Dave

Dr. David Alan Gilbert (3):
hmp*hx: Move info docs
hxtool: Split srst/erst add checks
hxtool: Error on missing docs

Markus Armbruster (1):
hmp-commands-info.hx: Move definition of "info accel"

Quoted 9 lines
 hmp-commands-info.hx | 33 +++++++++++++--------------------
 hmp-commands.hx      | 27 +++++++++++++++++----------
 scripts/hxtool       | 38 +++++++++++++++++++++++++++++++++++---
 3 files changed, 65 insertions(+), 33 deletions(-)

--
2.52.0

Signature · 1 line
Marc-André Lureau