Small improvements to the remote protocol manual
I was reading the gdb RSP manual recently and I found a number of small problems in the documentation. This patch attempts to improve these areas. Specfically: * The term "memory breakpoint" is used only in this section of the manual, and there inconsistently. I found this term confusing -- initially I thought it might be a watchpoint. This patch changes it to use the term "software breakpoint", which is used in the rest of the manual. * The z0 packet didn't document how "kind" was written. And, it had a stray link to the architecture-specific protocol details node. This patch moves this link to a better spot. * The z1 patch didn't document that it accepts cmd_list. * I couldn't find any text saying what response is given to a command like vCont in non-stop mode. The answer is that OK is sent, and then a stop reply is sent as a notification. This patch adds a note about this. * The "create" stop reply did not document that the "R" argument is ignored. * The "W", "X", and "w" packets did not document how the "AA" part is formatted. * The %Stop notification example said "%%Stop", but I think this is incorrect. 2016-09-28 Tom Tromey <tom@tromey.com> * gdb.texinfo (Packets) <z0>: Use "software breakpoint" rather than "memory breakpoint". Further document "kind". Move protocol-details link earlier. <z1>: Document the cmd_list argument. Fix typo. <g>: Remove incorrect sentence. (Stop Reply Packets): Document "OK" response to requests when in non-stop mode. <swbreak>: Use "software breakpoint" rather than "memory breakpoint". <create>: Document that "R" is ignored. <W, X, w>: Document formatting of "AA". (Notification Packets): Use "%Stop", not "%%Stop".
This commit is contained in:
parent
9eaff86138
commit
4435e1cc62
|
@ -1,3 +1,18 @@
|
|||
2016-09-28 Tom Tromey <tom@tromey.com>
|
||||
|
||||
* gdb.texinfo (Packets) <z0>: Use "software breakpoint" rather
|
||||
than "memory breakpoint". Further document "kind". Move
|
||||
protocol-details link earlier.
|
||||
<z1>: Document the cmd_list argument. Fix typo.
|
||||
<g>: Remove incorrect sentence.
|
||||
(Stop Reply Packets): Document "OK" response to requests when in
|
||||
non-stop mode.
|
||||
<swbreak>: Use "software breakpoint" rather than "memory
|
||||
breakpoint".
|
||||
<create>: Document that "R" is ignored.
|
||||
<W, X, w>: Document formatting of "AA".
|
||||
(Notification Packets): Use "%Stop", not "%%Stop".
|
||||
|
||||
2016-09-21 Anton Kolesov <anton.kolesov@synopsys.com>
|
||||
|
||||
* gdb.texinfo (Embedded Processors): Document ARC.
|
||||
|
|
|
@ -35250,8 +35250,7 @@ Each byte of register data is described by two hex digits. The bytes
|
|||
with the register are transmitted in target byte order. The size of
|
||||
each register and their position within the @samp{g} packet are
|
||||
determined by the @value{GDBN} internal gdbarch functions
|
||||
@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{gdbarch_register_name}. The
|
||||
specification of several standard @samp{g} packets is specified below.
|
||||
@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{gdbarch_register_name}.
|
||||
|
||||
When reading registers from a trace frame (@pxref{Analyze Collected
|
||||
Data,,Using the Collected Data}), the stub may also return a string of
|
||||
|
@ -35748,22 +35747,25 @@ be implemented in an idempotent way.}
|
|||
@itemx Z0,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}@r{[};cmds:@var{persist},@var{cmd_list}@dots{}@r{]}
|
||||
@cindex @samp{z0} packet
|
||||
@cindex @samp{Z0} packet
|
||||
Insert (@samp{Z0}) or remove (@samp{z0}) a memory breakpoint at address
|
||||
Insert (@samp{Z0}) or remove (@samp{z0}) a software breakpoint at address
|
||||
@var{addr} of type @var{kind}.
|
||||
|
||||
A memory breakpoint is implemented by replacing the instruction at
|
||||
A software breakpoint is implemented by replacing the instruction at
|
||||
@var{addr} with a software breakpoint or trap instruction. The
|
||||
@var{kind} is target-specific and typically indicates the size of
|
||||
the breakpoint in bytes that should be inserted. E.g., the @sc{arm}
|
||||
and @sc{mips} can insert either a 2 or 4 byte breakpoint. Some
|
||||
architectures have additional meanings for @var{kind};
|
||||
@var{cond_list} is an optional list of conditional expressions in bytecode
|
||||
form that should be evaluated on the target's side. These are the
|
||||
conditions that should be taken into consideration when deciding if
|
||||
the breakpoint trigger should be reported back to @var{GDBN}.
|
||||
@var{kind} is target-specific and typically indicates the size of the
|
||||
breakpoint in bytes that should be inserted. E.g., the @sc{arm} and
|
||||
@sc{mips} can insert either a 2 or 4 byte breakpoint. Some
|
||||
architectures have additional meanings for @var{kind}
|
||||
(@pxref{Architecture-Specific Protocol Details}); if no
|
||||
architecture-specific value is being used, it should be @samp{0}.
|
||||
@var{kind} is hex-encoded. @var{cond_list} is an optional list of
|
||||
conditional expressions in bytecode form that should be evaluated on
|
||||
the target's side. These are the conditions that should be taken into
|
||||
consideration when deciding if the breakpoint trigger should be
|
||||
reported back to @value{GDBN}.
|
||||
|
||||
See also the @samp{swbreak} stop reason (@pxref{swbreak stop reason})
|
||||
for how to best report a memory breakpoint event to @value{GDBN}.
|
||||
for how to best report a software breakpoint event to @value{GDBN}.
|
||||
|
||||
The @var{cond_list} parameter is comprised of a series of expressions,
|
||||
concatenated without separators. Each expression has the following form:
|
||||
|
@ -35792,10 +35794,8 @@ actual conditional expression in bytecode form.
|
|||
|
||||
@end table
|
||||
|
||||
see @ref{Architecture-Specific Protocol Details}.
|
||||
|
||||
@emph{Implementation note: It is possible for a target to copy or move
|
||||
code that contains memory breakpoints (e.g., when implementing
|
||||
code that contains software breakpoints (e.g., when implementing
|
||||
overlays). The behavior of this packet, in the presence of such a
|
||||
target, is not defined.}
|
||||
|
||||
|
@ -35810,15 +35810,16 @@ for an error
|
|||
@end table
|
||||
|
||||
@item z1,@var{addr},@var{kind}
|
||||
@itemx Z1,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}
|
||||
@itemx Z1,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}@r{[};cmds:@var{persist},@var{cmd_list}@dots{}@r{]}
|
||||
@cindex @samp{z1} packet
|
||||
@cindex @samp{Z1} packet
|
||||
Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at
|
||||
address @var{addr}.
|
||||
|
||||
A hardware breakpoint is implemented using a mechanism that is not
|
||||
dependant on being able to modify the target's memory. The @var{kind}
|
||||
and @var{cond_list} have the same meaning as in @samp{Z0} packets.
|
||||
dependent on being able to modify the target's memory. The
|
||||
@var{kind}, @var{cond_list}, and @var{cmd_list} arguments have the
|
||||
same meaning as in @samp{Z0} packets.
|
||||
|
||||
@emph{Implementation note: A hardware breakpoint is not affected by code
|
||||
movement.}
|
||||
|
@ -35898,6 +35899,10 @@ 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.
|
||||
|
||||
In non-stop mode, the server will simply reply @samp{OK} to commands
|
||||
such as @samp{vCont}; any stop will be the subject of a future
|
||||
notification. @xref{Remote Non-Stop}.
|
||||
|
||||
As in the description of request packets, we include spaces in the
|
||||
reply templates for clarity; these are not part of the reply packet's
|
||||
syntax. No @value{GDBN} stop reply packet uses spaces to separate its
|
||||
|
@ -35976,7 +35981,7 @@ for more information.
|
|||
|
||||
@item swbreak
|
||||
@anchor{swbreak stop reason}
|
||||
The packet indicates a memory breakpoint instruction was executed,
|
||||
The packet indicates a software breakpoint instruction was executed,
|
||||
irrespective of whether it was @value{GDBN} that planted the
|
||||
breakpoint or the breakpoint is hardcoded in the program. The @var{r}
|
||||
part must be left empty.
|
||||
|
@ -36063,7 +36068,8 @@ The packet indicates that the thread was just created. The new thread
|
|||
is stopped until @value{GDBN} sets it running with a resumption packet
|
||||
(@pxref{vCont packet}). This packet should not be sent by default;
|
||||
@value{GDBN} requests it with the @ref{QThreadEvents} packet. See
|
||||
also the @samp{w} (@ref{thread exit event}) remote reply below.
|
||||
also the @samp{w} (@pxref{thread exit event}) remote reply below. The
|
||||
@var{r} part is ignored.
|
||||
|
||||
@end table
|
||||
|
||||
|
@ -36072,10 +36078,11 @@ also the @samp{w} (@ref{thread exit event}) remote reply below.
|
|||
The process exited, and @var{AA} is the exit status. This is only
|
||||
applicable to certain targets.
|
||||
|
||||
The second form of the response, including the process ID of the exited
|
||||
process, can be used only when @value{GDBN} has reported support for
|
||||
multiprocess protocol extensions; see @ref{multiprocess extensions}.
|
||||
The @var{pid} is formatted as a big-endian hex string.
|
||||
The second form of the response, including the process ID of the
|
||||
exited process, can be used only when @value{GDBN} has reported
|
||||
support for multiprocess protocol extensions; see @ref{multiprocess
|
||||
extensions}. Both @var{AA} and @var{pid} are formatted as big-endian
|
||||
hex strings.
|
||||
|
||||
@item X @var{AA}
|
||||
@itemx X @var{AA} ; process:@var{pid}
|
||||
|
@ -36084,7 +36091,8 @@ The process terminated with signal @var{AA}.
|
|||
The second form of the response, including the process ID of the
|
||||
terminated process, can be used only when @value{GDBN} has reported
|
||||
support for multiprocess protocol extensions; see @ref{multiprocess
|
||||
extensions}. The @var{pid} is formatted as a big-endian hex string.
|
||||
extensions}. Both @var{AA} and @var{pid} are formatted as big-endian
|
||||
hex strings.
|
||||
|
||||
@anchor{thread exit event}
|
||||
@cindex thread exit event, remote reply
|
||||
|
@ -36093,6 +36101,7 @@ extensions}. The @var{pid} is formatted as a big-endian hex string.
|
|||
The thread exited, and @var{AA} is the exit status. This response
|
||||
should not be sent by default; @value{GDBN} requests it with the
|
||||
@ref{QThreadEvents} packet. See also @ref{thread create event} above.
|
||||
@var{AA} is formatted as a big-endian hex string.
|
||||
|
||||
@item N
|
||||
There are no resumed threads left in the target. In other words, even
|
||||
|
@ -38664,7 +38673,7 @@ the process shall be repeated.
|
|||
The process of asynchronous notification can be illustrated by the
|
||||
following example:
|
||||
@smallexample
|
||||
<- @code{%%Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;}
|
||||
<- @code{%Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;}
|
||||
@code{...}
|
||||
-> @code{vStopped}
|
||||
<- @code{T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;}
|
||||
|
|
Loading…
Reference in New Issue