Re: [rfc/rfa] [3/4] SPU enhancements: gdbserver support

["Ulrich Weigand" <uweigand@de.ibm.com>]

Eli Zareteskii wrote:

> You already added a "@cindex SPU" entry in your previous patch.  This
> is the second index entry with exactly the same name, which is not a
> very good idea: a reader looking at the index will not know which one
> to choose.  It is better to use an entry qualified by its context, for
> example:
> 
>   @cindex SPU, read @code{spufs} files

Right.  Actually, I think we probably don't even need an index entry
for that at all ...   (The other qXfer packets don't have index entries
either.)

> > +Read contents of an @code{spufs} file on the target system.  The
> > +annex specifies which file to read; it must be of the form 
> > +@var{id}/@var{name}, where @var{id} specifies an SPU context ID
> 
> Since you are talking about a file, you should use the @file markup:
> 
>   +@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID

OK.

> > -@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{}
> > +@item qXfer:@var{object}:write:@var{annex}:@var{offset},@var{length}:@var{data}@dots{}
> 
> Won't this change break backward compatibility?

Not really, since there currently are no qXfer::write packets.  This was
simply a generic entry that described how potential such packets might 
look like; now that we've actually implemented the first real packet, it 
seemed better to add the LENGTH.

> > +Write @var{length} bytes of uninterpreted data into the target's
> > +special data area identified by the keyword @var{object}, starting
> 
> What do you mean by ``keyword''?  Isn't @var{object} a _name_ of an
> object or its symbol?

This is just copied from the pre-existing text (also present in the
qXfer::read section).  In any case, I think "keyword" is right here,
as you can only use one of the defined strings ("auxv", "memory-map",
"spu", ...) as "object".

> > +at @var{offset} bytes into the data.  @samp{@var{data}@dots{}} is
>                                          ^^^^^^^^^^^^^^^^^^^^^^
> Why use @samp here?  Does it do anything useful?

Not really, this again was copied from pre-existing text.  I've 
removed the @samp now.

> > +the binary-encoded data (@pxref{Binary Data}) to be written.  The
> > +content and encoding of @var{annex} is specific to the object; it can
>                                        ^^^^^^^^^^^^^^^^^^^^^^^^^
> Better say "... is specific to @var{object}".

OK.  I've made the same change at the corresponding line in the qXfer::read
description.


Is the following version OK?

Bye,
Ulrich

diff -urNp gdb-orig/gdb/doc/gdb.texinfo gdb-head/gdb/doc/gdb.texinfo
--- gdb-orig/gdb/doc/gdb.texinfo	2007-05-31 18:54:31.000000000 +0200
+++ gdb-head/gdb/doc/gdb.texinfo	2007-06-03 14:44:31.860732882 +0200
@@ -23590,6 +23590,16 @@ These are the currently defined stub fea
 @tab @samp{-}
 @tab Yes
 
+@item @samp{qXfer:spu:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
+@item @samp{qXfer:spu:write}
+@tab No
+@tab @samp{-}
+@tab Yes
+
 @item @samp{QPassSignals}
 @tab No
 @tab @samp{-}
@@ -23623,6 +23633,14 @@ The remote stub understands the @samp{qX
 The remote stub understands the @samp{qXfer:memory-map:read} packet
 (@pxref{qXfer memory map read}).
 
+@item qXfer:spu:read
+The remote stub understands the @samp{qXfer:spu:read} packet
+(@pxref{qXfer spu read}).
+
+@item qXfer:spu:write
+The remote stub understands the @samp{qXfer:spu:write} packet
+(@pxref{qXfer spu write}).
+
 @item QPassSignals
 The remote stub understands the @samp{QPassSignals} packet
 (@pxref{QPassSignals}).
@@ -23708,7 +23726,7 @@ packets.)
 Read uninterpreted bytes from the target's special data area
 identified by the keyword @var{object}.  Request @var{length} bytes
 starting at @var{offset} bytes into the data.  The content and
-encoding of @var{annex} is specific to the object; it can supply
+encoding of @var{annex} is specific to @var{object}; it can supply
 additional details about what data to access.
 
 Here are the specific requests of this form defined so far.  All
@@ -23741,6 +23759,17 @@ annex part of the generic @samp{qXfer} p
 
 This packet is not probed by default; the remote stub must request it,
 by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
+@item qXfer:spu:read:@var{annex}:@var{offset},@var{length}
+@anchor{qXfer spu read}
+Read contents of an @code{spufs} file on the target system.  The
+annex specifies which file to read; it must be of the form 
+@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID
+in the target process, and @var{name} identifes the @code{spufs} file
+in that context to be accessed.
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
 @end table
 
 Reply:
@@ -23774,18 +23803,31 @@ An empty reply indicates the @var{object
 the stub, or that the object does not support reading.
 @end table
 
-@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{}
+@item qXfer:@var{object}:write:@var{annex}:@var{offset},@var{length}:@var{data}@dots{}
 @cindex write data into object, remote request
-Write uninterpreted bytes into the target's special data area
-identified by the keyword @var{object}, starting at @var{offset} bytes
-into the data.  @samp{@var{data}@dots{}} is the binary-encoded data
-(@pxref{Binary Data}) to be written.  The content and encoding of @var{annex}
-is specific to the object; it can supply additional details about what data
-to access.
-
-No requests of this form are presently in use.  This specification
-serves as a placeholder to document the common format that new
-specific request specifications ought to use.
+Write @var{length} bytes of uninterpreted data into the target's
+special data area identified by the keyword @var{object}, starting
+at @var{offset} bytes into the data.  @var{data}@dots{} is
+the binary-encoded data (@pxref{Binary Data}) to be written.  The
+content and encoding of @var{annex} is specific to @var{object}; it can
+supply additional details about what data to access.
+
+Here are the specific requests of this form defined so far.  All
+@samp{qXfer:@var{object}:write:@dots{}} requests use the same reply
+formats, listed below.
+
+@table @samp
+@item qXfer:@var{spu}:write:@var{annex}:@var{offset},@var{length}:@var{data}@dots{}
+@anchor{qXfer spu write}
+Write @var{length} bytes of @var{data} to an @code{spufs} file on 
+the target system.  The annex specifies which file to write; it must 
+be of the form @file{@var{id}/@var{name}}, where @var{id} specifies an SPU
+context ID in the target process, and @var{name} identifes the @code{spufs}
+file in that context to be accessed.
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@end table
 
 Reply:
 @table @samp


-- 
  Dr. Ulrich Weigand
  GNU Toolchain for Linux on System z and Cell BE
  Ulrich.Weigand@de.ibm.com