* gdb.texinfo (Remote): Move the sub-section ``The GDB remote

serial protocol'' from here.
(Remote Debugging): To here.  New chapter.

2 files changed, 212 insertions, 209 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 2d8bc4b..40592c0 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,9 @@
+2002-01-21  Andrew Cagney  <ac131313@redhat.com>
+
+	* gdb.texinfo (Remote): Move the sub-section ``The GDB remote
+	serial protocol'' from here.
+	(Remote Debugging): To here.  New chapter.
+
 2002-01-20  Andrew Cagney  <ac131313@redhat.com>
 
 	* gdbint.texinfo (Target Architecture Definition): Delete
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index bc9b191..43f6e36 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -9901,12 +9901,209 @@ communicate with @value{GDBN}.
 Other remote targets may be available in your
 configuration of @value{GDBN}; use @code{help target} to list them.
 
-@menu
-* Remote Serial::               @value{GDBN} remote serial protocol
-@end menu
+@node KOD
+@section Kernel Object Display
+
+@cindex kernel object display
+@cindex kernel object
+@cindex KOD
+
+Some targets support kernel object display.  Using this facility,
+@value{GDBN} communicates specially with the underlying operating system
+and can display information about operating system-level objects such as
+mutexes and other synchronization objects.  Exactly which objects can be
+displayed is determined on a per-OS basis.
+
+Use the @code{set os} command to set the operating system.  This tells
+@value{GDBN} which kernel object display module to initialize:
+
+@example
+(@value{GDBP}) set os cisco
+@end example
+
+If @code{set os} succeeds, @value{GDBN} will display some information
+about the operating system, and will create a new @code{info} command
+which can be used to query the target.  The @code{info} command is named
+after the operating system:
 
-@node Remote Serial
-@subsection The @value{GDBN} remote serial protocol
+@example
+(@value{GDBP}) info cisco
+List of Cisco Kernel Objects
+Object     Description
+any        Any and all objects
+@end example
+
+Further subcommands can be used to query about particular objects known
+by the kernel.
+
+There is currently no way to determine whether a given operating system
+is supported other than to try it.
+
+
+@node Remote Debugging
+@chapter Debugging remote programs
+
+@node Server
+@section Using the @code{gdbserver} program
+
+@kindex gdbserver
+@cindex remote connection without stubs
+@code{gdbserver} is a control program for Unix-like systems, which
+allows you to connect your program with a remote @value{GDBN} via
+@code{target remote}---but without linking in the usual debugging stub.
+
+@code{gdbserver} is not a complete replacement for the debugging stubs,
+because it requires essentially the same operating-system facilities
+that @value{GDBN} itself does.  In fact, a system that can run
+@code{gdbserver} to connect to a remote @value{GDBN} could also run
+@value{GDBN} locally!  @code{gdbserver} is sometimes useful nevertheless,
+because it is a much smaller program than @value{GDBN} itself.  It is
+also easier to port than all of @value{GDBN}, so you may be able to get
+started more quickly on a new system by using @code{gdbserver}.
+Finally, if you develop code for real-time systems, you may find that
+the tradeoffs involved in real-time operation make it more convenient to
+do as much development work as possible on another system, for example
+by cross-compiling.  You can use @code{gdbserver} to make a similar
+choice for debugging.
+
+@value{GDBN} and @code{gdbserver} communicate via either a serial line
+or a TCP connection, using the standard @value{GDBN} remote serial
+protocol.
+
+@table @emph
+@item On the target machine,
+you need to have a copy of the program you want to debug.
+@code{gdbserver} does not need your program's symbol table, so you can
+strip the program if necessary to save space.  @value{GDBN} on the host
+system does all the symbol handling.
+
+To use the server, you must tell it how to communicate with @value{GDBN};
+the name of your program; and the arguments for your program.  The
+syntax is:
+
+@smallexample
+target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
+@end smallexample
+
+@var{comm} is either a device name (to use a serial line) or a TCP
+hostname and portnumber.  For example, to debug Emacs with the argument
+@samp{foo.txt} and communicate with @value{GDBN} over the serial port
+@file{/dev/com1}:
+
+@smallexample
+target> gdbserver /dev/com1 emacs foo.txt
+@end smallexample
+
+@code{gdbserver} waits passively for the host @value{GDBN} to communicate
+with it.
+
+To use a TCP connection instead of a serial line:
+
+@smallexample
+target> gdbserver host:2345 emacs foo.txt
+@end smallexample
+
+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.
+
+@item On the @value{GDBN} host machine,
+you need an unstripped copy of your program, since @value{GDBN} needs
+symbols and debugging information.  Start up @value{GDBN} as usual,
+using the name of the local copy of your program as the first argument.
+(You may also need the @w{@samp{--baud}} option if the serial line is
+running at anything other than 9600@dmn{bps}.)  After that, use @code{target
+remote} to establish communications with @code{gdbserver}.  Its argument
+is either a device name (usually a serial device, like
+@file{/dev/ttyb}), or a TCP port descriptor in the form
+@code{@var{host}:@var{PORT}}.  For example:
+
+@smallexample
+(@value{GDBP}) target remote /dev/ttyb
+@end smallexample
+
+@noindent
+communicates with the server via serial line @file{/dev/ttyb}, and
+
+@smallexample
+(@value{GDBP}) target remote the-target:2345
+@end smallexample
+
+@noindent
+communicates via a TCP connection to port 2345 on host @w{@file{the-target}}.
+For TCP connections, you must start up @code{gdbserver} prior to using
+the @code{target remote} command.  Otherwise you may get an error whose
+text depends on the host system, but which usually looks something like
+@samp{Connection refused}.
+@end table
+
+@node NetWare
+@section Using the @code{gdbserve.nlm} program
+
+@kindex gdbserve.nlm
+@code{gdbserve.nlm} is a control program for NetWare systems, which
+allows you to connect your program with a remote @value{GDBN} via
+@code{target remote}.
+
+@value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
+using the standard @value{GDBN} remote serial protocol.
+
+@table @emph
+@item On the target machine,
+you need to have a copy of the program you want to debug.
+@code{gdbserve.nlm} does not need your program's symbol table, so you
+can strip the program if necessary to save space.  @value{GDBN} on the
+host system does all the symbol handling.
+
+To use the server, you must tell it how to communicate with
+@value{GDBN}; the name of your program; and the arguments for your
+program.  The syntax is:
+
+@smallexample
+load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
+              [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
+@end smallexample
+
+@var{board} and @var{port} specify the serial line; @var{baud} specifies
+the baud rate used by the connection.  @var{port} and @var{node} default
+to 0, @var{baud} defaults to 9600@dmn{bps}.
+
+For example, to debug Emacs with the argument @samp{foo.txt}and
+communicate with @value{GDBN} over serial port number 2 or board 1
+using a 19200@dmn{bps} connection:
+
+@smallexample
+load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
+@end smallexample
+
+@item On the @value{GDBN} host machine,
+you need an unstripped copy of your program, since @value{GDBN} needs
+symbols and debugging information.  Start up @value{GDBN} as usual,
+using the name of the local copy of your program as the first argument.
+(You may also need the @w{@samp{--baud}} option if the serial line is
+running at anything other than 9600@dmn{bps}.  After that, use @code{target
+remote} to establish communications with @code{gdbserve.nlm}.  Its
+argument is a device name (usually a serial device, like
+@file{/dev/ttyb}).  For example:
+
+@smallexample
+(@value{GDBP}) target remote /dev/ttyb
+@end smallexample
+
+@noindent
+communications with the server via serial line @file{/dev/ttyb}.
+@end table
+
+@node remote stub
+@section Implementing a remote stub
 
 @cindex remote serial debugging, overview
 To debug a program running on another machine (the debugging
@@ -9998,13 +10195,10 @@ recently added stubs.
 * Stub Contents::       What the stub can do for you
 * Bootstrapping::       What you must do for the stub
 * Debug Session::       Putting it all together
-* Protocol::            Definition of the communication protocol
-* Server::                Using the `gdbserver' program
-* NetWare::                Using the `gdbserve.nlm' program
 @end menu
 
 @node Stub Contents
-@subsubsection What the stub can do for you
+@subsection What the stub can do for you
 
 @cindex remote serial stub
 The debugging stub for your architecture supplies these three
@@ -10055,7 +10249,7 @@ start of your debugging session.
 @end table
 
 @node Bootstrapping
-@subsubsection What you must do for the stub
+@subsection What you must do for the stub
 
 @cindex remote stub, support routines
 The debugging stubs that come with @value{GDBN} are set up for a particular
@@ -10146,7 +10340,7 @@ subroutines which @code{@value{GCC}} generates as inline code.
 
 
 @node Debug Session
-@subsubsection Putting it all together
+@subsection Putting it all together
 
 @cindex remote serial debugging summary
 In summary, when your program is ready to debug, you must follow these
@@ -10264,7 +10458,7 @@ remote} again to connect once more.)  If you type @kbd{n}, @value{GDBN}
 goes back to waiting.
 
 @node Protocol
-@subsubsection Communication protocol
+@section Communication protocol
 
 @cindex debugging stub, example
 @cindex remote stub, example
@@ -11123,203 +11317,6 @@ Example sequence of a target being stepped by a single instruction:
 <- @code{+}
 @end example
 
-@node Server
-@subsubsection Using the @code{gdbserver} program
-
-@kindex gdbserver
-@cindex remote connection without stubs
-@code{gdbserver} is a control program for Unix-like systems, which
-allows you to connect your program with a remote @value{GDBN} via
-@code{target remote}---but without linking in the usual debugging stub.
-
-@code{gdbserver} is not a complete replacement for the debugging stubs,
-because it requires essentially the same operating-system facilities
-that @value{GDBN} itself does.  In fact, a system that can run
-@code{gdbserver} to connect to a remote @value{GDBN} could also run
-@value{GDBN} locally!  @code{gdbserver} is sometimes useful nevertheless,
-because it is a much smaller program than @value{GDBN} itself.  It is
-also easier to port than all of @value{GDBN}, so you may be able to get
-started more quickly on a new system by using @code{gdbserver}.
-Finally, if you develop code for real-time systems, you may find that
-the tradeoffs involved in real-time operation make it more convenient to
-do as much development work as possible on another system, for example
-by cross-compiling.  You can use @code{gdbserver} to make a similar
-choice for debugging.
-
-@value{GDBN} and @code{gdbserver} communicate via either a serial line
-or a TCP connection, using the standard @value{GDBN} remote serial
-protocol.
-
-@table @emph
-@item On the target machine,
-you need to have a copy of the program you want to debug.
-@code{gdbserver} does not need your program's symbol table, so you can
-strip the program if necessary to save space.  @value{GDBN} on the host
-system does all the symbol handling.
-
-To use the server, you must tell it how to communicate with @value{GDBN};
-the name of your program; and the arguments for your program.  The
-syntax is:
-
-@smallexample
-target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
-@end smallexample
-
-@var{comm} is either a device name (to use a serial line) or a TCP
-hostname and portnumber.  For example, to debug Emacs with the argument
-@samp{foo.txt} and communicate with @value{GDBN} over the serial port
-@file{/dev/com1}:
-
-@smallexample
-target> gdbserver /dev/com1 emacs foo.txt
-@end smallexample
-
-@code{gdbserver} waits passively for the host @value{GDBN} to communicate
-with it.
-
-To use a TCP connection instead of a serial line:
-
-@smallexample
-target> gdbserver host:2345 emacs foo.txt
-@end smallexample
-
-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.
-
-@item On the @value{GDBN} host machine,
-you need an unstripped copy of your program, since @value{GDBN} needs
-symbols and debugging information.  Start up @value{GDBN} as usual,
-using the name of the local copy of your program as the first argument.
-(You may also need the @w{@samp{--baud}} option if the serial line is
-running at anything other than 9600@dmn{bps}.)  After that, use @code{target
-remote} to establish communications with @code{gdbserver}.  Its argument
-is either a device name (usually a serial device, like
-@file{/dev/ttyb}), or a TCP port descriptor in the form
-@code{@var{host}:@var{PORT}}.  For example:
-
-@smallexample
-(@value{GDBP}) target remote /dev/ttyb
-@end smallexample
-
-@noindent
-communicates with the server via serial line @file{/dev/ttyb}, and
-
-@smallexample
-(@value{GDBP}) target remote the-target:2345
-@end smallexample
-
-@noindent
-communicates via a TCP connection to port 2345 on host @w{@file{the-target}}.
-For TCP connections, you must start up @code{gdbserver} prior to using
-the @code{target remote} command.  Otherwise you may get an error whose
-text depends on the host system, but which usually looks something like
-@samp{Connection refused}.
-@end table
-
-@node NetWare
-@subsubsection Using the @code{gdbserve.nlm} program
-
-@kindex gdbserve.nlm
-@code{gdbserve.nlm} is a control program for NetWare systems, which
-allows you to connect your program with a remote @value{GDBN} via
-@code{target remote}.
-
-@value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
-using the standard @value{GDBN} remote serial protocol.
-
-@table @emph
-@item On the target machine,
-you need to have a copy of the program you want to debug.
-@code{gdbserve.nlm} does not need your program's symbol table, so you
-can strip the program if necessary to save space.  @value{GDBN} on the
-host system does all the symbol handling.
-
-To use the server, you must tell it how to communicate with
-@value{GDBN}; the name of your program; and the arguments for your
-program.  The syntax is:
-
-@smallexample
-load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
-              [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
-@end smallexample
-
-@var{board} and @var{port} specify the serial line; @var{baud} specifies
-the baud rate used by the connection.  @var{port} and @var{node} default
-to 0, @var{baud} defaults to 9600@dmn{bps}.
-
-For example, to debug Emacs with the argument @samp{foo.txt}and
-communicate with @value{GDBN} over serial port number 2 or board 1
-using a 19200@dmn{bps} connection:
-
-@smallexample
-load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
-@end smallexample
-
-@item On the @value{GDBN} host machine,
-you need an unstripped copy of your program, since @value{GDBN} needs
-symbols and debugging information.  Start up @value{GDBN} as usual,
-using the name of the local copy of your program as the first argument.
-(You may also need the @w{@samp{--baud}} option if the serial line is
-running at anything other than 9600@dmn{bps}.  After that, use @code{target
-remote} to establish communications with @code{gdbserve.nlm}.  Its
-argument is a device name (usually a serial device, like
-@file{/dev/ttyb}).  For example:
-
-@smallexample
-(@value{GDBP}) target remote /dev/ttyb
-@end smallexample
-
-@noindent
-communications with the server via serial line @file{/dev/ttyb}.
-@end table
-
-@node KOD
-@section Kernel Object Display
-
-@cindex kernel object display
-@cindex kernel object
-@cindex KOD
-
-Some targets support kernel object display.  Using this facility,
-@value{GDBN} communicates specially with the underlying operating system
-and can display information about operating system-level objects such as
-mutexes and other synchronization objects.  Exactly which objects can be
-displayed is determined on a per-OS basis.
-
-Use the @code{set os} command to set the operating system.  This tells
-@value{GDBN} which kernel object display module to initialize:
-
-@example
-(@value{GDBP}) set os cisco
-@end example
-
-If @code{set os} succeeds, @value{GDBN} will display some information
-about the operating system, and will create a new @code{info} command
-which can be used to query the target.  The @code{info} command is named
-after the operating system:
-
-@example
-(@value{GDBP}) info cisco
-List of Cisco Kernel Objects
-Object     Description
-any        Any and all objects
-@end example
-
-Further subcommands can be used to query about particular objects known
-by the kernel.
-
-There is currently no way to determine whether a given operating system
-is supported other than to try it.
-
 
 @node Configurations
 @chapter Configuration-Specific Information