From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 10854 invoked by alias); 13 Aug 2002 10:34:29 -0000 Mailing-List: contact gdb-patches-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sources.redhat.com Received: (qmail 10846 invoked from network); 13 Aug 2002 10:34:26 -0000 Received: from unknown (HELO freya.inter.net.il) (192.114.186.14) by sources.redhat.com with SMTP; 13 Aug 2002 10:34:26 -0000 Received: from Zaretsky ([80.230.2.40]) by freya.inter.net.il (Mirapoint Messaging Server MOS 3.1.0.58-GA) with ESMTP id BQW39097; Tue, 13 Aug 2002 13:33:54 +0300 (IDT) Date: Tue, 13 Aug 2002 03:34:00 -0000 From: "Eli Zaretskii" To: ac131313@ges.redhat.com Message-Id: <2950-Tue13Aug2002133142+0300-eliz@is.elta.co.il> CC: gdb-patches@sources.redhat.com In-reply-to: <3D4D6494.30807@ges.redhat.com> (message from Andrew Cagney on Sun, 04 Aug 2002 13:29:56 -0400) Subject: Re: [patch/rfa:doco] Reformat ``Remote Protocol'' appendix Reply-to: Eli Zaretskii References: <3D4D6494.30807@ges.redhat.com> X-SW-Source: 2002-08/txt/msg00292.txt.bz2 > Date: Sun, 04 Aug 2002 13:29:56 -0400 > From: Andrew Cagney > > This patch re-formats the ``Remote Protocol'' section. It replaces the > @multitable with a more normal @table (and gets rid of all those hfull > problems). Thanks! Sorry for the long delay. Here are my comments: > Fields within the packet should be separated using @samp{,} @samp{;} or > @samp{:}. Except where otherwise noted all numbers are represented in > HEX with leading zeros suppressed. Suggest an index entry here about the separators. > Reply: > @xref{Stop Reply Packets}. This @xref (and others similar to it) should probably be written as @xref{Stop Reply Packets}, for the reply specifications. > @item @code{a} --- reserved > > Reserved for future use A period is missing after the last sentence. > Initialized @samp{argv[]} array passed into program. @var{arglen} > specifies the number of bytes in the hex encoded byte stream @var{arg}. > See @file{gdbserver} for more details. What is this file `gdbserver' to which we refer the reader here? Is that the gdbserver binary? > @var{addr} is address to resume. If @var{addr} is omitted, resume at > current address. Please make sure that there are 2 blanks after a period that ends a sentence, here and elsewhere. > @item @code{e} --- reserved > > Reserved for future use Missing period (there are more like this one). > For a description of the @var{XX@dots{}} data, @xref{read registers > packet}. Please use "see @ref" instead of @xref. The latter produces a capitalized "See", which is wrong in the middle of a sentence. > @item @code{H}@var{c}@var{t@dots{}} --- set thread > > Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g}, > @samp{G}, et.al.). @var{c} = @samp{c} for thread used in step and > continue; @var{t@dots{}} can be -1 for all threads. @var{c} = @samp{g} for > thread used in other operations. If zero, pick a thread, any thread. I think this text is better here: @item @code{H}@var{c}@var{t@dots{}} --- set thread Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g}, @samp{G}, et.al.). @var{c} depends on the operation to be performed: it should be @samp{c} for step and continue operations, @samp{g} for other operations. The thread designator @var{t@dots{}} may be -1, meaning all the threads, a thread number, or zero which means pick any thread. > For a discussing of naming conventions, @xref{general query packet}. This should use "see @ref" or @pxref in parens instead of @xref. > @var{t} is type: @samp{0} - software breakpoint, @samp{1} - hardware > breakpoint, @samp{2} - write watchpoint, @samp{3} - read watchpoint, > @samp{4} - access watchpoint; @var{addr} is address; @var{length} is in > bytes. For a software breakpoint, @var{length} specifies the size of Please use "---" instead of just "-". The latter is typeset by TeX as a minus, not as a dash. > @node Stop Reply Packets > @section Stop Reply Packets A @cindex entry here is probably a good idea. > The process exited, and @var{AA} is the exit status. This is only > applicable for certains sorts of targets. The trailing `s' in "certains" is a typo. > @var{AA} = signal number; @var{t@dots{}} = address of symbol "_start"; Please use @code_start} instead of "_start". > @var{d@dots{}} = base of data section; @var{b@dots{}} = base of bss section. > @emph{Note: only used by Cisco Systems targets. The difference between > this reply and the "qOffsets" query is that the 'N' packet may arrive > spontaneously whereas the 'qOffsets' is a query initiated by the host > debugger.} Please use @samp{N} instead of 'N'. > @var{XX@dots{}} is hex encoding of @sc{ascii} data. This can happen at any > time while the program is running and the debugger should continue to > wait for 'W', 'T', etc. Same here. > In response to each query, the target will reply with a list of one or > more thread ids, in big-endian hex, separated by commas. GDB will "GDB" should be @value{GDBN}. > @item @code{q}@code{ThreadExtraInfo}@code{,}@var{id} --- extra thread info > > Where @var{} is a thread-id in big-endian hex. Obtain a printable There's no need in <> around "id". > in @value{GDBN}'s @samp{info threads} display. Some examples of > possible thread extra info strings are "Runnable", or "Blocked on > Mutex". Please use `` and '' rather than " for quoting things. The former are typeset by TeX in a way that produces a more pleasant effect (the on-line manual has `` and '' transformed into "). > @item @code{q}@code{Rcmd,}@var{COMMAND} --- remote command > > @var{COMMAND} (hex encoded) is passed to the local interpreter for Please use @var{command}, not @var{COMMAND}. In Info the up-casing will be done anyway, while in the printed version upper-case is ugly and against the conventions of @var arguments. > number of intermediate @code{O}@var{OUTPUT} console output packets. Same with OUTPUT. > @item @code{qSymbol:}@var{sym_value}:@var{sym_name} --- symbol value > > Set the value of SYM_NAME to SYM_VALUE. These should be @var{sym_name} and @var{sym_value}. Finally, perhaps there should be an index entry for each packet/command.