Re: [PATCH] target attributes [5/5] doc

[Hui Zhu <teawater@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 16829 bytes --]

Oops.  I am so sorry that I post a old version of this patch.  So
sorry about that.
The attachment is the right version.  Please help me with it.

Thanks,
Hui

On Sat, Sep 1, 2012 at 3:24 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Wed, 29 Aug 2012 16:12:20 +0800
>> From: Hui Zhu <hui_zhu@mentor.com>
>>
>> This patch add doc about target attributes in the doc.
>
> Thanks.
>
>> +If @var{n} is the number of trace state variable, Push the value of
>                             ^^^^^^^^^^^^^^^^^^^^^^^
> "of a trace state variable".  Also, "push", with a lower-case 'p'.
>
>> +If @var{n} is the id of target attribute, push the value of target
>> +attribute @var{n} and do the type convert according the type of
>> +target attribute @var{n} and the stack type.
>
>   If @var{n} is the id of a target attribute, push the value of that
>   attribute after converting the type of the attribute according to
>   the stack type.
>
> I have a question: what does it mean for a number N to be "the id of
> an attribute"?  Obviously, some context is missing here, because I
> fail to understand how a number can identify an attribute.
>
>>  @item @code{setv} (0x2d) @var{n}: @result{} @var{v}
>> -Set trace state variable number @var{n} to the value found on the top
>> +If @var{n} is the number of trace state variable, set trace state
>> +variable number @var{n} to the value found on the top
>>  of the stack.  The stack is unchanged, so that the value is readily
>
> I don't understand the reason for the change.  The new text seems to
> say the same as the old one (and the old one was more clear).
>
>> +If @var{n} is the id of target attribute, do the type convert according
>> +the type of target attribute @var{n} and the stack type, set to
>> +target attribute @var{n}.
>
> If you leave the old text, this addition will be unnecessary.
>
> If you want to point out that the value at stack top can identify a
> trace variable or an attribute, then just say so:
>
>   The value at stack top can identify either a trace variable or an
>   attribute.
>
>> +@kindex maint load-target-attributes
>> +@item maint load-target-attributes @var{filename}
>> +Load @ref{Target Attributes} from a XML file.
>> +
>> +@kindex maint clear-target-attributes
>> +@item maint clear-target-attributes
>> +Remove all @ref{Target Attributes}.
>
> Why is this command needed?  Shouldn't GDB load the attributes
> automatically?
>
>> +The value of the variable is @var{value}.  This will be unlongest value
>                                                            ^^^^^^^^^
> I believe you meant "ulongest".
>
> Also, I don't think we mention "ulongest" anywhere else in the
> manual.  Would it be good enough to use "unsigned integer" instead?
>
>> +that is convert from the current value of the target attribute.
>            ^^^^^^^
> "converted"
>
>> +Or hardware register of this target attribute is busy that cannot
>> +access.
>
> This is not a sentence.  I believe you meant something like this:
>
>   This would occur, for example, if the user is examining a trace
>   frame in which the requested target attribute was not collected, or
>   if the hardware register holding this target attribute is busy and
>   cannot be accessed.
>
>> +Set unlongest value that is convert from the value that want set to
>        ^^^^^^^^^               ^^^^^^^
>> +target attribute to target attribute @var{var}.
>
> Same typos; and see the comments above about "ulongest".
>
> Also, "that want set to target attribute to target attribute" is not
> correct English.  What did you want to say there?
>
>> +Some of @value{GDBN} target have some special attributes that can be
>> +access.
>    ^^^^^^
> "accessed"
>
>> +@value{GDBN} can access target attributes directly or through agent
>> +code that running in target.
>         ^^^^^^^^^^^^
> "that is running"
>
>> +A target attributes will include name, id, type, access mode,
>> +the breakpoint type that it support, the breakpoint address that
>> +it support.
>
> This needs to be rephrased, but I need to understand what you meant
> first.  I can understand about the name, ID, type, and access mode.
> But what does "the breakpoint type that it supports" mean?  Same
> question about "the breakpoint address that it supports".  What are
> these about?
>
> Based on the example you provide further down, I'm guessing that the
> former is a series of YES/NO values for the various breakpoint types
> we have in GDB, where YES means that kind of breakpoint is supported.
> While the latter gives the ranges of addresses for this attribute.
> But I still don't understand the semantics: what does it mean to say
> that attribute 'foo' "supports software-breakpoint", and what do the
> address ranges mean?
>
>> +@menu
>> +* Retrieving Target Attributes::     How target attributes are fetched from a target.
>> +* Format of Target Attributes::              The contents of a target attributes list.
>> +* Access Target Attributes::         Access target attributes.
>> +* Example of Target Attributes::     Example of target attributes in gdbserver.
>> +@end menu
>
> This menu is malformed.  Please format it like we do with other menus
> in the manual, including alignment and line length.
>
>> +Target attributes can be read from the target automatically.
>> +The default behavior is to read the attributes from the target.
>
> Does the second sentence mean that automatic reading is the default?
> Or does it mean something else?
>
>> +@value{GDBN} retrieves it via the remote protocol using
>                           ^^
> "the attributes" ("it" is just one thing, not many).
>
>> +                                         The contents of it are
>> +an XML document, of the form described in
>> +@ref{Format of Target Attributes}.
>
> I would rephrase:
>
>   The attributes are received in the form of an XML document described
>   in @ref{Format of Target Attributes}.
>
>> +Here is a simple target attributes list that include two target
>> +attributes ``foo'' and ``bar'':
>
> Please use @samp instead of ``...''.
>
>> +@smallexample
>> +<target-attributes>
>> +     <target-attribute name="foo" id="1" type="int8" >
>> +             <access>
>> +                     <agent read="yes" write="no"/>
>> +                     <gdb write="yes" read="yes"/>
>> +             </access>
>> +             <support software-breakpoint="yes" hardware-breakpoint="yes" hardware-watchpoint="yes" tracepoint="yes"/>
>
> This line is too long, please break it into 2.
>
>> +     </target-attribute>
>> +     <target-attribute name="bar" id="2" type="int32" target-only-cond-check="yes">
>
> Likewise.
>
>> +             <support software-breakpoint="yes" hardware-breakpoint="yes" tracepoint="yes"/>
>
> Likewise.
>
>> +This define the @samp{name}, @samp{id} , @samp{type}
>         ^^^^^^
> "defines"
>
>> +and @samp{target-only-cond-check} of a target attribute.
>
> What is target-only-cond-check?  It was never mentioned before.
>
> I think this whole sentence should be removed, it doesn't add anything
> to the XML fragment you show.
>
>> +If @samp{target-only-cond-check} set to @samp{yes}, GDB will not check the
>                                                        ^^^
> @value{GDBN}
>
>> +                                      If @samp{target-only-cond-check} not
>> +define, it means @samp{no}.
>
>   If @samp{target-only-cond-check} is not defines, it defaults to
>   @samp{no}.
>
>> +@smallexample
>> +<target-attribute name="foo" id="1" type="int8" >
>> +@end smallexample
>
> What does this example show?
>
>> +This define the agent access mode of a target attribute.
>         ^^^^^^
> "defines"
>
> Also, please have a ":" at the end of this sentence, to indicate that
> the explanation refers to the next example.
>
>> +If @samp{read} or @samp{write} not define, it means @samp{no}.
>
> This sentence should follow the example.  Please rephrase it:
>
>   If neither @samp{read} nor @samp{write} are defined, they both
>   default to @samp{no}.
>
>> +This define the GDB access mode of a target attribute.
>                    ^^^
> @value{GDBN}.
>
> Also, please make the same changes as for the agent access mode.
>
>> +If @samp{read} or @samp{write} not define, it means @samp{no}.
>> +@smallexample
>> +<gdb write="yes" read="yes"/>
>> +@end smallexample
>
> Likewise.
>
>> +This define the breakpoint type that a target attribute can be used in
>> +the condition or commands of these type breakpoints.
>> +If a type is not defined, it means @samp{no}.
>> +@smallexample
>> +<support software-breakpoint="yes" hardware-breakpoint="yes" hardware-watchpoint="yes" tracepoint="yes"/>
>> +@end smallexample
>> +
>> +This define the breakpoint address range that a target attribute can be used
>> +in the condition or commands of the breakpoints that inside this address range.
>
> As I mentioned above, this business with breakpoint support is
> unclear.  What does it mean to "use an attribute in the condition or
> commands for the breakpoint"?
>
>> +If not define any address, this target attribute support any address.
>
> This seems to be contrary to the other defaults, which are
> restrictive, while this one is permissive.  Why the difference?
>
>> +@node Access Target Attributes
>> +@section Access Target Attributes
>> +@cindex access target attributes
>
> Please use "target attribute access" instead.
>
>> +@item info target-attributes
>> +Status of target attributes.
>> +
>> +@item Access target attributes in agent code.
>> +Target attributes can be accessed in breakpoint condition and actions.
>> +
>> +@item Access target attributes in GDB.
>> +Target attributes can be accessed in print commands and expressions as
>> +if they were convenience variables.
>> +
>> +@end table
>
> Sorry, I don't understand this description.  Are you describing some
> kind of display of target attributes?  If so, an example would help a
> lot.
>
>> +@node Example of Target Attributes
>> +@section Example of Target Attributes
>> +@cindex example of target attributes
>
> The rest of the text seems to indicate that this is not an example,
> but an optional feature.
>
>> +Gdbserver include target attributes to count how many times does each
>> +breakpoint pass.
>> +
>> +This function will not be built in default.  To build it with gdbsrver,
>> +need add @code{--enable-break-count} in the config command.
>> +
>> +Gdbserver include three target attributes:
>> +
>> +@table @samp
>> +
>> +@item $break_count_on
>> +This is the switch of the breakpoints pass count function.
>> +The default value of it is 0, the breakpoints pass count function is closed.
>> +If it is set to 1, function is opened and the count value of all
>> +the breakpoints will reset to 0 when inferior stop and continue again.
>> +If it is set to 2, function is opened and the count value will not be reset.
>> +
>> +@item $break_count_select
>> +When count function is opened, set the address of breakpoint to
>> +$break_count_select to select which count value you want to access
>> +in $break_count_val.
>> +
>> +@ $break_count_val
>> +It will return the value of a breakpoint pass count if access it from GDB.
>> +When access it inside the condition of a breakpoint, its value is the value
>> +of this breakpoint pass count.
>> +
>> +@end table
>> +
>> +Following example show how to use breakpoints pass count function in condition:
>> +
>> +@smallexample
>> +(gdb) target remote :1234
>> +Remote debugging using :1234
>> +Reading symbols from /lib64/ld-linux-x86-64.so.2...(no debugging symbols found)...done.
>> +Loaded symbols for /lib64/ld-linux-x86-64.so.2
>> +0x00007ffff7ddb6b0 in ?? () from /lib64/ld-linux-x86-64.so.2
>> +(gdb) list
>> +1    int
>> +2    main()
>> +3    @{
>> +4      int   a = 1;
>> +5
>> +6      while (1)
>> +7        printf("%d\n", a++);
>> +8    @}
>> +(gdb) set $break_count_on=1
>> +(gdb) b 7
>> +Breakpoint 1 at 0x400503: file 1.c, line 7.
>> +(gdb) condition 1 ($break_count_val == 10)
>> +(gdb) c
>> +Continuing.
>> +
>> +Breakpoint 1, main () at 1.c:7
>> +7        printf("%d\n", a++);
>> +
>> +In gdbserver part, you can see that:
>> +Process /home/teawater/tmp/a.out created; pid = 7937
>> +Listening on port 1234
>> +Remote debugging from host 127.0.0.1
>> +Found breakpoint condition.
>> +Found breakpoint condition.
>> +Found breakpoint condition.
>> +1
>> +2
>> +3
>> +4
>> +5
>> +6
>> +7
>> +8
>> +9
>> +@end smallexample
>> +
>> +Following example show how to use breakpoints pass count show a address
>> +passed times:
>> +
>> +@smallexample
>> +(gdb) set non-stop on
>> +(gdb) set target-async on
>> +(gdb) target remote :1234
>> +Remote debugging using :1234
>> +[New Thread 7944]
>> +(gdb)
>> +[Thread 7944] #1 stopped.
>> +0x00007ffff7ddb6b0 in ?? ()
>> +set $break_count_on=2
>> +(gdb) list
>> +1    int
>> +2    main()
>> +3    @{
>> +4      int   a = 1;
>> +5
>> +6      while (1)
>> +7        printf("%d\n", a++);
>> +8    @}
>> +(gdb) b 7
>> +Breakpoint 1 at 0x400503: file 1.c, line 7.
>> +(gdb) condition 1 ($break_count_val == 0)
>> +(gdb) c&
>> +Continuing.
>> +(gdb) p $break_count_val
>> +$1 = 96965
>> +(gdb) p $break_count_val
>> +$2 = 148548
>> +@end smallexample
>> +
>>  @node Operating System Information
>>  @appendix Operating System Information
>>  @cindex operating system information
>
> I rephrased all this as below:
>
>   Gdbserver includes an optional feature that uses target attributes
>   in order to count how many times does each breakpoint is hit.
>
>   This feature will not be built by default.  To build it with gdbsrver,
>   you need to use the @option{--enable-break-count} option to the
>   @command{configure} script.
>
>   When built with this feature, gdbserver will support three target
>   attributes:
>
>   @table @samp
>
>   @item $break_count_on
>   This attribute activates and deactivates the breakpoints pass-count feature.
>   Its default value is 0, which means the breakpoints pass-count
>   feature is inactive.
>   If $break_count_on is set to 1, the feature is active.  The count
>   value of every breakpoint will be reset to 0 when the inferior stops.
>   If $break_count_on is set to 2, the feature is active, but the count
>   value will not be reset when the inferior stops.
>
> My comments are that using 0, 1, and 2 for $break_count_on is not very
> helpful; better use some more mnemonic values.
>
>   @item $break_count_select
>   When the pass-count feature is active, set the address of breakpoint to
>   $break_count_select to select which count value you want to access
>   in $break_count_val.
>
> Not clear, please elaborate or give an example.
>
>   @item $break_count_val
>   This attribute holds the value of a breakpoint pass-count.  It is
>   useful for accessing the value it from @value{GDBN}.
>   When access is from inside the condition of a breakpoint, its value
>   is the pass-count of this breakpoint.
>   @end table
>
>   The following example shows how to use breakpoints pass-count
>   in conditions:
>
>   @smallexample
>   (gdb) target remote :1234
>   Remote debugging using :1234
>   Reading symbols from /lib64/ld-linux-x86-64.so.2...(no debugging symbols found)...done.
>   Loaded symbols for /lib64/ld-linux-x86-64.so.2
>   0x00007ffff7ddb6b0 in ?? () from /lib64/ld-linux-x86-64.so.2
>   (gdb) list
>   1     int
>   2     main()
>   3     @{
>   4       int   a = 1;
>   5
>   6       while (1)
>   7         printf("%d\n", a++);
>   8     @}
>   (gdb) set $break_count_on=1
>   (gdb) b 7
>   Breakpoint 1 at 0x400503: file 1.c, line 7.
>   (gdb) condition 1 ($break_count_val == 10)
>   (gdb) c
>   Continuing.
>
>   Breakpoint 1, main () at 1.c:7
>   7         printf("%d\n", a++);
>   @end smallexample
>
>   In gdbserver part, you can see that:
>
>   @smallexample
>   Process /home/teawater/tmp/a.out created; pid = 7937
>   Listening on port 1234
>   Remote debugging from host 127.0.0.1
>   Found breakpoint condition.
>   Found breakpoint condition.
>   Found breakpoint condition.
>   1
>   2
>   3
>   4
>   5
>   6
>   7
>   8
>   9
>   @end smallexample
>
>   The following example show how to use breakpoint pass-count to show
>   how many times an address was passed:
>
>   @smallexample
>   (gdb) set non-stop on
>   (gdb) set target-async on
>   (gdb) target remote :1234
>   Remote debugging using :1234
>   [New Thread 7944]
>   (gdb)
>   [Thread 7944] #1 stopped.
>   0x00007ffff7ddb6b0 in ?? ()
>   set $break_count_on=2
>   (gdb) list
>   1     int
>   2     main()
>   3     @{
>   4       int   a = 1;
>   5
>   6       while (1)
>   7         printf("%d\n", a++);
>   8     @}
>   (gdb) b 7
>   Breakpoint 1 at 0x400503: file 1.c, line 7.
>   (gdb) condition 1 ($break_count_val == 0)
>   (gdb) c&
>   Continuing.
>   (gdb) p $break_count_val
>   $1 = 96965
>   (gdb) p $break_count_val
>   $2 = 148548
>   @end smallexample

[-- Attachment #2: target_attribute_doc.txt --]
[-- Type: text/plain, Size: 12880 bytes --]

--- a/doc/agentexpr.texi
+++ b/doc/agentexpr.texi
@@ -450,8 +450,12 @@ alignment within the bytecode stream; th
 register number one byte at a time.
 
 @item @code{getv} (0x2c) @var{n}: @result{} @var{v}
-Push the value of trace state variable number @var{n}, without sign
-extension.
+Push the value of trace state variable or target attribute number
+@var{n}.
+
+If @var{n} is a trace state variable, the value is not sign-extended.
+If @var{n} is the id of a target attribute, it is type-converted
+according to the type of the target attribute..
 
 The variable number @var{n} is encoded as a 16-bit unsigned integer
 immediately following the @code{getv} bytecode.  It is always stored most
@@ -462,10 +466,15 @@ alignment within the bytecode stream; th
 register number one byte at a time.
 
 @item @code{setv} (0x2d) @var{n}: @result{} @var{v}
-Set trace state variable number @var{n} to the value found on the top
-of the stack.  The stack is unchanged, so that the value is readily
-available if the assignment is part of a larger expression.  The
-handling of @var{n} is as described for @code{getv}.
+If @var{n} is the number of a trace state variable, set that variable
+to the value found on the top of the stack.  The stack is unchanged,
+so that the value is readily available if the assignment is part of a
+larger expression.  The handling of @var{n} is as described for
+@code{getv}.
+
+If @var{n} is the id of a target attribute, do the type conversion
+according to the type of target attribute @var{n}, and set target
+attribute @var{n} to the result.
 
 @item @code{trace} (0x0c): @var{addr} @var{size} @result{}
 Record the contents of the @var{size} bytes at @var{addr} in a trace
--- a/doc/gdb.texinfo
+++ b/doc/gdb.texinfo
@@ -179,6 +179,7 @@ software in general.  We will miss him.
 * Agent Expressions::           The GDB Agent Expression Mechanism
 * Target Descriptions::         How targets can describe themselves to
                                 @value{GDBN}
+* Target Attributes::           Controlling attributes of the target
 * Operating System Information:: Getting additional information from
                                  the operating system
 * Trace File Format::		GDB trace file format
@@ -34932,6 +34933,14 @@ If section was not specified, the sectio
 is also printed.  For dynamically linked executables, the name of
 executable or shared library containing the symbol is printed as well.
 
+@kindex maint load-target-attributes
+@item maint load-target-attributes @var{filename}
+Load @ref{Target Attributes} from an XML file.
+
+@kindex maint clear-target-attributes
+@item maint clear-target-attributes
+Remove all @ref{Target Attributes}.
+
 @end table
 
 The following command is useful for non-interactive invocations of
@@ -36611,6 +36620,11 @@ These are the currently defined stub fea
 @tab @samp{-}
 @tab Yes
 
+@item @samp{qXfer:target-attributes:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
 @item @samp{qXfer:libraries:read}
 @tab No
 @tab @samp{-}
@@ -36765,6 +36779,9 @@ The remote stub understands the @samp{qX
 The remote stub understands the @samp{qXfer:features:read} packet
 (@pxref{qXfer target description read}).
 
+@item qXfer:target-attributes:read
+The remote stub understands the @samp{qXfer:target-attributes:read} packet(@pxref{qXfer target attributes read}).
+
 @item qXfer:libraries:read
 The remote stub understands the @samp{qXfer:libraries:read} packet
 (@pxref{qXfer library list read}).
@@ -37022,6 +37039,15 @@ always loaded from the @samp{target.xml}
 This packet is not probed by default; the remote stub must request it,
 by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
 
+@item qXfer:target-attributes:read:@var{offset},@var{length}
+@anchor{qXfer target attributes read}
+Access the target attributes.  @xref{Format of Target Attributes}.  The
+annex part of the generic @samp{qXfer} packet must be empty
+(@pxref{qXfer read}).
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
 @item qXfer:libraries:read:@var{annex}:@var{offset},@var{length}
 @anchor{qXfer library list read}
 Access the target's list of loaded libraries.  @xref{Library List Format}.
@@ -37249,6 +37275,36 @@ The remote server created a new process.
 A badly formed request or an error was encountered.
 @end table
 
+@item qTA:@var{var}
+@cindex target attribute value, remote request
+@cindex @samp{qTA} packet
+Ask the stub for the value of the target attribute id @var{var}.
+
+Replies:
+@table @samp
+@item V@var{value}
+The value of the variable is @var{value}, encoded in hex.
+
+@item U
+The value of the target attribute is unknown.  This would occur,
+for example, if the user is examining a trace frame in which the
+requested target attribute was not collected, or perhaps the
+attribute is associated with a hardware register that is not
+presently accessible.
+@end table
+
+@item QTA:@var{n}:@var{value}
+@cindex target attribute value, remote set
+@cindex @samp{QTA} packet
+Set the target attribute @var{var} to have the value @var{value}.
+Reply:
+@table @samp
+@item OK
+for success
+@item E @var{NN}
+for an error
+@end table
+
 @end table
 
 @node Architecture-Specific Protocol Details
@@ -40309,6 +40365,245 @@ through @samp{B31}.
 The @samp{org.gnu.gdb.tic6x.c6xp} feature is optional.  It should
 contain registers @samp{TSR}, @samp{ILC} and @samp{RILC}.
 
+@node Target Attributes
+@appendix Target Attributes
+@cindex target attributes
+
+Some @value{GDBN} targets may have some special attributes that are
+specific to that target, such as hardware registers, software flags
+managed by a stub or agent, and so on.  @value{GDBN} can access target
+attributes directly, or through agent code that is running on the
+target.
+
+A target attribute may include name, id, type, access mode, the
+breakpoint type, and a breakpoint address.
+
+Target attributes are solely defined by the target and supplied to
+@value{GDBN} during a debugging session.  The target supplies them in
+XML format, @value{GDBN} must be linked with the Expat library in
+order to use attributes.  @xref{Expat}.
+
+@menu
+* Retrieving Target Attributes::	How target attributes are fetched from a target
+* Format of Target Attributes::		The contents of a target attributes list
+* Access Target Attributes::		Access target attributes
+* Example of Target Attributes::	Example of target attributes in gdbserver
+@end menu
+
+@node Retrieving Target Attributes
+@section Retrieving Target Attributes
+@cindex retrieving target attributes
+
+Target attributes can be read from the target automatically.  The
+default behavior is to read the attributes from the target.
+@value{GDBN} retrieves it via the remote protocol using
+@samp{qXfer:target-attributes:read} requests (@pxref{qXfer target
+attributes read}).  The contents are an XML document, in the form
+described at @ref{Format of Target Attributes}.
+
+@node Format of Target Attributes
+@section Format of Target Attributes
+@cindex format of target attributes
+
+Here is a simple target attributes list that include two target
+attributes ``foo'' and ``bar'':
+
+@smallexample
+<target-attributes>
+	<target-attribute name="foo" id="1" type="int8" >
+		<access>
+			<agent read="yes" write="no"/>
+			<gdb write="yes" read="yes"/>
+		</access>
+		<support software-breakpoint="yes" hardware-breakpoint="yes" hardware-watchpoint="yes" tracepoint="yes"/>
+		<addresses>
+			<address start="0x123" end="0x456" />
+			<address start="0x789" end="0x1111" />
+		</addresses>
+	</target-attribute>
+	<target-attribute name="bar" id="2" type="int32" target-only-cond-check="yes">
+		<access>
+			<agent read="yes" write="no"/>
+			<gdb read="yes"/>
+		</access>
+		<support software-breakpoint="yes" hardware-breakpoint="yes" tracepoint="yes"/>
+	</target-attribute>
+</target-attributes>
+@end smallexample
+
+This defines the @samp{name}, @samp{id} , @samp{type}
+and @samp{target-only-cond-check} of a target attribute.
+The type can be @samp{int8}, @samp{uint8}, @samp{int16}, @samp{uint16},
+@samp{int32}, @samp{uint32}, @samp{int64} or @samp{uint64}.
+If @samp{target-only-cond-check} set to @samp{yes}, GDB will not check the
+condition of breakpoint in its side.  If @samp{target-only-cond-check} not
+define, it means @samp{no}.
+
+@smallexample
+<target-attribute name="foo" id="1" type="int8" >
+@end smallexample
+
+This defines the agent access mode of a target attribute.
+If @samp{read} or @samp{write} is not defined, it means @samp{no}.
+
+@smallexample
+<agent read="yes" write="no"/>
+@end smallexample
+
+This defines the GDB access mode of a target attribute.
+If @samp{read} or @samp{write} is not defined, it means @samp{no}.
+
+@smallexample
+<gdb write="yes" read="yes"/>
+@end smallexample
+
+This defines the breakpoint type that a target attribute can be used
+in the condition or commands of these type breakpoints.  If a type is
+not defined, it means @samp{no}.
+
+@smallexample
+<support software-breakpoint="yes" hardware-breakpoint="yes" hardware-watchpoint="yes" tracepoint="yes"/>
+@end smallexample
+
+This define the breakpoint address range that a target attribute can
+be used in the condition or commands of the breakpoints that are
+inside this address range.  If address is defined, this target
+attribute supports any address.
+
+@smallexample
+<addresses>
+	<address start="0x123" end="0x456" />
+	<address start="0x789" end="0x1111" />
+</addresses>
+@end smallexample
+
+@node Access Target Attributes
+@section Access Target Attributes
+@cindex access target attributes
+
+Target attributes may be used in breakpoint conditions and actions,
+as well as being included in expressions and print commands.  The
+syntax is the same as for convenience variables; target attributes
+will mask convenience variables of the same name.
+
+@table @code
+
+@kindex info target-attributes
+@item info target-attributes
+Status of target attributes.
+
+@end table
+
+@node Example of Target Attributes
+@section Example of Target Attributes
+@cindex example of target attributes
+
+Gdbserver includes a target attribute to count how many times each
+breakpoint has been passed.
+
+This function will not be built in by default.  To include it in
+gdbserver, add @code{--enable-break-count} in the config command.
+When built with this option, gdbserver will report three target
+attributes:
+
+@table @samp
+
+@item $break_count_on
+This is the switch of the breakpoints pass count function.  The
+default value of it is 0, the breakpoints pass count function is
+disabled.  If it is set to 1, counting is enabled, and the count value
+of all the breakpoints will reset to 0 when the inferior stops and
+continues again.  If it is set to 2, function is enabled, but the
+count value will not be reset.
+
+@item $break_count_select
+When the count function is enabled, this sets the address of the
+breakpoint whose hits will be counted in $break_count_val.
+
+@item $break_count_val
+This is the current value of the breakpoint pass count.
+
+@end table
+
+The following example shows how to use the breakpoints pass count
+function in a breakpoint condition:
+
+@smallexample
+(gdb) target remote :1234
+Remote debugging using :1234
+Reading symbols from /lib64/ld-linux-x86-64.so.2...(no debugging symbols found)...done.
+Loaded symbols for /lib64/ld-linux-x86-64.so.2
+0x00007ffff7ddb6b0 in ?? () from /lib64/ld-linux-x86-64.so.2
+(gdb) list
+1	int
+2	main()
+3	@{
+4	  int	a = 1;
+5
+6	  while (1)
+7	    printf("%d\n", a++);
+8	@}
+(gdb) set $break_count_on=1
+(gdb) b 7
+Breakpoint 1 at 0x400503: file 1.c, line 7.
+(gdb) condition 1 ($break_count_val == 10)
+(gdb) c
+Continuing.
+
+Breakpoint 1, main () at 1.c:7
+7	    printf("%d\n", a++);
+
+In gdbserver part, you can see that:
+Process /home/teawater/tmp/a.out created; pid = 7937
+Listening on port 1234
+Remote debugging from host 127.0.0.1
+Found breakpoint condition.
+Found breakpoint condition.
+Found breakpoint condition.
+1
+2
+3
+4
+5
+6
+7
+8
+9
+@end smallexample
+
+The following example shows how to use breakpoints pass count to show
+an address passed times:
+
+@smallexample
+(gdb) set non-stop on
+(gdb) set target-async on
+(gdb) target remote :1234
+Remote debugging using :1234
+[New Thread 7944]
+(gdb)
+[Thread 7944] #1 stopped.
+0x00007ffff7ddb6b0 in ?? ()
+set $break_count_on=2
+(gdb) list
+1	int
+2	main()
+3	@{
+4	  int	a = 1;
+5
+6	  while (1)
+7	    printf("%d\n", a++);
+8	@}
+(gdb) b 7
+Breakpoint 1 at 0x400503: file 1.c, line 7.
+(gdb) condition 1 ($break_count_val == 0)
+(gdb) c&
+Continuing.
+(gdb) p $break_count_val
+$1 = 96965
+(gdb) p $break_count_val
+$2 = 148548
+@end smallexample
+
 @node Operating System Information
 @appendix Operating System Information
 @cindex operating system information