From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 27839 invoked by alias); 7 Nov 2015 08:18:16 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 27782 invoked by uid 89); 7 Nov 2015 08:18:15 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-0.8 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_NONE,SPF_SOFTFAIL autolearn=no version=3.3.2 X-HELO: mtaout25.012.net.il Received: from mtaout25.012.net.il (HELO mtaout25.012.net.il) (80.179.55.181) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Sat, 07 Nov 2015 08:18:13 +0000 Received: from conversion-daemon.mtaout25.012.net.il by mtaout25.012.net.il (HyperSendmail v2007.08) id <0NXF00300QRKB300@mtaout25.012.net.il> for gdb-patches@sourceware.org; Sat, 07 Nov 2015 10:15:52 +0200 (IST) Received: from HOME-C4E4A596F7 ([84.94.185.246]) by mtaout25.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0NXF00HDJQYF1C90@mtaout25.012.net.il>; Sat, 07 Nov 2015 10:15:52 +0200 (IST) Date: Sat, 07 Nov 2015 08:18:00 -0000 From: Eli Zaretskii Subject: Re: [PATCH 3/3] Target remote mode fork and exec docs In-reply-to: <1446854188-496-4-git-send-email-donb@codesourcery.com> To: Don Breazeal Cc: gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: <83a8qqql38.fsf@gnu.org> References: <1446854188-496-1-git-send-email-donb@codesourcery.com> <1446854188-496-4-git-send-email-donb@codesourcery.com> X-IsSubscribed: yes X-SW-Source: 2015-11/txt/msg00213.txt.bz2 > From: Don Breazeal > Date: Fri, 6 Nov 2015 15:56:28 -0800 > > diff --git a/gdb/NEWS b/gdb/NEWS > index b2b1e99..166a6ca 100644 > --- a/gdb/NEWS > +++ b/gdb/NEWS > @@ -87,6 +87,14 @@ set remote exec-event-feature-packet > show remote exec-event-feature-packet > Set/show the use of the remote exec event feature. > > +* Target remote mode fork and exec events > + > + ** GDB now has support for fork and exec events on target remote mode > + Linux targets. For such targets with Linux kernels 2.5.46 and later, > + this enables follow-fork-mode, detach-on-fork and fork and exec > + catchpoints. Note that follow-exec-mode is not supported, because > + target remote mode does not support the 'run' command. > + > *** Changes in GDB 7.10 This part is OK. > -@value{GDBN} needs an unstripped copy of your program to access symbol > -and debugging information. Some remote targets (@pxref{qXfer > -executable filename read}, and @pxref{Host I/O Packets}) allow > -@value{GDBN} to access program files over the same connection used to > -communicate with @value{GDBN}. With such a target, if the remote > -program is unstripped, the only command you need is @code{target > -remote}. Otherwise, start up @value{GDBN} using the name of the local > +@value{GDBN} supports two types of remote connections, @kbd{target remote} > +mode and @kbd{target extended-remote} mode. There are several major > +differences between the two. In @kbd{target extended-remote} mode, GDB ^^^ @value{GDBN} > +stays connected to @code{gdbserver} after the debugged program exits or you > +detach from it, and @code{gdbserver} provides support for the @code{run} > +and @code{attach} commands. Saying "several major differences" and then neither describing them nor providing a reference (not even just "described below") will leave the reader confused, I think. How about a short summary of the differences, e.g. as an itemized list, here? Also, does the sentence that follow (the last one in the above excerpt) need to be here? It reads strange, especially since it doesn't seem like it belongs to the aforementioned differences. Maybe you could reword it so it did contrast the two modes. Alternatively, perhaps the following subsections are better rearranged as extended descriptions of each of the differences, e.g. using @table. Right now, they read somewhat confusingly, because the description jumps between the two modes without providing any intermediate summary for the reader, and thus it is easy to become confused as to what mode and what difference you are describing. Some better organization of the same material could help the reader organize their thoughts and come out with a better understanding of the differences. Last, but not least: please consider adding @cindex entries to each of the subsections, with text that describes the main subject of each subsection. In many cases, just the down-cased name of the section is a good starting point. This will help the readers find the subsection quickly using the Info index-searching commands, which is important for using the manual as a reference. > +@item > +Finally, connect to your target. For TCP connections, you must start up > +@code{gdbserver} prior to using the @kbd{target remote} or > +@kbd{target extended-remote} command. Otherwise you may get an error > +whose text depends on the host system, but which usually looks something > +like @samp{Connection refused}. Don't use the @code{load} command in > +@value{GDBN} when using @code{gdbserver}, since the program is already on > +the target. There's some inconsistency in your usage of @code and @kbd markup for commands. In general, the correct markup is @kbd when the context is about commands typed by the user, and @code otherwise. (The GDB manual almost never uses @kbd, for historical reasons, btw.) You have changed some of the @code to @kbd regardless of context, or so it seems. But in the above passage, you use @code as well, so I'm unsure what is your rule for selecting one or the other. > @item target remote @var{serial-device} > -@cindex serial line, @code{target remote} > +@item target extended-remote @var{serial-device} ^^^^^ Should be @itemx. > @item target remote @code{udp:@var{host}:@var{port}} > -@cindex @acronym{UDP} port, @code{target remote} > +@item target extended-remote @code{udp:@var{host}:@var{port}} Likewise. > @item target remote | @var{command} > -@cindex pipe, @code{target remote} to > +@item target extended-remote | @var{command} Likewise. > -@subsection Running @code{gdbserver} > +@subsection Running gdbserver Not sure why you removed the markup from "gdbserver" here. Thanks.