Peter Maydell <peter.maydell@linaro.org> writes:
> 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.
The feature is kind of esoteric. Rather weak excuse for not fixing bad
UI, in my opinion. Weaker still since you already did a good part of
the actual work.
> (2) if we do do it, do we retain the old name indefinitely,
> or actively put it on the deprecate-and-drop list?
By "the old name", you mean the CLI option name, right?
I'd prefer deprecate and drop.
> (3) what should we do about the HMP StatusInfo object?
> I'm not sure how we handle compatibility for HMP.
Uh, you mean *QMP*, don't you?
As you wrote above, StatusInfo is returned by query-status, which is a
stable interface. Changes to members therefore require the usual
deprecation grace period. We'd add a new member with a sane name, and
deprecate the old one.
The matching HMP command is "info status". It shows member @singlestep
as " (single step mode)". Changing that is fine; HMP is not a stable
interface.
We don't use this feature on bsd-user, so I'm happy to follow whatever is decided
here. I can test things once the suggestion in this and other threads have played out
and there's another RFC set of patches.
Warner