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@xxxxxxxxxx>
Reviewed-by: Dr. David Alan Gilbert <dgilbert@xxxxxxxxxx>
Reviewed-by: Richard Henderson <richard.henderson@xxxxxxxxxx>
---
docs/about/deprecated.rst | 9 +++++++++
include/monitor/hmp.h | 2 +-
softmmu/runstate-hmp-cmds.c | 2 +-
tests/qtest/test-hmp.c | 1 +
hmp-commands.hx | 25 +++++++++++++++++++++----
5 files changed, 33 insertions(+), 6 deletions(-)
diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst
index 3c62671dac1..6f5e689aa45 100644
--- a/docs/about/deprecated.rst
+++ b/docs/about/deprecated.rst
@@ -199,6 +199,15 @@ 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.
+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/include/monitor/hmp.h b/include/monitor/hmp.h
index fdb69b7f9ca..13f9a2dedb8 100644
--- a/include/monitor/hmp.h
+++ b/include/monitor/hmp.h
@@ -158,7 +158,7 @@ void hmp_info_vcpu_dirty_limit(Monitor *mon, const QDict *qdict);
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 a477838dc5a..2df670f0c06 100644
--- a/softmmu/runstate-hmp-cmds.c
+++ b/softmmu/runstate-hmp-cmds.c
@@ -40,7 +40,7 @@ void hmp_info_status(Monitor *mon, const QDict *qdict)
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 b4a920df898..6704be239be 100644
--- a/tests/qtest/test-hmp.c
+++ b/tests/qtest/test-hmp.c
@@ -56,6 +56,7 @@ static const char *hmp_cmds[] = {
"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 /",
diff --git a/hmp-commands.hx b/hmp-commands.hx
index bb85ee1d267..9afbb54a515 100644
--- a/hmp-commands.hx
+++ b/hmp-commands.hx
@@ -378,18 +378,35 @@ SRST
only *tag* as parameter.
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
{
--
2.34.1
