Re: Better MI memory commands

Eli Zaretskii
2010-08-12T17:04:47Z

> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Thu, 12 Aug 2010 11:25:02 +0400
> Cc: gdb-patches@sources.redhat.com
>
> On Wednesday 11 August 2010 22:00:21 Eli Zaretskii wrote:
>
> > > From: Vladimir Prus <vladimir@codesourcery.com>
> > > Date: Wed, 11 Aug 2010 16:37:49 +0400
> > > Cc: gdb-patches@sources.redhat.com
> > >
> > > > > +The output of the command has a result record named @samp{memory},
> > > > ^^^^^^^^^^^^^^^^^^^
> > > > Perhaps "is a result record"?
> > >
> > > Nope. "result record" is actually a nonterminal in MI grammar, and output
> > > of a command may have result records but is never a result record itself.
> > >
> > > > And what is the importance of naming
> > > > this record `memory'? why is the name important here?
> > >
> > > Because for frontend to access a result record in a command output, it
> > > has to know its name.
> >
> > Then perhaps
> >
> > The result record (@pxref{GDB/MI Result Records}) that is output of
> > the command includes a field named @samp{memory} whose content is a
> > list of tuples ...
>
> This is still not accurate. The output of the command is:
>
> - the character sequence "^done"
> - zero, one, or more result results, separated with spaces.
>
> So, it's still an command output that "has" a result record named "memory"
> as opposed to "result record .. is .. output of the command"

This is a misunderstanding. In the text I suggested, "record that is
output", the "output" part is a verb, not a noun. (I should have said
"output by the command", though.) IOW, the text says that the command
outputs some stuff, and part of that stuff is the result vector with a
field named "memory".

Saying "output has the result record" is not good English, because the
result record is part of the output, not some attribute of it.

I could try to be more accurate, if "that is output by the command" is
not good enough, but please note that our current definition of what
exactly is a "result record" is quite vague. In fact, we don't say
what it is at all. For starters, it talks about "result indications":

In addition to a number of out-of-band notifications, the response to a
@sc{gdb/mi} command includes one of the following result indications:

@table @code
@findex ^done
@item "^done" [ "," @var{results} ]
The synchronous operation was successful, @code{@var{results}} are the return
values.

@item "^running"
@findex ^running
This result record is equivalent to @samp{^done}. Historically, it
was output instead of @samp{^done} if the command has resumed the
target. This behaviour is maintained for backward compatibility, but
all frontends should treat @samp{^done} and @samp{^running}
identically and rely on the @samp{*running} output record to determine
which threads are resumed.

My reading of this is that ^done, ^running, etc. _are_ examples of
result records. By contrast, you say above that a result record is
everything _after_ these indications. This inconsistency is the main
reason why I deliberately left the text I suggested slightly vague.

I'm open to other suggestions, but if we want to be rigorous, we
should be more consistent than we are now regarding what exactly is a
result record.

> > > > > +@item @var{contents}
> > > > > +The hex-encoded bytes to write. The size of this parameter determines
> > > > > +how many bytes should be written.^^^^^^^^
> > > >
> > > > You probably meant "the value", not "the size".
> > >
> > > Actually, "the size". A parameter is a string, a string has a size
> >
> > A string has a length, not size, so please use that. Actually,
> > perhaps this sentence should be simply removed, as it seems to say
> > something trivial, doesn't it?
>
> It's your call. It seemed to me that clarifying that there's no explicit option
> for size might help users, who otherwise might decide the docs are
> incompletely.

I don't mind leaving it, if you think it's important.