[RFC PATCH 0/5] Deprecate/rename singlestep command line option

[Peter Maydell]

The command line option '-singlestep' and its HMP equivalent
the 'singlestep' command are very confusingly named, because
they have nothing to do with single-stepping the guest (either
via the gdb stub or by emulation of guest CPU architectural
debug facilities). What they actually do is put TCG into a
mode where it puts only one guest instruction into each
translation block. This is useful for some circumstances
such as when you want the -d debug logging to be easier to
interpret, or if you have a finicky guest binary that wants
to see interrupts delivered at something other than the end
of a basic block.

The confusing name is made worse by the fact that our
documentation for these is so minimal as to be useless
for telling users what they really do.

This series:
 * renames the 'singlestep' global variable to 'one_insn_per_tb'
 * Adds new '-one-insn-per-tb' command line options and a
   HMP 'one-insn-per-tb' command
 * Documents the '-singlestep' options and 'singlestep'
   HMP command as deprecated synonyms for the new ones

It does not do anything about the other place where we surface
'singlestep', which is in the QMP StatusInfo object returned by the
'query-status' command.  This is incorrectly documented as "true if
VCPUs are in single-step mode" and "singlestep is enabled through
the GDB stub", because what it's actually returning is the
one-insn-per-tb state.

Things I didn't bother with because this is only an RFC but
will do if it turns into a non-RFC patchset:
 * test the bsd-user changes :-)
 * add text to deprecated.rst

So, questions:

(1) is this worth bothering with at all? We could just
    name our global variable etc better, and document what
    -singlestep actually does, and not bother with the new
    names for the options/commands.
(2) if we do do it, do we retain the old name indefinitely,
    or actively put it on the deprecate-and-drop list?
(3) what should we do about the HMP StatusInfo object?
    I'm not sure how we handle compatibility for HMP.

thanks
-- PMM


Peter Maydell (5):
  Rename the singlestep global variable to one_insn_per_tb
  linux-user: Add '-one-insn-per-tb' option equivalent to '-singlestep'
  bsd-user: Add '-one-insn-per-tb' option equivalent to '-singlestep'
  softmmu: Add '-one-insn-per-tb' option equivalent to '-singlestep'
  hmp: Add 'one-insn-per-tb' command equivalent to 'singlestep'

 docs/user/main.rst          | 14 ++++++++++++--
 include/exec/cpu-common.h   |  2 +-
 include/monitor/hmp.h       |  2 +-
 accel/tcg/cpu-exec.c        |  4 ++--
 bsd-user/main.c             |  9 +++++----
 linux-user/main.c           | 13 ++++++++-----
 softmmu/globals.c           |  2 +-
 softmmu/runstate-hmp-cmds.c |  6 +++---
 softmmu/runstate.c          |  2 +-
 softmmu/vl.c                |  3 ++-
 tests/qtest/test-hmp.c      |  1 +
 hmp-commands.hx             | 25 +++++++++++++++++++++----
 qemu-options.hx             | 14 ++++++++++++--
 tcg/tci/README              |  2 +-
 14 files changed, 71 insertions(+), 28 deletions(-)

-- 
2.34.1