gdbserver: allow the --debug command line option to take a value

Currently, gdbserver has the following command line options related to
debugging output:

  --debug
  --remote-debug
  --event-loop-debug

This doesn't scale well.  If I want an extra debug component I need to
add another command line flag.

This commit changes --debug to take a list of components.

The currently supported components are: all, threads, remote, and
event-loop.  The 'threads' component represents the debug we currently
get from the --debug option.  And if --debug is used without a
component list then the threads component is assumed as the default.

Currently the threads component actually includes a lot of output that
is not really threads related.  In the future I'd like to split this
up into some new, separate components.  But that is not part of this
commit, or even this series.

The special component 'all' does what you'd expect: enables debug
output from all supported components.

The component list is parsed left to write, and you can prefix a
component with '-' to disable that component, so I can write:

  target> gdbserver --debug=all,-event-loop

to get debug for all components except the event-loop component.

I've removed the existing --remote-debug and --event-loop-debug
command line options, these are equivalent to --debug=remote and
--debug=event-loop respectively, or --debug=remote,event-loop to
enable both components.

In this commit I've only update the command line options, in the next
commit I'll update the monitor commands to support a similar
interface.

Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Tom Tromey <tom@tromey.com>

1 files changed, 56 insertions, 14 deletions

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d2428ef..6d20e4c 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -23674,11 +23674,42 @@ program.  For more information,
 @pxref{--multi Option in Types of Remote Connnections}.
 
 @cindex @option{--debug}, @code{gdbserver} option
-The @option{--debug} option tells @code{gdbserver} to display extra
-status information about the debugging process.
-@cindex @option{--remote-debug}, @code{gdbserver} option
-The @option{--remote-debug} option tells @code{gdbserver} to display
-remote protocol debug output.
+The @option{--debug[=option1,option2,@dots{}]} option tells
+@code{gdbserver} to display extra diagnostic information about the
+debugging process.  The options (@var{option1}, @var{option2}, etc)
+control for which areas of @code{gdbserver} additional information
+will be displayed, possible values are:
+
+@table @code
+@item all
+This enables all available diagnostic output.
+@item threads
+This enables diagnostic output related to threading.  Currently other
+general diagnostic output is included in this category, but this could
+change in future releases of @code{gdbserver}.
+@item event-loop
+This enables event-loop specific diagnostic output.
+@item remote
+This enables diagnostic output related to the transfer of remote
+protocol packets too and from the debugger.
+@end table
+
+@noindent
+If no options are passed to @option{--debug} then this is treated as
+equivalent to @option{--debug=threads}.  This could change in future
+releases of @code{gdbserver}.  The options passed to @option{--debug}
+are processed left to right, and individual options can be prefixed
+with the @kbd{-} (minus) character to disable diagnostic output from
+this area, so it is possible to use:
+
+@smallexample
+  target> gdbserver --debug=all,-event-loop
+@end smallexample
+
+@noindent
+In order to enable all diagnostic output except that for the
+event-loop.
+
 @cindex @option{--debug-file}, @code{gdbserver} option
 @cindex @code{gdbserver}, send all debug output to a single file
 The @option{--debug-file=@var{filename}} option tells @code{gdbserver} to
@@ -50671,16 +50702,27 @@ the program you want to debug.  The syntax is:
 target> gdbserver --multi @var{comm}
 @end smallexample
 
-@item --debug
-Instruct @code{gdbserver} to display extra status information about the debugging
-process.
-This option is intended for @code{gdbserver} development and for bug reports to
-the developers.
+@item --debug@r{[}=option1,option2,@dots{}@r{]}
+Instruct @code{gdbserver} to display extra status information about
+the debugging process.  This option is intended for @code{gdbserver}
+development and for bug reports to the developers.
 
-@item --remote-debug
-Instruct @code{gdbserver} to display remote protocol debug output.
-This option is intended for @code{gdbserver} development and for bug reports to
-the developers.
+Each @var{option} is the name of a component for which debugging
+should be enabled.  The list of possible options is @option{all},
+@option{threads}, @option{event-loop}, @option{remote}.  The special
+option @option{all} enables all components.  The option list is
+processed left to right, and an option can be prefixed with the
+@kbd{-} character to disable output for that component, so you could write:
+
+@smallexample
+target> gdbserver --debug=all,-event-loop
+@end smallexample
+
+@noindent
+to turn on debug output for all components except @option{event-loop}.
+If no options are passed to @option{--debug} then this is treated as
+equivalent to @option{--debug=threads}.  This could change in future
+releases of @code{gdbserver}.
 
 @item --debug-file=@var{filename}
 Instruct @code{gdbserver} to send any debug output to the given @var{filename}.