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".

1 files changed, 36 insertions, 27 deletions

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 4bbe79e..099680d 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;}