[rfc] "maint set remote"

Daniel Jacobowitz
2006-10-26T21:26:52Z

Per my discussion with Eli earlier today. This patch removes most of
the documentation for the individual packet commands, moves them under
"maint", and aggregates their documentation into a table there. The
new bits of interest:

+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:

I also fixed "show remote" while I was here; it became apparent that it
wasn't showing all of the settings once I cut down on the number.

Comments? OK?

--
Daniel Jacobowitz
CodeSourcery

2006-10-26 Daniel Jacobowitz <dan@codesourcery.com>

* remote.c (maint_set_remote_cmdlist, maint_show_remote_cmdlist):
New.
(add_packet_config_cmd): Remove legacy argument. Use the new lists.
(remote_Z_packet_detect, set_remote_protocol_Z_packet_cmd)
(show_remote_protocol_Z_packet_cmd): Delete.
(set_remote_cmd): Call help_list.
(show_remote_cmd): Just call cmd_show_list.
(maint_set_remote_cmd, maint_show_remote_cmd): New.
(_initialize_remote): Add "maint set remote". Delete Z-packet.
Update calls to add_packet_config_cmd.
* cli/cli-setshow.c (cmd_show_list): Handle non-show_cmd entries.
* NEWS: Mention "maint set remote" and "maint show remote".

2006-10-26 Daniel Jacobowitz <dan@codesourcery.com>

* gdb.texinfo (Remote configuration): Remove packet
configuration commands.
(Maintenance Commands): Add "maint set remote" and "maint show
remote".
(General Query Packets): Remove reference to read-aux-vector-packet.

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 26 Oct 2006 21:18:06 -0000
@@ -214,6 +214,8 @@ void _initialize_remote (void);

static struct cmd_list_element *remote_set_cmdlist;
static struct cmd_list_element *remote_show_cmdlist;
+static struct cmd_list_element *maint_set_remote_cmdlist;
+static struct cmd_list_element *maint_show_remote_cmdlist;

/* Description of the remote protocol state for the currently
connected target. This is per-target state, and independent of the
@@ -734,7 +736,7 @@ show_packet_config_cmd (struct packet_co

static void
add_packet_config_cmd (struct packet_config *config, const char *name,
- const char *title, int legacy)
+ const char *title)
{
char *set_doc;
char *show_doc;
@@ -748,23 +750,14 @@ add_packet_config_cmd (struct packet_con
name, title);
show_doc = xstrprintf ("Show current use of remote protocol `%s' (%s) packet",
name, title);
- /* set/show TITLE-packet {auto,on,off} */
+ /* maint set/show TITLE-packet {auto,on,off} */
cmd_name = xstrprintf ("%s-packet", title);
add_setshow_auto_boolean_cmd (cmd_name, class_obscure,
&config->detect, set_doc, show_doc, NULL, /* help_doc */
set_remote_protocol_packet_cmd,
show_remote_protocol_packet_cmd,
- &remote_set_cmdlist, &remote_show_cmdlist);
- /* set/show remote NAME-packet {auto,on,off} -- legacy. */
- if (legacy)
- {
- char *legacy_name;
- legacy_name = xstrprintf ("%s-packet", name);
- add_alias_cmd (legacy_name, cmd_name, class_obscure, 0,
- &remote_set_cmdlist);
- add_alias_cmd (legacy_name, cmd_name, class_obscure, 0,
- &remote_show_cmdlist);
- }
+ &maint_set_remote_cmdlist,
+ &maint_show_remote_cmdlist);
}

static enum packet_result
@@ -925,35 +918,6 @@ enum Z_packet_type
NR_Z_PACKET_TYPES
};

-/* For compatibility with older distributions. Provide a ``set remote
- Z-packet ...'' command that updates all the Z packet types. */
-
-static enum auto_boolean remote_Z_packet_detect;
-
-static void
-set_remote_protocol_Z_packet_cmd (char *args, int from_tty,
- struct cmd_list_element *c)
-{
- int i;
- for (i = 0; i < NR_Z_PACKET_TYPES; i++)
- {
- remote_protocol_packets[PACKET_Z0 + i].detect = remote_Z_packet_detect;
- update_packet_config (&remote_protocol_packets[PACKET_Z0 + i]);
- }
-}
-
-static void
-show_remote_protocol_Z_packet_cmd (struct ui_file *file, int from_tty,
- struct cmd_list_element *c,
- const char *value)
-{
- int i;
- for (i = 0; i < NR_Z_PACKET_TYPES; i++)
- {
- show_packet_config_cmd (&remote_protocol_packets[PACKET_Z0 + i]);
- }
-}
-
/* Should we try the 'ThreadInfo' query packet?

This variable (NOT available to the user: auto-detect only!)
@@ -6082,30 +6046,26 @@ 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". */
- struct cleanup *showlist_chain;
- struct cmd_list_element *list = remote_show_cmdlist;
-
- showlist_chain = make_cleanup_ui_out_tuple_begin_end (uiout, "showlist");
- for (; list != NULL; list = list->next)
- if (strcmp (list->name, "Z-packet") == 0)
- continue;
- else if (list->type == show_cmd)
- {
- 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);
- /* Close the tuple. */
- do_cleanups (option_chain);
- }
+ cmd_show_list (remote_show_cmdlist, from_tty, "");
+}
+
+static void
+maint_set_remote_cmd (char *args, int from_tty)
+{
+ help_list (maint_set_remote_cmdlist, "maintenance set remote ",
+ -1, gdb_stdout);
+}
+
+static void
+maint_show_remote_cmd (char *args, int from_tty)
+{
+ cmd_show_list (maint_show_remote_cmdlist, from_tty, "");
}

static void
@@ -6176,14 +6136,12 @@ _initialize_remote (void)

add_prefix_cmd ("remote", class_maintenance, set_remote_cmd, _("\
Remote protocol specific variables\n\
-Configure various remote-protocol specific variables such as\n\
-the packets being used"),
+Configure various remote-protocol specific variables."),
&remote_set_cmdlist, "set remote ",
0 /* allow-unknown */, &setlist);
add_prefix_cmd ("remote", class_maintenance, show_remote_cmd, _("\
Remote protocol specific variables\n\
-Configure various remote-protocol specific variables such as\n\
-the packets being used"),
+Configure various remote-protocol specific variables."),
&remote_show_cmdlist, "show remote ",
0 /* allow-unknown */, &showlist);

@@ -6264,62 +6222,63 @@ Show the maximum size of the address (in
NULL, /* FIXME: i18n: */
&setlist, &showlist);

+ /* Add maint set remote and maint show remote, for things which
+ should almost always be left alone, but can be useful in
+ rare cases or for testing. */
+ add_prefix_cmd ("remote", class_maintenance, maint_set_remote_cmd, _("\
+Internal remote protocol variables\n\
+Configure internal settings of the remote protocol, e.g. override\n\
+the packets being used."),
+ &maint_set_remote_cmdlist, "maintenance set remote ",
+ 0 /* allow-unknown */, &maintenance_set_cmdlist);
+ add_prefix_cmd ("remote", class_maintenance, maint_show_remote_cmd, _("\
+Internal remote protocol variables\n\
+Configure internal settings of the remote protocol, e.g. override\n\
+the packets being used."),
+ &maint_show_remote_cmdlist, "maintenance show remote ",
+ 0 /* allow-unknown */, &maintenance_show_cmdlist);
+
add_packet_config_cmd (&remote_protocol_packets[PACKET_X],
- "X", "binary-download", 1);
+ "X", "binary-download");

add_packet_config_cmd (&remote_protocol_packets[PACKET_vCont],
- "vCont", "verbose-resume", 0);
+ "vCont", "verbose-resume");

add_packet_config_cmd (&remote_protocol_packets[PACKET_qSymbol],
- "qSymbol", "symbol-lookup", 0);
+ "qSymbol", "symbol-lookup");

add_packet_config_cmd (&remote_protocol_packets[PACKET_P],
- "P", "set-register", 1);
+ "P", "set-register");

add_packet_config_cmd (&remote_protocol_packets[PACKET_p],
- "p", "fetch-register", 1);
+ "p", "fetch-register");

add_packet_config_cmd (&remote_protocol_packets[PACKET_Z0],
- "Z0", "software-breakpoint", 0);
+ "Z0", "software-breakpoint");

add_packet_config_cmd (&remote_protocol_packets[PACKET_Z1],
- "Z1", "hardware-breakpoint", 0);
+ "Z1", "hardware-breakpoint");

add_packet_config_cmd (&remote_protocol_packets[PACKET_Z2],
- "Z2", "write-watchpoint", 0);
+ "Z2", "write-watchpoint");

add_packet_config_cmd (&remote_protocol_packets[PACKET_Z3],
- "Z3", "read-watchpoint", 0);
+ "Z3", "read-watchpoint");

add_packet_config_cmd (&remote_protocol_packets[PACKET_Z4],
- "Z4", "access-watchpoint", 0);
+ "Z4", "access-watchpoint");

add_packet_config_cmd (&remote_protocol_packets[PACKET_qXfer_auxv],
- "qXfer:auxv:read", "read-aux-vector", 0);
+ "qXfer:auxv:read", "read-aux-vector");

add_packet_config_cmd (&remote_protocol_packets[PACKET_qXfer_memory_map],
- "qXfer:memory-map:read", "memory-map", 0);
+ "qXfer:memory-map:read", "memory-map");

add_packet_config_cmd (&remote_protocol_packets[PACKET_qGetTLSAddr],
- "qGetTLSAddr", "get-thread-local-storage-address",
- 0);
+ "qGetTLSAddr", "get-thread-local-storage-address");

add_packet_config_cmd (&remote_protocol_packets[PACKET_qSupported],
- "qSupported", "supported-packets", 0);
-
- /* Keep the old ``set remote Z-packet ...'' working. Each individual
- Z sub-packet has its own set and show commands, but users may
- have sets to this variable in their .gdbinit files (or in their
- documentation). */
- add_setshow_auto_boolean_cmd ("Z-packet", class_obscure,
- &remote_Z_packet_detect, _("\
-Set use of remote protocol `Z' packets"), _("\
-Show use of remote protocol `Z' packets "), _("\
-When set, GDB will attempt to use the remote breakpoint and watchpoint\n\
-packets."),
- set_remote_protocol_Z_packet_cmd,
- show_remote_protocol_Z_packet_cmd, /* FIXME: i18n: Use of remote protocol `Z' packets is %s. */
- &remote_set_cmdlist, &remote_show_cmdlist);
+ "qSupported", "supported-packets");

/* Eventually initialize fileio. See fileio.c */
initialize_remote_fileio (remote_set_cmdlist, remote_show_cmdlist);
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 26 Oct 2006 21:18:07 -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.365
diff -u -p -r1.365 gdb.texinfo
--- doc/gdb.texinfo 21 Oct 2006 13:06:03 -0000 1.365
+++ doc/gdb.texinfo 26 Oct 2006 21:18:10 -0000
@@ -12760,132 +12760,6 @@ 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.
-
-@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.
-
-@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

@node remote stub
@@ -22631,6 +22505,72 @@ data in a @file{gmon.out} file, be sure
Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be
compiled with the @samp{-pg} compiler option.

+@kindex maint set remote
+@kindex maint show remote
+@cindex remote packets, enabling and disabling
+@item maint set remote
+@itemx maint show remote
+
+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 @samp @columnfractions 0.7 0.3
+@item Command Name
+@tab Remote Packet
+
+@item fetch-register-packet
+@tab p
+
+@item set-register-packet
+@tab P
+
+@item binary-download-packet
+@tab X
+
+@item read-aux-vector-packet
+@tab qXfer:auxv:read
+
+@item symbol-lookup-packet
+@tab qSymbol
+
+@item verbose-resume-packet
+@tab vCont
+
+@item software-breakpoint-packet
+@tab Z0
+
+@item hardware-breakpoint-packet
+@tab Z1
+
+@item write-watchpoint-packet
+@tab Z2
+
+@item read-watchpoint-packet
+@tab Z3
+
+@item access-watchpoint-packet
+@tab Z4
+
+@item get-thread-local-storage-address-packet
+@tab qGetTLSAddr
+
+@item supported-packets
+@tab qSupported
+@end multitable
+
@kindex maint show-debug-regs
@cindex x86 hardware debug registers
@item maint show-debug-regs
@@ -23908,8 +23848,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}).
Index: NEWS
===================================================================
RCS file: /cvs/src/src/gdb/NEWS,v
retrieving revision 1.198
diff -u -p -r1.198 NEWS
--- NEWS 18 Oct 2006 15:29:18 -0000 1.198
+++ NEWS 26 Oct 2006 21:23:41 -0000
@@ -33,6 +33,14 @@ show trace-commands
a number of `+' symbols representing the nesting depth.
The source command now has a `-v' option to enable the same feature.

+* Moved commands
+
+maint set remote
+maint show remote
+ The individual packet settings have been moved from "set remote" and
+ "show remote" to reflect the fact that they should generally not be
+ used.
+
* REMOVED features

The ARM Demon monitor support (RDP protocol, "target rdp").