QMP: Introduce commands documentation

One of the most important missing feature in QMP today is its
supported commands documentation.

The plan is to make it part of self-description support, however
self-description is a big task we have been postponing for a
long time now and still don't know when it's going to be done.

In order not to compromise QMP adoption and make users' life easier,
this commit adds a simple text documentation which fully describes
all QMP supported commands.

This is not ideal for a number of reasons (harder to maintain,
text-only, etc) but does improve the current situation. To avoid at
least divering from the user monitor help and texi snippets, QMP bits
are also maintained inside qemu-monitor.hx, and hxtool is extended to
generate a single text file from them.

Signed-off-by: Jan Kiszka <jan.kiszka@siemens.com>
Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>

Makefile

@@ -29,7 +29,7 @@ $(call set-vpath, $(SRC_PATH):$(SRC_PATH)/hw)
 LIBS+=-lz $(LIBS_TOOLS)
 
 ifdef BUILD_DOCS
-DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8
+DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 QMP/qmp-commands.txt
 else
 DOCS=
 endif
@@ -263,6 +263,9 @@ qemu-options.texi: $(SRC_PATH)/qemu-options.hx
 qemu-monitor.texi: $(SRC_PATH)/qemu-monitor.hx
 	$(call quiet-command,sh $(SRC_PATH)/hxtool -t < $< > $@,"  GEN   $@")
 
+QMP/qmp-commands.txt: $(SRC_PATH)/qemu-monitor.hx
+	$(call quiet-command,sh $(SRC_PATH)/hxtool -q < $< > $@,"  GEN   $@")
+
 qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx
 	$(call quiet-command,sh $(SRC_PATH)/hxtool -t < $< > $@,"  GEN   $@")
 

QMP/README

@@ -15,8 +15,9 @@ QMP is JSON[1] based and has the following features:
 
 For more information, please, refer to the following files:
 
-o qmp-spec.txt    QEMU Monitor Protocol current specification
+o qmp-spec.txt      QEMU Monitor Protocol current specification
-o qmp-events.txt  List of available asynchronous events
+o qmp-commands.txt  QMP supported commands
+o qmp-events.txt    List of available asynchronous events
 
 There are also two simple Python scripts available:
 

configure

@@ -2817,3 +2817,7 @@ ln -s $source_path/Makefile.user $d/Makefile
 if test "$static" = "no" -a "$user_pie" = "yes" ; then
   echo "QEMU_CFLAGS+=-fpie" > $d/config.mak
 fi
+
+if test "$docs" = "yes" ; then
+  mkdir -p QMP
+fi

hxtool

@@ -7,7 +7,7 @@ hxtoh()
         case $str in
             HXCOMM*)
             ;;
-            STEXI*|ETEXI*) flag=$(($flag^1))
+            STEXI*|ETEXI*|SQMP*|EQMP*) flag=$(($flag^1))
             ;;
             *)
             test $flag -eq 1 && printf "%s\n" "$str"
@@ -38,6 +38,12 @@ hxtotexi()
             fi
             flag=0
             ;;
+            SQMP*|EQMP*)
+            if test $flag -eq 1 ; then
+                echo "line $line: syntax error: expected ETEXI, found $str" >&2
+                exit 1
+            fi
+            ;;
             DEFHEADING*)
             echo "$(expr "$str" : "DEFHEADING(\(.*\))")"
             ;;
@@ -49,9 +55,45 @@ hxtotexi()
     done
 }
 
+hxtoqmp()
+{
+    IFS=
+    flag=0
+    while read -r str; do
+        case "$str" in
+            HXCOMM*)
+            ;;
+            SQMP*)
+            if test $flag -eq 1 ; then
+                echo "line $line: syntax error: expected EQMP, found $str" >&2
+                exit 1
+            fi
+            flag=1
+            ;;
+            EQMP*)
+            if test $flag -ne 1 ; then
+                echo "line $line: syntax error: expected SQMP, found $str" >&2
+                exit 1
+            fi
+            flag=0
+            ;;
+            STEXI*|ETEXI*)
+            if test $flag -eq 1 ; then
+                echo "line $line: syntax error: expected EQMP, found $str" >&2
+                exit 1
+            fi
+            ;;
+            *)
+            test $flag -eq 1 && echo "$str"
+            ;;
+        esac
+    done
+}
+
 case "$1" in
 "-h") hxtoh ;;
 "-t") hxtotexi ;;
+"-q") hxtoqmp ;;
 *) exit 1 ;;
 esac