[PATCH v2 10/10] hmp: Deprecate 'singlestep' member of StatusInfo

[Peter Maydell <peter.maydell@xxxxxxxxxx>]

The 'singlestep' member of StatusInfo has never done what
the QMP documentation claims it does. What it actually
reports is whether TCG is working in "one guest instruction
per translation block" mode.

Create a new 'one-insn-per-tb' member whose name matches
what the field actually does and the new command line
options. Deprecate the old 'singlestep' field.

Signed-off-by: Peter Maydell <peter.maydell@xxxxxxxxxx>
---
 docs/about/deprecated.rst   | 10 ++++++++++
 docs/interop/qmp-intro.txt  |  1 +
 qapi/run-state.json         | 17 ++++++++++++++---
 softmmu/runstate-hmp-cmds.c |  2 +-
 softmmu/runstate.c          |  6 ++++--
 5 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst
index 6f5e689aa45..dd36becdf3b 100644
--- a/docs/about/deprecated.rst
+++ b/docs/about/deprecated.rst
@@ -199,6 +199,16 @@ accepted incorrect commands will return an error. Users should make sure that
 all arguments passed to ``device_add`` are consistent with the documented
 property types.
 
+``StatusInfo`` member ``singlestep`` (since 8.1)
+''''''''''''''''''''''''''''''''''''''''''''''''
+
+The ``singlestep`` member of the ``StatusInfo`` returned from
+the ``query-status`` command is deprecated, because its name
+is confusing and it never did what the documentation claimed
+or what its name suggests. Use the ``one-insn-per-tb``
+member instead, which reports the same information the old
+``singlestep`` member did but under a clearer name.
+
 Human Monitor Protocol (HMP) commands
 -------------------------------------
 
diff --git a/docs/interop/qmp-intro.txt b/docs/interop/qmp-intro.txt
index 1c745a7af04..b22916b23df 100644
--- a/docs/interop/qmp-intro.txt
+++ b/docs/interop/qmp-intro.txt
@@ -73,6 +73,7 @@ Escape character is '^]'.
 { "execute": "query-status" }
 {
     "return": {
+        "one-insn-per-tb": false,
         "status": "prelaunch", 
         "singlestep": false, 
         "running": false
diff --git a/qapi/run-state.json b/qapi/run-state.json
index 9d34afa39e0..1de8c5c55d0 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -104,16 +104,27 @@
 #
 # @running: true if all VCPUs are runnable, false if not runnable
 #
-# @singlestep: true if VCPUs are in single-step mode
+# @one-insn-per-tb: true if using TCG with one guest instruction
+#                   per translation block
+#
+# @singlestep: deprecated synonym for @one-insn-per-tb
 #
 # @status: the virtual machine @RunState
 #
+# Features:
+# @deprecated: Member 'singlestep' is deprecated. Use @one-insn-per-tb instead.
+#
 # Since: 0.14
 #
-# Notes: @singlestep is enabled through the GDB stub
+# Notes: @one-insn-per-tb is enabled on the command line with
+#        '-accel tcg,one-insn-per-tb=on', or with the HMP
+#        'one-insn-per-tb' command.
 ##
 { 'struct': 'StatusInfo',
-  'data': {'running': 'bool', 'singlestep': 'bool', 'status': 'RunState'} }
+  'data': {'running': 'bool',
+           'singlestep': { 'type': 'bool', 'features': [ 'deprecated' ]},
+           'one-insn-per-tb': 'bool',
+           'status': 'RunState'} }
 
 ##
 # @query-status:
diff --git a/softmmu/runstate-hmp-cmds.c b/softmmu/runstate-hmp-cmds.c
index 20facb055f0..404d331b523 100644
--- a/softmmu/runstate-hmp-cmds.c
+++ b/softmmu/runstate-hmp-cmds.c
@@ -30,7 +30,7 @@ void hmp_info_status(Monitor *mon, const QDict *qdict)
 
     monitor_printf(mon, "VM status: %s%s",
                    info->running ? "running" : "paused",
-                   info->singlestep ? " (one insn per TB)" : "");
+                   info->one_insn_per_tb ? " (one insn per TB)" : "");
 
     if (!info->running && info->status != RUN_STATE_PAUSED) {
         monitor_printf(mon, " (%s)", RunState_str(info->status));
diff --git a/softmmu/runstate.c b/softmmu/runstate.c
index 2f2396c819e..a93e74c41ca 100644
--- a/softmmu/runstate.c
+++ b/softmmu/runstate.c
@@ -239,11 +239,13 @@ StatusInfo *qmp_query_status(Error **errp)
 
     /*
      * We ignore errors, which will happen if the accelerator
-     * is not TCG. "singlestep" is meaningless for other accelerators,
+     * is not TCG. "one-insn-per-tb" is meaningless for other accelerators,
      * so we will set the StatusInfo field to false for those.
      */
-    info->singlestep = object_property_get_bool(OBJECT(accel),
+    info->one_insn_per_tb = object_property_get_bool(OBJECT(accel),
                                                 "one-insn-per-tb", NULL);
+    /* Deprecated member with same meaning as one-insn-per-tb */
+    info->singlestep = info->one_insn_per_tb;
     info->running = runstate_is_running();
     info->status = current_run_state;
 
-- 
2.34.1