[RFC] Target-defined breakpoints (autoload breakpoints) [2/9] doc of target-defined breakpoints without sync function

[Hui Zhu]

This is the doc for the target-defined breakpoints without sync function.

Thanks,
Hui

2012-10-24  Hui Zhu  <hui_zhu@mentor.com>

	* gdb.texinfo (Setting Breakpoints): Add set breakpoint target-defined.
	(Remote Serial Protocol): Add target-defined breakpoints Format.
-------------- next part --------------
--- a/doc/gdb.texinfo
+++ b/doc/gdb.texinfo
@@ -3805,6 +3805,34 @@ not support breakpoint condition evaluat
 to evaluating all these conditions on the host's side.
 @end table
 
+Prior to @value{GDBN} connects to remote target, some breakpoints might
+have been already set in target, either by a prior @value{GDBN} session or
+by the program itself through some special system API.  When @value{GDBN}
+connects to target, it should handle these existing breakpoints from
+remote target.  We call these breakpoints @dfn{auotload-breakpoints}.
+
+This feature can be controlled via the following commands:
+
+@kindex set breakpoint target-defined
+@kindex show breakpoint target-defined
+@table @code
+@item set breakpoint target-defined query
+If this option is @samp{query} (the default), @value{GDBN} will query the user
+how to handle the target-defined-breakpoints when @value{GDBN} connects to the target.
+
+@item set breakpoint target-defined merge
+If this option is @samp{merge}, the target-defined-breakpoints of both @value{GDBN}
+and of the target will be kept.
+
+@item set breakpoint target-defined gdb
+If this option is @samp{gdb}, the target-defined-breakpoints of target will be removed
+when @value{GDBN} connects to target.
+
+@item set breakpoint target-defined target
+If this option is @samp{target}, the target-defined-breakpoints of @value{GDBN} will
+be removed when @value{GDBN} connects to target.
+@end table
+
 
 @cindex negative breakpoint numbers
 @cindex internal @value{GDBN} breakpoints
@@ -35025,6 +35053,7 @@ Show the current setting of the target w
 * Memory Map Format::
 * Thread List Format::
 * Traceframe Info Format::
+* Target-defined-breakpoints Format::
 @end menu
 
 @node Overview
@@ -39718,6 +39747,77 @@ The formal DTD for the traceframe info f
                         length  CDATA   #REQUIRED>
 @end smallexample
 
+@node Target-defined-breakpoints Format
+@section Target-defined-breakpoints Format
+@cindex target-defined-breakpoints format
+
+@table @samp
+@item qBfP
+@itemx qBsP
+These packets request data in target-defined-breakpoints base format
+about target-defined-breakpoints from the target.
+@value{GDBN} sends @code{qBfP} to get the first piece
+of data, and multiple @code{qTsP} to get additional pieces.
+
+@item @samp{QBDP}:@var{target-defined-breakpoints base format}
+@value{GDBN} uses this packet to control the target-defined-breakpoints in the remote.
+@end table
+
+Target-defined-breakpoints base format describes the operation of
+the target-defined-breakpoints in @value{GDBN} and the target.
+
+@table @samp
+
+@item @var{id}:@var{command}:@var{addr_string}:@var{type}:@var{ignore_num}
+@table @samp
+@item @var{id}
+This is the id in hex string format of the breakpoint to which to
+apply this command.
+0 means all target-defined-breakpoints.
+@item @var{command}
+This is the command character, either @samp{E} (for ``enable'') or
+@samp{D} (for ``disable'').
+If the target-defined-breakpoint @var{id} does not exist, create one and
+enable or disable it.  @value{GDBN} will assume the breakpoint already
+exists and is inserted in the remote, so the target needs to insert
+the breakpoint when it creates it.
+If the target-defined-breakpoint @var{id} does exist, the following items
+will be ignored, and the target-defined-breakpoint will be enabled or
+disabled as specified by @var{command}.
+@item @var{addr_string}
+This is the address of an target-defined-breakpoint to create, encoded
+as a hex string.
+@item @var{type}
+This is the type of the target-defined-breakpoint to create, either
+@samp{H} (for ``hardware'') or @samp{S} (for ``software'').
+@item @var{ignore_num}
+This is the ignore count of the target-defined-breakpoint to create,
+encoded as a hex string.
+@end table
+
+@item @var{id}:R
+This is the remove packet.
+@var{id} is the number of the target-defined-breakpoint that this command
+wants to remove, encoded as a hex string.
+0 means all target-defined-breakpoints.
+When @value{GDBN} or the target get this packet, they will delete
+the target-defined-breakpoint @var{id}.
+
+@item @var{id}:C:@var{cmd_str}
+This packet adds commands in @var{cmd_list} to the command list
+of the target-defined-breakpoint whose number is @var{id}.
+If @var{cmd_str} is empty, the command list will be emptied.
+@var{cmd_str} is encoded as hex string.
+
+@item @var{id}:O:@var{condition_str}
+This packet sets the condition of the target-defined-breakpoint @var{id} to
+be as specified by @var{condition_str}.
+If @var{condition_str} is empty, the target-defined-breakpoint becomes
+unconditional.
+@var{condition_str} is encoded as hex string.
+
+@end table
+
 @include agentexpr.texi
 
 @node Target Descriptions