Merge tag 'pull-monitor-2026-05-05' of https://repo.or.cz/qemu/armbru into staging

Monitor patches for 2026-05-05

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCgAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmn52lkSHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZT+5sQALSTlDKF36ICt8g0EJUpi+c3/TyvrtOy
# VBycVtAfOo6p3i1oquSrMSwcsxvHr3oSpws4Ej6q2NGWLd07bz+oI2ryJz8z2iWV
# CFB9O8gyPrr7WesEfYKB63RfEroAk015JYPLJK0DrGo51A4o2z+cNLTGTQY6ZFBm
# ABmL6/umR6/suPlQiE6MSZcBBp3xy5CTSxeCdrEQNt+ITY6G6hGgGb+5NvoneRpn
# EWBmEN7czHDkZkySGj+Z21olUVVAhHGSo50G00vy8KlMmXhO5txUKV6gf9zHKPBw
# tUXPLwr81BJrsA8zorQb/GUkZ50Bf7GNFk6+aZmdiOUKcgIZQscIksyu6uP5GXEL
# V9b/b01F7Es6tEhbGVWo6zzMjg9lhFMxQ3zQ7DHjMf2fyKy2RUKSSqZ+9pjOuWrI
# BpD0YOabJ5yr18sKELdrPGgOgb6x+KgNaI+0b6zuOVK3bZ9zfOGt0AfNxLNkzSLT
# vH6Jhw8i4ntU25QNJRLuHt8xyAt1yZrrYvaAJHeUq2Xf0p8pHwJJ8rTzOrXpHzec
# si7tXkWrqgYjwjkOHqHZLloEJcD9CCBluVexpRRS3xqwfqDIlmtqCotBPfLMKvJQ
# mw/w4rtAvKnkZU7eMKNGiINKoao6LrzIymqCnPOI+Robo6iF3v9od6li8Nz3ZznN
# W7vYHQQ1HKHp
# =LaJY
# -----END PGP SIGNATURE-----
# gpg: Signature made Tue 05 May 2026 07:54:01 EDT
# gpg:                using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg:                issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [full]
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>" [full]
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* tag 'pull-monitor-2026-05-05' of https://repo.or.cz/qemu/armbru:
  monitor: Add `clear` command
  hxtool: Error on missing docs
  hxtool: Split srst/erst add checks
  hmp*hx: Move info docs

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>

hmp-commands-info.hx

@@ -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

@@ -20,6 +20,20 @@ SRST
   Show the help for all commands or just for command *cmd*.
 ERST
 
+    {
+        .name       = "clear",
+        .args_type  = "",
+        .params     = "",
+        .help       = "clear the monitor screen",
+        .cmd        = hmp_clear,
+        .flags      = "p",
+    },
+
+SRST
+``clear``
+  Clear the monitor screen.
+ERST
+
     {
         .name       = "commit",
         .args_type  = "device:B",
@@ -1814,16 +1828,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 +1871,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 **

include/monitor/hmp.h

@@ -165,6 +165,7 @@ void hmp_trace_event(Monitor *mon, const QDict *qdict);
 void hmp_trace_file(Monitor *mon, const QDict *qdict);
 void hmp_info_trace_events(Monitor *mon, const QDict *qdict);
 void hmp_help(Monitor *mon, const QDict *qdict);
+void hmp_clear(Monitor *mon, const QDict *qdict);
 void hmp_info_help(Monitor *mon, const QDict *qdict);
 void hmp_info_sync_profile(Monitor *mon, const QDict *qdict);
 void hmp_info_history(Monitor *mon, const QDict *qdict);

monitor/hmp-cmds.c

@@ -219,6 +219,17 @@ void hmp_help(Monitor *mon, const QDict *qdict)
     hmp_help_cmd(mon, qdict_get_try_str(qdict, "name"));
 }
 
+void hmp_clear(Monitor *mon, const QDict *qdict)
+{
+    /*
+     * Send an ANSI escape sequence:
+     * "\x1b[H" - move cursor to top-left
+     * "\x1b[2J" - clear visible screen
+     * "\x1b[3J" - clear scrollback
+     */
+    monitor_printf(mon, "\x1b[H\x1b[2J\x1b[3J");
+}
+
 void hmp_info_help(Monitor *mon, const QDict *qdict)
 {
     hmp_help_cmd(mon, "info");

scripts/hxtool

@@ -1,16 +1,49 @@
 #!/bin/sh
 
+print_if_not_rst()
+{
+    test $in_rst -eq 0 && printf "%s\n" "$str"
+}
+
 hxtoh()
 {
-    flag=1
+    in_rst=0
+    # .name for HMP
+    seen_name=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
+              # consume the name
+              seen_name=0
+              in_rst=1
+            ;;
+            ERST*)
+              if [ $in_rst -eq 0 ]
+              then
+                echo "Error: ERST already outside RST" >&2
+                exit 1
+              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 $flag -eq 1 && printf "%s\n" "$str"
+            print_if_not_rst
             ;;
         esac
     done