Re: Better MI memory commands

[Vladimir Prus <vladimir at codesourcery dot 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"

> > > > +@item contents
> > > > +The contents of the memory block, as hex-encoded string of bytes.
> > > 
> > > But your example shows this:
> > > 
> > > > +              contents="01000000020000000300"@}]
> > > 
> > > This doesn't look like a ``string of bytes'' to me.  Or maybe I don't
> > > understand what you meant by that?
> > 
> > It seems very much like a hex-encoded string of bytes. Maybe, "hex-encoded
> > sequence of bytes" will work better?
> I suggest just
> 
>    The contents of the memory block, in hex.

OK.

> > > > +@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.

> 
> > What about the attached revision?
> 
> Okay, with the above changes and two more comments:
> 
> > +This command attempts to read all accessible memory regions in the
> > +specified range.  First, all regions marked as unreadable in the memory
> > +map (if one is defined) will be skipped.
>    ^^^^^^^^^^^^^^^^^^^^^^^
> I asked for a cross-reference here to where memory maps are
> described.

Added. (I did not find a relevant section on the first try, and then
forgot)

> 
> > +At present, if multiple
> 
> What happened here?
> 

I meant to clarify that more than one memory block can be returned,
as requested by Dan, but then realize the previous sequence actually
say that already. I've removed this bit now.



Thanks,

-- 
Vladimir Prus
CodeSourcery
vladimir@codesourcery.com
(650) 331-3385 x722