Skip to contentSkip to conversation

HMP: hxtool sanity checks

PATCH In review [email protected] 4 participants 11 messages Jan 16

lore
Share & tools
lore
#0 lore raw

v2 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

v2:
Add brackets on the .name regexp
Use snake_case for names.

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 v2 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
Reviewed-by on v2 1/4
#2 lore raw

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

Quoted 5 lines · On 16/1/26 01:50, [email protected] wrote:

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".

Oops...

Quoted 6 lines
---
  hmp-commands-info.hx | 24 ++++++++++++------------
  1 file changed, 12 insertions(+), 12 deletions(-)
#3 lore raw

PATCH v2 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
Reviewed-by on v2 2/4
#4 lore raw

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

Quoted 5 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.

Could mention:

Generated HTML changes slightly. The difference is basically invisible.

Quoted 2 lines
#5 lore raw

PATCH v2 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..51dc841479 100755
@@ -2,15 +2,29 @@
 
 hxtoh()
 {
-    flag=1
+    in_rst=0
     while read -r str; do
         case $str in
             HXCOMM*)
             ;;
-            SRST*|ERST*) flag=$(($flag^1))
+            SRST*)
+              if [ $in_rst -eq 1 ]
+              then
+                echo "Error: SRST inside another RST" >&2
+                exit 1
+              fi
+              in_rst=1
+            ;;
+            ERST*)
+              if [ $in_rst -eq 0 ]
+              then
+                echo "Error: ERST already outside RST" >&2
+                exit 1
+              fi
+              in_rst=0
             ;;
             *)
-            test $flag -eq 1 && printf "%s\n" "$str"
+            test $in_rst -eq 0 && printf "%s\n" "$str"
             ;;
         esac
     done
Signature · 1 line
2.52.0
Reviewed-by on v2 3/4
#6 lore raw

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

Quoted 38 lines · On 16/01/2026 01.50, [email protected] wrote:

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 +13 -2
index 80516b9437..51dc841479 100755
@@ -2,15 +2,29 @@
 
  hxtoh()
  {
-    flag=1
+    in_rst=0
      while read -r str; do
          case $str in
              HXCOMM*)
              ;;
-            SRST*|ERST*) flag=$(($flag^1))
+            SRST*)
+              if [ $in_rst -eq 1 ]
+              then
+                echo "Error: SRST inside another RST" >&2
+                exit 1
+              fi
+              in_rst=1
+            ;;
+            ERST*)
+              if [ $in_rst -eq 0 ]
+              then
+                echo "Error: ERST already outside RST" >&2

scripts/hxtool line 30

Quoted 10 lines
scripts/hxtool +4 -1
+                exit 1
+              fi
+              in_rst=0
              ;;
              *)
-            test $flag -eq 1 && printf "%s\n" "$str"
+            test $in_rst -eq 0 && printf "%s\n" "$str"
              ;;
          esac
      done
#8 lore raw

PATCH v2 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 | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
scripts/hxtool +18 -0
index 51dc841479..ee98fb9c09 100755
@@ -1,8 +1,14 @@
 #!/bin/sh
 
+print_if_not_rst()
+{
+    test $in_rst -eq 0 && printf "%s\n" "$str"
+}
 hxtoh()
 {
     in_rst=0
+    # .name for HMP
+    seen_name=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
+              seen_name=0
               in_rst=1
             ;;
             ERST*)
@@ -23,6 +31,16 @@ hxtoh()
               fi
               in_rst=0
             ;;
+            # Note the space at the start - we need to exclude something.name
+            ( .name*)
+              if [ $seen_name -eq 1 ]
+              then
+                echo "Error: Seen another .name, maybe missing docs?" >&2
+                exit 1
+              fi
+              seen_name=1
+              print_if_not_rst
+            ;;
             *)
             test $in_rst -eq 0 && printf "%s\n" "$str"
             ;;
Signature · 1 line
2.52.0
#9 lore raw

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

Quoted 18 lines · On 16/01/2026 01.50, [email protected] wrote:

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 | 18 ++++++++++++++++++
  1 file changed, 18 insertions(+)
scripts/hxtool +0 -0
index 51dc841479..ee98fb9c09 100755

scripts/hxtool line 6

Quoted 6 lines
scripts/hxtool +4 -0
@@ -1,8 +1,14 @@
  #!/bin/sh
 
+print_if_not_rst()
+{
+    test $in_rst -eq 0 && printf "%s\n" "$str"
+}

Add an empty line after this function?

Quoted 23 lines
scripts/hxtool +6 -0
  hxtoh()
  {
      in_rst=0
+    # .name for HMP
+    seen_name=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
+              seen_name=0
                in_rst=1
              ;;
              ERST*)
@@ -23,6 +31,16 @@ hxtoh()
                fi
                in_rst=0
              ;;
+            # Note the space at the start - we need to exclude something.name
+            ( .name*)

scripts/hxtool hxtoh() · line 45

Quoted 10 lines
scripts/hxtool +8 -0
+              if [ $seen_name -eq 1 ]
+              then
+                echo "Error: Seen another .name, maybe missing docs?" >&2
+                exit 1
+              fi
+              seen_name=1
+              print_if_not_rst
+            ;;
              *)
              test $in_rst -eq 0 && printf "%s\n" "$str"

I think this line could be replaced with print_if_not_rst now?

Thomas

Reviewed-by on v2 4/4
#10 lore raw

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

In reply to [email protected]
Quoted 42 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.

---
 scripts/hxtool | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
scripts/hxtool +8 -0
index 51dc841479..ee98fb9c09 100755
@@ -1,8 +1,14 @@
 #!/bin/sh
 
+print_if_not_rst()
+{
+    test $in_rst -eq 0 && printf "%s\n" "$str"
+}
 hxtoh()
 {
     in_rst=0
+    # .name for HMP
+    seen_name=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
+              seen_name=0
               in_rst=1
             ;;
             ERST*)

scripts/hxtool hxtoh() · line 35

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

TIL about the optional left parenthesis here.

scripts/hxtool hxtoh() · line 46

Quoted 11 lines
scripts/hxtool +8 -0
+              if [ $seen_name -eq 1 ]
+              then
+                echo "Error: Seen another .name, maybe missing docs?" >&2
+                exit 1
+              fi
+              seen_name=1
+              print_if_not_rst
+            ;;
             *)
             test $in_rst -eq 0 && printf "%s\n" "$str"
             ;;