Re: [patch] IPv6 support for gdbserver

[Eli Zaretskii <eliz@gnu.org>]

> Date: Sun, 8 Oct 2006 21:02:39 +0200
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> Cc: gdb-patches@sourceware.org
> 
> patch for the IPv6 support according to the Daniel Jacobowitz's recommendation:
> 	http://sourceware.org/ml/gdb-patches/2006-09/msg00194.html

Thanks.  I have a few comments about the documentation patch:

> -@item target remote @code{@var{host}:@var{port}}
> +@item  target remote @code{@var{host}:@var{port}}

This just changes whitespace; please don't.

> +@code{tcp6:} prefix forces IPv6 network connection while @code{tcp4:} forces

Please say ``The @code{tcp6:} prefix forces IPv6 network ...''.

> +@code{udp6:} prefix forces IPv6 network connection while @code{udp4:} forces

Same here.

> +@var{comm} is either a device name (to use a serial line) or file descriptions
> +numbers or a TCP hostname and portnumber.  For example, to debug Emacs with the

A better way of putting it would be

  @var{comm} is a device name (to use a serial line), a file descriptor,
  or a TCP hostname and portnumber.

> -The only difference from the previous example is the first argument,
> -specifying that you are communicating with the host @value{GDBN} via
> -TCP.  The @samp{host:2345} argument means that @code{gdbserver} is to
> -expect a TCP connection from machine @samp{host} to local TCP port 2345.
> -(Currently, the @samp{host} part is ignored.)  You can choose any number
> -you want for the port number as long as it does not conflict with any
> -TCP ports already in use on the target system (for example, @code{23} is
> -reserved for @code{telnet}).@footnote{If you choose a port number that
> -conflicts with another service, @code{gdbserver} prints an error message
> -and exits.}  You must use the same port number with the host @value{GDBN}
> -@code{target remote} command.

Why did you drop this part?

> +This example still debugs the same program just in this case it is specifying
> +that you are communicating with the host @value{GDBN} via TCP.
> +The @code{gdbserver} specific part @code{fd34} directs @code{gdbserver} to use
> +already preopened file descriptor 3 for @value{GDBN} remote serial protocol
> +input and file descriptor 4 for the protocol output.  As the format is
> +@code{fd<character><character>} you cannot specify file descriptors numbers
> +above 9.

First, please use @var{} instead of <..>, as in
@code{fd@var{c1}@var{c2}} (I find <character> too lengthy).

And second, isn't there a better way of specifying two descriptors?  I
find the "fdNM" method inelegant, and the limitation of a single-digit
descriptor it requires too high a price to pay.  I hope we can come up
with a better method.

> +You can choose any port number you want (@code{2345} here) as long as it does
> +not conflict with any TCP ports already in use on the target system (for
> +example, @code{23} is reserved for @code{telnet}).@footnote{If you choose
> +a port number that conflicts with another service, @code{socat} prints an error
> +message and exits.}  You must use the same port number with the host
> +@value{GDBN} @code{target remote} command.
> +
> +On IPv4 networks you may also run @code{gdbserver} directly, without the
> +@code{socat} helper there (equivalent command to the example above):
> +
> +@smallexample
> +target> gdbserver :2345 emacs foo.txt
> +@end smallexample

The example (and the sentence that precedes it) should be before the
descriptive text, otherwise the text doesn't make sense.

> 	* gdb.texinfo (Using the gdbserver program): Remove "host:port".

Why?  I think back-compatibility is important.