Re: [rfc] "maint set remote"

[Daniel Jacobowitz <drow at false dot org>]

On Sat, Oct 28, 2006 at 01:00:59PM +0200, Eli Zaretskii wrote:
> > Date: Fri, 27 Oct 2006 17:59:48 -0400
> > From: Daniel Jacobowitz <drow@false.org>
> > 
> > You're right; is the attached better?
> 
> Yes, thanks.
> 
> > The PDF version of this doesn't look great, but there's not much I
> > can see to do about it (the column spacing comes out funny, and the
> > hyphenation is a bit random).
> 
> I will try to look into that when I have time.  Meanwhile, you are
> cleared to commit the patches.

Hi Eli,

I let this patch sit for a while because I wasn't really sure I was
doing the right thing.  In the end, I couldn't convince myself, so I'm
withdrawing the patch as posted; I will not rename the existing
commands.

That leaves me with two things: the improvements for set/show remote,
and the rewritten documentation, which is about the same as in the
previous posting except that it is now in the "Remote configuration"
section instead of moved to maintenance commands.

Does this seem OK?

-- 
Daniel Jacobowitz
CodeSourcery

2006-11-14  Daniel Jacobowitz  <dan@codesourcery.com>

	* remote.c (set_remote_cmd): Call help_list.
	(show_remote_cmd): Skip legacy aliases.  Handle non-show_cmd
	entries.  Add missed cleanup.
	* cli/cli-setshow.c (cmd_show_list): Handle non-show_cmd entries.

2006-11-14  Daniel Jacobowitz  <dan@codesourcery.com>

	* gdb.texinfo (Remote configuration): Rewrite documentation for
	packet configuration commands.
	(OS Information): Adjust reference to qXfer:auxv:read.
	(General Query Packets): Remove references to read-aux-vector-packet
	and set remote get-thread-local-storage-address.

Index: remote.c
===================================================================
RCS file: /cvs/src/src/gdb/remote.c,v
retrieving revision 1.236
diff -u -p -r1.236 remote.c
--- remote.c	21 Oct 2006 17:59:08 -0000	1.236
+++ remote.c	14 Nov 2006 15:48:56 -0000
@@ -6082,13 +6082,14 @@ Specify the serial device it is connecte
 static void
 set_remote_cmd (char *args, int from_tty)
 {
+  help_list (remote_set_cmdlist, "set remote ", -1, gdb_stdout);
 }
 
 static void
 show_remote_cmd (char *args, int from_tty)
 {
   /* We can't just use cmd_show_list here, because we want to skip
-     the redundant "show remote Z-packet".  */
+     the redundant "show remote Z-packet" and the legacy aliases.  */
   struct cleanup *showlist_chain;
   struct cmd_list_element *list = remote_show_cmdlist;
 
@@ -6096,16 +6097,26 @@ show_remote_cmd (char *args, int from_tt
   for (; list != NULL; list = list->next)
     if (strcmp (list->name, "Z-packet") == 0)
       continue;
-    else if (list->type == show_cmd)
+    else if (list->type == not_set_cmd)
+      /* Alias commands are exactly like the original, except they
+	 don't have the normal type.  */
+      continue;
+    else
       {
 	struct cleanup *option_chain
 	  = make_cleanup_ui_out_tuple_begin_end (uiout, "option");
 	ui_out_field_string (uiout, "name", list->name);
 	ui_out_text (uiout, ":  ");
-	do_setshow_command ((char *) NULL, from_tty, list);
+	if (list->type == show_cmd)
+	  do_setshow_command ((char *) NULL, from_tty, list);
+	else
+	  cmd_func (list, NULL, from_tty);
 	/* Close the tuple.  */
 	do_cleanups (option_chain);
       }
+
+  /* Close the tuple.  */
+  do_cleanups (showlist_chain);
 }
 
 static void
Index: cli/cli-setshow.c
===================================================================
RCS file: /cvs/src/src/gdb/cli/cli-setshow.c,v
retrieving revision 1.27
diff -u -p -r1.27 cli-setshow.c
--- cli/cli-setshow.c	17 Dec 2005 22:40:17 -0000	1.27
+++ cli/cli-setshow.c	14 Nov 2006 15:48:56 -0000
@@ -405,14 +405,17 @@ cmd_show_list (struct cmd_list_element *
 	  /* Close the tuple.  */
 	  do_cleanups (optionlist_chain);
 	}
-      if (list->type == show_cmd)
+      else
 	{
 	  struct cleanup *option_chain
 	    = make_cleanup_ui_out_tuple_begin_end (uiout, "option");
 	  ui_out_text (uiout, prefix);
 	  ui_out_field_string (uiout, "name", list->name);
 	  ui_out_text (uiout, ":  ");
-	  do_setshow_command ((char *) NULL, from_tty, list);
+	  if (list->type == show_cmd)
+	    do_setshow_command ((char *) NULL, from_tty, list);
+	  else
+	    cmd_func (list, NULL, from_tty);
           /* Close the tuple.  */
 	  do_cleanups (option_chain);
 	}
Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.366
diff -u -p -r1.366 gdb.texinfo
--- doc/gdb.texinfo	27 Oct 2006 22:23:20 -0000	1.366
+++ doc/gdb.texinfo	14 Nov 2006 15:57:10 -0000
@@ -6740,8 +6740,8 @@ identified by an integer tag; the meanin
 Depending on the configuration and operating system facilities,
 @value{GDBN} may be able to show you this information.  For remote
 targets, this functionality may further depend on the remote stub's
-support of the @samp{qXfer:auxv:read} packet, see @ref{Remote
-configuration, auxiliary vector}.
+support of the @samp{qXfer:auxv:read} packet, see
+@ref{qXfer auxiliary vector read}.
 
 @table @code
 @kindex info auxv
@@ -12760,133 +12760,83 @@ responses.
 @itemx set remote hardware-breakpoint-limit @var{limit}
 Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or
 watchpoints.  A limit of -1, the default, is treated as unlimited.
+@end table
 
-@item set remote fetch-register-packet
-@itemx set remote set-register-packet
-@itemx set remote P-packet
-@itemx set remote p-packet
-@cindex P-packet
-@cindex fetch registers from remote targets
-@cindex set registers in remote targets
-Determine whether @value{GDBN} can set and fetch registers from the
-remote target using the @samp{P} packets.  The default depends on the
-remote stub's support of the @samp{P} packets (@value{GDBN} queries
-the stub when this packet is first required).
-
-@item show remote fetch-register-packet
-@itemx show remote set-register-packet
-@itemx show remote P-packet
-@itemx show remote p-packet
-Show the current setting of using the @samp{P} packets for setting and
-fetching registers from the remote target.
-
-@cindex binary downloads
-@cindex X-packet
-@item set remote binary-download-packet
-@itemx set remote X-packet
-Determine whether @value{GDBN} sends downloads in binary mode using
-the @samp{X} packets.  The default is on.
-
-@item show remote binary-download-packet
-@itemx show remote X-packet
-Show the current setting of using the @samp{X} packets for binary
-downloads.
-
-@item set remote read-aux-vector-packet
-@cindex auxiliary vector of remote target
-@cindex @code{auxv}, and remote targets
-Set the use of the remote protocol's @samp{qXfer:auxv:read} (target
-auxiliary vector) request.  This request is used to fetch the
-remote target's @dfn{auxiliary vector}, see @ref{OS Information,
-Auxiliary Vector}.  The default setting depends on the remote stub's
-support of this request (@value{GDBN} queries the stub when this
-request is first required).  @xref{General Query Packets, qXfer}, for
-more information about this request.
-
-@item show remote read-aux-vector-packet
-Show the current setting of use of the @samp{qXfer:auxv:read} request.
-
-@item set remote symbol-lookup-packet
-@cindex remote symbol lookup request
-Set the use of the remote protocol's @samp{qSymbol} (target symbol
-lookup) request.  This request is used to communicate symbol
-information to the remote target, e.g., whenever a new shared library
-is loaded by the remote (@pxref{Files, shared libraries}).  The
-default setting depends on the remote stub's support of this request
-(@value{GDBN} queries the stub when this request is first required).
-@xref{General Query Packets, qSymbol}, for more information about this
-request.
-
-@item show remote symbol-lookup-packet
-Show the current setting of use of the @samp{qSymbol} request.
-
-@item set remote verbose-resume-packet
-@cindex resume remote target
-@cindex signal thread, and remote targets
-@cindex single-step thread, and remote targets
-@cindex thread-specific operations on remote targets
-Set the use of the remote protocol's @samp{vCont} (descriptive resume)
-request.  This request is used to resume specific threads in the
-remote target, and to single-step or signal them.  The default setting
-depends on the remote stub's support of this request (@value{GDBN}
-queries the stub when this request is first required).  This setting
-affects debugging of multithreaded programs: if @samp{vCont} cannot be
-used, @value{GDBN} might be unable to single-step a specific thread,
-especially under @code{set scheduler-locking off}; it is also
-impossible to pause a specific thread.  @xref{Packets, vCont}, for
-more details.
-
-@item show remote verbose-resume-packet
-Show the current setting of use of the @samp{vCont} request
-
-@item set remote software-breakpoint-packet
-@itemx set remote hardware-breakpoint-packet
-@itemx set remote write-watchpoint-packet
-@itemx set remote read-watchpoint-packet
-@itemx set remote access-watchpoint-packet
-@itemx set remote Z-packet
-@cindex Z-packet
-@cindex remote hardware breakpoints and watchpoints
-These commands enable or disable the use of @samp{Z} packets for
-setting breakpoints and watchpoints in the remote target.  The default
-depends on the remote stub's support of the @samp{Z} packets
-(@value{GDBN} queries the stub when each packet is first required).
-The command @code{set remote Z-packet}, kept for back-compatibility,
-turns on or off all the features that require the use of @samp{Z}
-packets.
-
-@item show remote software-breakpoint-packet
-@itemx show remote hardware-breakpoint-packet
-@itemx show remote write-watchpoint-packet
-@itemx show remote read-watchpoint-packet
-@itemx show remote access-watchpoint-packet
-@itemx show remote Z-packet
-Show the current setting of @samp{Z} packets usage.
-
-@item set remote get-thread-local-storage-address
-@kindex set remote get-thread-local-storage-address
-@cindex thread local storage of remote targets
-This command enables or disables the use of the @samp{qGetTLSAddr}
-(Get Thread Local Storage Address) request packet.  The default
-depends on whether the remote stub supports this request.
-@xref{General Query Packets, qGetTLSAddr}, for more details about this
-packet.
+@cindex remote packets, enabling and disabling
+The @value{GDBN} remote protocol autodetects the packets supported by
+your debugging stub.  If you need to override the autodetection, you
+can use these commands to enable or disable individual packets.  Each
+packet can be set to @samp{on} (the remote target supports this
+packet), @samp{off} (the remote target does not support this packet),
+or @samp{auto} (detect remote target support for this packet).  They
+all default to @samp{auto}.  For more information about each packet,
+see @ref{Remote Protocol}.
+
+During normal use, you should not have to use any of these commands.
+If you do, that may be a bug in your remote debugging stub, or a bug
+in @value{GDBN}.  You may want to report the problem to the
+@value{GDBN} developers.
+
+The available settings are:
+
+@multitable @columnfractions 0.3 0.2 0.35
+@item Command Name
+@tab Remote Packet
+@tab Related Features
+
+@item @code{fetch-register-packet}
+@tab @code{p}
+@tab @code{info registers}
+
+@item @code{set-register-packet}
+@tab @code{P}
+@tab @code{set}
+
+@item @code{binary-download-packet}
+@tab @code{X}
+@tab @code{load}, @code{set}
+
+@item @code{read-aux-vector-packet}
+@tab @code{qXfer:auxv:read}
+@tab @code{info auxv}
+
+@item @code{symbol-lookup-packet}
+@tab @code{qSymbol}
+@tab Detecting multiple threads
+
+@item @code{verbose-resume-packet}
+@tab @code{vCont}
+@tab Stepping or resuming multiple threads
+
+@item @code{software-breakpoint-packet}
+@tab @code{Z0}
+@tab @code{break}
+
+@item @code{hardware-breakpoint-packet}
+@tab @code{Z1}
+@tab @code{hbreak}
+
+@item @code{write-watchpoint-packet}
+@tab @code{Z2}
+@tab @code{watch}
+
+@item @code{read-watchpoint-packet}
+@tab @code{Z3}
+@tab @code{rwatch}
+
+@item @code{access-watchpoint-packet}
+@tab @code{Z4}
+@tab @code{awatch}
+
+@item @code{get-thread-local-storage-address-packet}
+@tab @code{qGetTLSAddr}
+@tab Displaying @code{__thread} variables
+
+@item @code{supported-packets}
+@tab @code{qSupported}
+@tab Remote communications parameters
 
-@item show remote get-thread-local-storage-address
-@kindex show remote get-thread-local-storage-address
-Show the current setting of @samp{qGetTLSAddr} packet usage.
-
-@item set remote supported-packets
-@kindex set remote supported-packets
-@cindex query supported packets of remote targets
-This command enables or disables the use of the @samp{qSupported}
-request packet.  @xref{General Query Packets, qSupported}, for more
-details about this packet.  The default is to use @samp{qSupported}.
-
-@item show remote supported-packets
-@kindex show remote supported-packets
-Show the current setting of @samp{qSupported} packet usage.
-@end table
+@end multitable
 
 @node remote stub
 @section Implementing a remote stub
@@ -23604,10 +23554,6 @@ An error occurred.  @var{nn} are hex dig
 An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub.
 @end table
 
-Use of this request packet is controlled by the @code{set remote
-get-thread-local-storage-address} command (@pxref{Remote
-configuration, set remote get-thread-local-storage-address}).
-
 @item qL @var{startflag} @var{threadcount} @var{nextthread}
 Obtain thread information from RTOS.  Where: @var{startflag} (one hex
 digit) is one to indicate the first query and zero to indicate a
@@ -23908,8 +23854,7 @@ formats, listed below.
 @item qXfer:auxv:read::@var{offset},@var{length}
 @anchor{qXfer auxiliary vector read}
 Access the target's @dfn{auxiliary vector}.  @xref{OS Information,
-auxiliary vector}, and @ref{Remote configuration,
-read-aux-vector-packet}.  Note @var{annex} must be empty.
+auxiliary vector}.  Note @var{annex} must be empty.
 
 This packet is not probed by default; the remote stub must request it,
 by suppling an appropriate @samp{qSupported} response (@pxref{qSupported}).