hmp: Add 'one-insn-per-tb' command equivalent to 'singlestep'
The 'singlestep' HMP command is confusing, because it doesn't
actually have anything to do with single-stepping the CPU. What it
does do is force TCG emulation to put one guest instruction in each
TB, which can be useful in some situations.
Create a new HMP command 'one-insn-per-tb', so we can document that
'singlestep' is just a deprecated synonym for it, and eventually
perhaps drop it.
We aren't obliged to do deprecate-and-drop for HMP commands,
but it's easy enough to do so, so we do.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Message-id: 20230417164041.684562-9-peter.maydell@linaro.org
diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst
index 3c62671..6f5e689 100644
--- a/docs/about/deprecated.rst
+++ b/docs/about/deprecated.rst
@@ -199,6 +199,15 @@
all arguments passed to ``device_add`` are consistent with the documented
property types.
+Human Monitor Protocol (HMP) commands
+-------------------------------------
+
+``singlestep`` (since 8.1)
+''''''''''''''''''''''''''
+
+The ``singlestep`` command has been replaced by the ``one-insn-per-tb``
+command, which has the same behaviour but a less misleading name.
+
Host Architectures
------------------
diff --git a/hmp-commands.hx b/hmp-commands.hx
index bb85ee1..9afbb54 100644
--- a/hmp-commands.hx
+++ b/hmp-commands.hx
@@ -379,17 +379,34 @@
ERST
{
+ .name = "one-insn-per-tb",
+ .args_type = "option:s?",
+ .params = "[on|off]",
+ .help = "run emulation with one guest instruction per translation block",
+ .cmd = hmp_one_insn_per_tb,
+ },
+
+SRST
+``one-insn-per-tb [off]``
+ Run the emulation with one guest instruction per translation block.
+ This slows down emulation a lot, but can be useful in some situations,
+ such as when trying to analyse the logs produced by the ``-d`` option.
+ This only has an effect when using TCG, not with KVM or other accelerators.
+
+ If called with option off, the emulation returns to normal mode.
+ERST
+
+ {
.name = "singlestep",
.args_type = "option:s?",
.params = "[on|off]",
- .help = "run emulation in singlestep mode or switch to normal mode",
- .cmd = hmp_singlestep,
+ .help = "deprecated synonym for one-insn-per-tb",
+ .cmd = hmp_one_insn_per_tb,
},
SRST
``singlestep [off]``
- Run the emulation in single step mode.
- If called with option off, the emulation returns to normal mode.
+ This is a deprecated synonym for the one-insn-per-tb command.
ERST
{
diff --git a/include/monitor/hmp.h b/include/monitor/hmp.h
index fdb69b7..13f9a2d 100644
--- a/include/monitor/hmp.h
+++ b/include/monitor/hmp.h
@@ -158,7 +158,7 @@
void hmp_human_readable_text_helper(Monitor *mon,
HumanReadableText *(*qmp_handler)(Error **));
void hmp_info_stats(Monitor *mon, const QDict *qdict);
-void hmp_singlestep(Monitor *mon, const QDict *qdict);
+void hmp_one_insn_per_tb(Monitor *mon, const QDict *qdict);
void hmp_watchdog_action(Monitor *mon, const QDict *qdict);
void hmp_pcie_aer_inject_error(Monitor *mon, const QDict *qdict);
void hmp_info_capture(Monitor *mon, const QDict *qdict);
diff --git a/softmmu/runstate-hmp-cmds.c b/softmmu/runstate-hmp-cmds.c
index a477838..2df670f 100644
--- a/softmmu/runstate-hmp-cmds.c
+++ b/softmmu/runstate-hmp-cmds.c
@@ -40,7 +40,7 @@
qapi_free_StatusInfo(info);
}
-void hmp_singlestep(Monitor *mon, const QDict *qdict)
+void hmp_one_insn_per_tb(Monitor *mon, const QDict *qdict)
{
const char *option = qdict_get_try_str(qdict, "option");
AccelState *accel = current_accel();
diff --git a/tests/qtest/test-hmp.c b/tests/qtest/test-hmp.c
index b4a920d..6704be2 100644
--- a/tests/qtest/test-hmp.c
+++ b/tests/qtest/test-hmp.c
@@ -56,6 +56,7 @@
"o /w 0 0x1234",
"object_add memory-backend-ram,id=mem1,size=256M",
"object_del mem1",
+ "one-insn-per-tb on",
"pmemsave 0 4096 \"/dev/null\"",
"p $pc + 8",
"qom-list /",
