darlinghq/darling-gdb
1
0
Fork 0
mirror of https://github.com/darlinghq/darling-gdb.git synced 2024-12-01 07:50:49 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

2008-10-24 Sandra Loosemore <sandra@codesourcery.com>

Browse Source 
gdb/doc
	* gdb.texinfo (Remote Protocol): Add new nodes to menu.
	(Overview): Mention notifications and non-stop mode behavior.
	(Packets): Update documentation of ?, vAttach, vCont, and vRun
	with non-stop mode behavior.  Add vStopped description.
	(Stop Reply Packets):  Update list of packets that return
	stop replies.  Mention non-stop behavior.
	(General Query Packets): Document QNonStop packet and associated
	qSupported query response.
	(Interrupts): Clarify multi-threaded behavior.  Mention non-stop
	behavior.
	(Notification Packets): New section.
	(Remote Non-Stop): New section.
	(File-I/O Overview): Mention non-stop behavior.
This commit is contained in:
Sandra Loosemore 2008-10-24 21:04:22 +00:00
parent 74531fed1f
commit 8b23ecc445
2 changed files with 264 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
gdb/doc/ChangeLog
View File

@ -1,3 +1,19 @@
2008-10-24 Sandra Loosemore <sandra@codesourcery.com>
* gdb.texinfo (Remote Protocol): Add new nodes to menu.
(Overview): Mention notifications and non-stop mode behavior.
(Packets): Update documentation of ?, vAttach, vCont, and vRun
with non-stop mode behavior. Add vStopped description.
(Stop Reply Packets): Update list of packets that return
stop replies. Mention non-stop behavior.
(General Query Packets): Document QNonStop packet and associated
qSupported query response.
(Interrupts): Clarify multi-threaded behavior. Mention non-stop
behavior.
(Notification Packets): New section.
(Remote Non-Stop): New section.
(File-I/O Overview): Mention non-stop behavior.
2008-10-24 Hui Zhu <teawater@gmail.com>
Pedro Alves <pedro@codesourcery.com>

270
gdb/doc/gdb.texinfo
View File

@ -24638,6 +24638,8 @@ Show the current setting of the target wait timeout.
* Tracepoint Packets::
* Host I/O Packets::
* Interrupts::
* Notification Packets::
* Remote Non-Stop::
* Packet Acknowledgment::
* Examples::
* File-I/O Remote Protocol Extension::
@ -24659,8 +24661,9 @@ transmitted and received data, respectively.
@cindex protocol, @value{GDBN} remote serial
@cindex serial protocol, @value{GDBN} remote
@cindex remote serial protocol
All @value{GDBN} commands and responses (other than acknowledgments) are
sent as a @var{packet}. A @var{packet} is introduced with the character
All @value{GDBN} commands and responses (other than acknowledgments
and notifications, see @ref{Notification Packets}) are sent as a
@var{packet}. A @var{packet} is introduced with the character
@samp{$}, the actual @var{packet-data}, and the terminating character
@samp{#} followed by a two-digit @var{checksum}:
@ -24706,7 +24709,10 @@ once a connection is established.
The host (@value{GDBN}) sends @var{command}s, and the target (the
debugging stub incorporated in your program) sends a @var{response}. In
the case of step and continue @var{command}s, the response is only sent
when the operation has completed (the target has again stopped).
when the operation has completed, and the target has again stopped all
threads in all attached processes. This is the default all-stop mode
behavior, but the remote protocol also supports @value{GDBN}'s non-stop
execution mode; see @ref{Remote Non-Stop}, for details.
@var{packet-data} consists of a sequence of characters with the
exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
@ -24842,7 +24848,8 @@ The remote target both supports and has enabled extended mode.
@item ?
@cindex @samp{?} packet
Indicate the reason the target halted. The reply is the same as for
step and continue.
step and continue. This packet has a special interpretation when the
target is in non-stop mode; see @ref{Remote Non-Stop}.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
@ -25162,9 +25169,20 @@ up to the first @samp{;} or @samp{?} (or the end of the packet).
@item vAttach;@var{pid}
@cindex @samp{vAttach} packet
Attach to a new process with the specified process ID. @var{pid} is a
hexadecimal integer identifying the process. The attached process is
stopped.
Attach to a new process with the specified process ID @var{pid}.
The process ID is a
hexadecimal integer identifying the process. In all-stop mode, all
threads in the attached process are stopped; in non-stop mode, it may be
attached without being stopped if that is supported by the target.
@c In non-stop mode, on a successful vAttach, the stub should set the
@c current thread to a thread of the newly-attached process. After
@c attaching, GDB queries for the attached process's thread ID with qC.
@c Also note that, from a user perspective, whether or not the
@c target is stopped on attach in non-stop mode depends on whether you
@c use the foreground or background version of the attach command, not
@c on what vAttach does; GDB does the right thing with respect to either
@c stopping or restarting threads.
This packet is only available in extended mode (@pxref{extended mode}).
@ -25173,7 +25191,9 @@ Reply:
@item E @var{nn}
for an error
@item @r{Any stop packet}
for success (@pxref{Stop Reply Packets})
for success in all-stop mode (@pxref{Stop Reply Packets})
@item OK
for success in non-stop mode (@pxref{Remote Non-Stop})
@end table
@item vCont@r{[};@var{action}@r{[}:@var{thread-id}@r{]]}@dots{}
@ -25181,7 +25201,9 @@ for success (@pxref{Stop Reply Packets})
Resume the inferior, specifying different actions for each thread.
If an action is specified with no @var{thread-id}, then it is applied to any
threads that don't have a specific action specified; if no default action is
specified then other threads should remain stopped. Specifying multiple
specified then other threads should remain stopped in all-stop mode and
in their current state in non-stop mode.
Specifying multiple
default actions is an error; specifying no actions is also an error.
Thread IDs are specified using the syntax described in @ref{thread-id syntax}.
@ -25191,16 +25213,29 @@ Currently supported actions are:
@item c
Continue.
@item C @var{sig}
Continue with signal @var{sig}. @var{sig} should be two hex digits.
Continue with signal @var{sig}. The signal @var{sig} should be two hex digits.
@item s
Step.
@item S @var{sig}
Step with signal @var{sig}. @var{sig} should be two hex digits.
Step with signal @var{sig}. The signal @var{sig} should be two hex digits.
@item t
Stop.
@item T @var{sig}
Stop with signal @var{sig}. The signal @var{sig} should be two hex digits.
@end table
The optional @var{addr} argument normally associated with these packets is
The optional argument @var{addr} normally associated with the
@samp{c}, @samp{C}, @samp{s}, and @samp{S} packets is
not supported in @samp{vCont}.
The @samp{t} and @samp{T} actions are only relevant in non-stop mode
(@pxref{Remote Non-Stop}) and may be ignored by the stub otherwise.
A stop reply should be generated for any affected thread not already stopped.
When a thread is stopped by means of a @samp{t} action,
the corresponding stop reply should indicate that the thread has stopped with
signal @samp{0}, regardless of whether the target uses some other signal
as an implementation detail.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
@ -25303,6 +25338,8 @@ command line. The file and arguments are hex-encoded strings. If
(e.g.@: the last program run). The program is created in the stopped
state.
@c FIXME: What about non-stop mode?
This packet is only available in extended mode (@pxref{extended mode}).
Reply:
@ -25313,6 +25350,21 @@ for an error
for success (@pxref{Stop Reply Packets})
@end table
@item vStopped
@anchor{vStopped packet}
@cindex @samp{vStopped} packet
In non-stop mode (@pxref{Remote Non-Stop}), acknowledge a previous stop
reply and prompt for the stub to report another one.
Reply:
@table @samp
@item @r{Any stop packet}
if there is another unreported stop event (@pxref{Stop Reply Packets})
@item OK
if there are no unreported stop events
@end table
@item X @var{addr},@var{length}:@var{XX@dots{}}
@anchor{X packet}
@cindex @samp{X} packet
@ -25452,9 +25504,10 @@ for an error
@section Stop Reply Packets
@cindex stop reply packets
The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can
receive any of the below as a reply. In the case of the @samp{C},
@samp{c}, @samp{S} and @samp{s} packets, that reply is only returned
The @samp{C}, @samp{c}, @samp{S}, @samp{s}, @samp{vCont},
@samp{vAttach}, @samp{vRun}, @samp{vStopped}, and @samp{?} packets can
receive any of the below as a reply. Except for @samp{?}
and @samp{vStopped}, that reply is only returned
when the target halts. In the below the exact meaning of @dfn{signal
number} is defined by the header @file{include/gdb/signals.h} in the
@value{GDBN} source code.
@ -25552,7 +25605,7 @@ extensions}. The @var{pid} is formatted as a big-endian hex string.
@samp{@var{XX}@dots{}} is hex encoding of @sc{ascii} data, to be
written as the program's console output. This can happen at any time
while the program is running and the debugger should continue to wait
for @samp{W}, @samp{T}, etc.
for @samp{W}, @samp{T}, etc. This reply is not permitted in non-stop mode.
@item F @var{call-id},@var{parameter}@dots{}
@var{call-id} is the identifier which says which host system call should
@ -25777,6 +25830,32 @@ Don't use this packet; use the @samp{qThreadExtraInfo} query instead
Reply: see @code{remote.c:remote_unpack_thread_info_response()}.
@item QNonStop:1
@item QNonStop:0
@cindex non-stop mode, remote request
@cindex @samp{QNonStop} packet
@anchor{QNonStop}
Enter non-stop (@samp{QNonStop:1}) or all-stop (@samp{QNonStop:0}) mode.
@xref{Remote Non-Stop}, for more information.
Reply:
@table @samp
@item OK
The request succeeded.
@item E @var{nn}
An error occurred. @var{nn} are hex digits.
@item
An empty reply indicates that @samp{QNonStop} is not supported by
the stub.
@end table
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
Use of this packet is controlled by the @code{set non-stop} command;
@pxref{Non-Stop Mode}.
@item QPassSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{}
@cindex pass signals to inferior, remote request
@cindex @samp{QPassSignals} packet
@ -26019,6 +26098,11 @@ These are the currently defined stub features and their properties:
@tab @samp{-}
@tab Yes
@item @samp{QNonStop}
@tab No
@tab @samp{-}
@tab Yes
@item @samp{QPassSignals}
@tab No
@tab @samp{-}
@ -26074,6 +26158,10 @@ The remote stub understands the @samp{qXfer:spu:read} packet
The remote stub understands the @samp{qXfer:spu:write} packet
(@pxref{qXfer spu write}).
@item QNonStop
The remote stub understands the @samp{QNonStop} packet
(@pxref{QNonStop}).
@item QPassSignals
The remote stub understands the @samp{QPassSignals} packet
(@pxref{QPassSignals}).
@ -26635,11 +26723,148 @@ and does @emph{not} represent an interrupt. E.g., an @samp{X} packet
Stubs are not required to recognize these interrupt mechanisms and the
precise meaning associated with receipt of the interrupt is
implementation defined. If the stub is successful at interrupting the
running program, it is expected that it will send one of the Stop
Reply Packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result
of successfully stopping the program. Interrupts received while the
program is stopped will be discarded.
implementation defined. If the target supports debugging of multiple
threads and/or processes, it should attempt to interrupt all
currently-executing threads and processes.
If the stub is successful at interrupting the
running program, it should send one of the stop
reply packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result
of successfully stopping the program in all-stop mode, and a stop reply
for each stopped thread in non-stop mode.
Interrupts received while the
program is stopped are discarded.
@node Notification Packets
@section Notification Packets
@cindex notification packets
@cindex packets, notification
The @value{GDBN} remote serial protocol includes @dfn{notifications},
packets that require no acknowledgment. Both the GDB and the stub
may send notifications (although the only notifications defined at
present are sent by the stub). Notifications carry information
without incurring the round-trip latency of an acknowledgment, and so
are useful for low-impact communications where occasional packet loss
is not a problem.
A notification packet has the form @samp{% @var{data} #
@var{checksum}}, where @var{data} is the content of the notification,
and @var{checksum} is a checksum of @var{data}, computed and formatted
as for ordinary @value{GDBN} packets. A notification's @var{data}
never contains @samp{$}, @samp{%} or @samp{#} characters. Upon
receiving a notification, the recipient sends no @samp{+} or @samp{-}
to acknowledge the notification's receipt or to report its corruption.
Every notification's @var{data} begins with a name, which contains no
colon characters, followed by a colon character.
Recipients should silently ignore corrupted notifications and
notifications they do not understand. Recipients should restart
timeout periods on receipt of a well-formed notification, whether or
not they understand it.
Senders should only send the notifications described here when this
protocol description specifies that they are permitted. In the
future, we may extend the protocol to permit existing notifications in
new contexts; this rule helps older senders avoid confusing newer
recipients.
(Older versions of @value{GDBN} ignore bytes received until they see
the @samp{$} byte that begins an ordinary packet, so new stubs may
transmit notifications without fear of confusing older clients. There
are no notifications defined for @value{GDBN} to send at the moment, but we
assume that most older stubs would ignore them, as well.)
The following notification packets from the stub to @value{GDBN} are
defined:
@table @samp
@item Stop: @var{reply}
Report an asynchronous stop event in non-stop mode.
The @var{reply} has the form of a stop reply, as
described in @ref{Stop Reply Packets}. Refer to @ref{Remote Non-Stop},
for information on how these notifications are acknowledged by
@value{GDBN}.
@end table
@node Remote Non-Stop
@section Remote Protocol Support for Non-Stop Mode
@value{GDBN}'s remote protocol supports non-stop debugging of
multi-threaded programs, as described in @ref{Non-Stop Mode}. If the stub
supports non-stop mode, it should report that to @value{GDBN} by including
@samp{QNonStop+} in its @samp{qSupported} response (@pxref{qSupported}).
@value{GDBN} typically sends a @samp{QNonStop} packet only when
establishing a new connection with the stub. Entering non-stop mode
does not alter the state of any currently-running threads, but targets
must stop all threads in any already-attached processes when entering
all-stop mode. @value{GDBN} uses the @samp{?} packet as necessary to
probe the target state after a mode change.
In non-stop mode, when an attached process encounters an event that
would otherwise be reported with a stop reply, it uses the
asynchronous notification mechanism (@pxref{Notification Packets}) to
inform @value{GDBN}. In contrast to all-stop mode, where all threads
in all processes are stopped when a stop reply is sent, in non-stop
mode only the thread reporting the stop event is stopped. That is,
when reporting a @samp{S} or @samp{T} response to indicate completion
of a step operation, hitting a breakpoint, or a fault, only the
affected thread is stopped; any other still-running threads continue
to run. When reporting a @samp{W} or @samp{X} response, all running
threads belonging to other attached processes continue to run.
Only one stop reply notification at a time may be pending; if
additional stop events occur before @value{GDBN} has acknowledged the
previous notification, they must be queued by the stub for later
synchronous transmission in response to @samp{vStopped} packets from
@value{GDBN}. Because the notification mechanism is unreliable,
the stub is permitted to resend a stop reply notification
if it believes @value{GDBN} may not have received it. @value{GDBN}
ignores additional stop reply notifications received before it has
finished processing a previous notification and the stub has completed
sending any queued stop events.
Otherwise, @value{GDBN} must be prepared to receive a stop reply
notification at any time. Specifically, they may appear when
@value{GDBN} is not otherwise reading input from the stub, or when
@value{GDBN} is expecting to read a normal synchronous response or a
@samp{+}/@samp{-} acknowledgment to a packet it has sent.
Notification packets are distinct from any other communication from
the stub so there is no ambiguity.
After receiving a stop reply notification, @value{GDBN} shall
acknowledge it by sending a @samp{vStopped} packet (@pxref{vStopped packet})
as a regular, synchronous request to the stub. Such acknowledgment
is not required to happen immediately, as @value{GDBN} is permitted to
send other, unrelated packets to the stub first, which the stub should
process normally.
Upon receiving a @samp{vStopped} packet, if the stub has other queued
stop events to report to @value{GDBN}, it shall respond by sending a
normal stop reply response. @value{GDBN} shall then send another
@samp{vStopped} packet to solicit further responses; again, it is
permitted to send other, unrelated packets as well which the stub
should process normally.
If the stub receives a @samp{vStopped} packet and there are no
additional stop events to report, the stub shall return an @samp{OK}
response. At this point, if further stop events occur, the stub shall
send a new stop reply notification, @value{GDBN} shall accept the
notification, and the process shall be repeated.
In non-stop mode, the target shall respond to the @samp{?} packet as
follows. First, any incomplete stop reply notification/@samp{vStopped}
sequence in progress is abandoned. The target must begin a new
sequence reporting stop events for all stopped threads, whether or not
it has previously reported those events to @value{GDBN}. The first
stop reply is sent as a synchronous reply to the @samp{?} packet, and
subsequent stop replies are sent as responses to @samp{vStopped} packets
using the mechanism described above. The target must not send
asynchronous stop reply notifications until the sequence is complete.
If all threads are running when the target receives the @samp{?} packet,
or if the target is not attached to any process, it shall respond
@samp{OK}.
@node Packet Acknowledgment
@section Packet Acknowledgment
@ -26684,7 +26909,6 @@ new connection is established,
there is also no protocol request to re-enable the acknowledgments
for the current connection, once disabled.
@node Examples
@section Examples
@ -26779,6 +27003,8 @@ the host file system. Character or block special devices, pipes,
named pipes, sockets or any other communication method on the host
system are not supported by this protocol.
File I/O is not supported in non-stop mode.
@node Protocol Basics
@subsection Protocol Basics
@cindex protocol basics, file-i/o