From 4435e1cc6214e6ef44bd90fcde8ae2de9d8be418 Mon Sep 17 00:00:00 2001 From: Tom Tromey Date: Tue, 13 Sep 2016 16:50:34 -0600 Subject: [PATCH] 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 * gdb.texinfo (Packets) : Use "software breakpoint" rather than "memory breakpoint". Further document "kind". Move protocol-details link earlier. : Document the cmd_list argument. Fix typo. : Remove incorrect sentence. (Stop Reply Packets): Document "OK" response to requests when in non-stop mode. : Use "software breakpoint" rather than "memory breakpoint". : Document that "R" is ignored. : Document formatting of "AA". (Notification Packets): Use "%Stop", not "%%Stop". --- gdb/doc/ChangeLog | 15 +++++++++++ gdb/doc/gdb.texinfo | 63 ++++++++++++++++++++++++++------------------- 2 files changed, 51 insertions(+), 27 deletions(-) diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 4fff1dee184..d0b071aaf7a 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,18 @@ +2016-09-28 Tom Tromey + + * gdb.texinfo (Packets) : Use "software breakpoint" rather + than "memory breakpoint". Further document "kind". Move + protocol-details link earlier. + : Document the cmd_list argument. Fix typo. + : Remove incorrect sentence. + (Stop Reply Packets): Document "OK" response to requests when in + non-stop mode. + : Use "software breakpoint" rather than "memory + breakpoint". + : Document that "R" is ignored. + : Document formatting of "AA". + (Notification Packets): Use "%Stop", not "%%Stop". + 2016-09-21 Anton Kolesov * gdb.texinfo (Embedded Processors): Document ARC. diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 4bbe79e417b..099680db596 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -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;} -- 2.30.2