[PATCH] target attributes [5/5] doc

[PATCH] target attributes [5/5] doc

[Hui Zhu]

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

This patch add doc about target attributes in the doc.

Thanks,
Hui


2012-08-29  Hui Zhu  <hui_zhu@mentor.com>
	    Stan Shebs  <stan@codesourcery.com>

	* agentexpr.texi (Bytecode Descriptions): Update "setv" and
	"getv".
	* gdb.texinfo (Maintenance Commands): Add
	"maint load-target-attributes" and "maint clear-target-attributes".
	(General Query Packets): Add "qXfer:target-attributes:read",
	"qTA" and "QTA".
	(Target Attributes): New appendix.

[-- Attachment #2: target_attribute_doc.txt --]
[-- Type: text/plain, Size: 12797 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.
+If @var{n} is the number of trace state variable, Push the value of
+trace state variable number @var{n}, without sign extension.
+
+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.
 
 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,11 +466,16 @@ 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
+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
 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 target attribute, do the type convert according
+the type of target attribute @var{n} and the stack type, set to
+target attribute @var{n}.
+
 @item @code{trace} (0x0c): @var{addr} @var{size} @result{}
 Record the contents of the @var{size} bytes at @var{addr} in a trace
 buffer, for later retrieval by GDB.
--- 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 the Attributes of the Target
 * Operating System Information:: Getting additional information from
                                  the operating system
 * Trace File Format::		GDB trace file format
@@ -34907,6 +34908,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 a 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
@@ -36586,6 +36595,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{-}
@@ -36740,6 +36754,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}).
@@ -36997,6 +37014,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}.
@@ -37224,6 +37250,38 @@ 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}.  This will be unlongest value
+that is convert from the current value of the target attribute.
+
+@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 hardware register of this target attribute is busy that cannot
+access.
+@end table
+
+@item QTA:@var{n}:@var{value}
+@cindex target attribute value, remote set
+@cindex @samp{QTA} packet
+Set unlongest value that is convert from the value that want set to
+target attribute to target attribute @var{var}.
+Reply:
+@table @samp
+@item OK
+for success
+@item E @var{NN}
+for an error
+@end table
+
 @end table
 
 @node Architecture-Specific Protocol Details
@@ -40284,6 +40342,241 @@ 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 of @value{GDBN} target have some special attributes that can be
+access.  They may be hardware registers or software flags and so on.
+@value{GDBN} can access target attributes directly or through agent
+code that running in target.
+
+A target attributes will include name, id, type, access mode,
+the breakpoint type that it support, the breakpoint address that
+it support.
+
+@value{GDBN} must be linked with the Expat library to support XML
+target 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 of it are
+an XML document, of the form described in
+@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 define 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 define the agent access mode of a target attribute.
+If @samp{read} or @samp{write} not define, it means @samp{no}.
+@smallexample
+<agent read="yes" write="no"/>
+@end smallexample
+
+This define the GDB access mode of a target attribute.
+If @samp{read} or @samp{write} not define, it means @samp{no}.
+@smallexample
+<gdb write="yes" read="yes"/>
+@end smallexample
+
+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.
+If not define any address, this target attribute support 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
+
+@table @code
+
+@kindex info target-attributes
+@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
+
+@node Example of Target Attributes
+@section Example of Target Attributes
+@cindex example of target attributes
+
+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

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

[Eli Zaretskii]

> 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

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

[Hui Zhu]

[-- 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

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

[Hui Zhu]

Ping.

Thanks,
Hui

On Sun, Sep 2, 2012 at 7:20 PM, Hui Zhu <teawater@gmail.com> wrote:
> 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

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

[Eli Zaretskii]

> From: Hui Zhu <teawater@gmail.com>
> Date: Sun, 2 Sep 2012 19:20:01 +0800
> Cc: Hui Zhu <hui_zhu@mentor.com>, gdb-patches@sourceware.org, stan_shebs@mentor.com
> 
> 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.

Sorry for the long delay.

> +@kindex maint load-target-attributes
> +@item maint load-target-attributes @var{filename}
> +Load @ref{Target Attributes} from an XML file.

Please don't let @ref serve double duty, it looks ugly in the manual.
Something like this is better:

  Load target attributes (@pxref{Target Attributes}) from an XML file.

> +@kindex maint clear-target-attributes
> +@item maint clear-target-attributes
> +Remove all @ref{Target Attributes}.

Same here.

> +@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

A few lines in this @smallexample will overflow the page dimensions;
please break them in two lines.

> +If @samp{target-only-cond-check} set to @samp{yes}, GDB will not check the
                                                       ^^^
@value{GDBN}

> +condition of breakpoint in its side.  If @samp{target-only-cond-check} not
> +define, it means @samp{no}.
   ^^^^^^
"defined"

> +@smallexample
> +<support software-breakpoint="yes" hardware-breakpoint="yes" hardware-watchpoint="yes" tracepoint="yes"/>
> +@end smallexample

Too long, please break into 2 lines.

> +This define the breakpoint address range that a target attribute can
        ^^^^^^
"defines"

> +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. ^^^^^^^^^^^^^^^^^

Did you mean "not defined"?

> +Target attributes may be used in breakpoint conditions and actions,
> +as well as being included in expressions and print commands.  The
              ^^^^^
"be"

> +of all the breakpoints will reset to 0 when the inferior stops and
                          ^^^^^^^^^^
"will be reset"

> +@smallexample
> +(gdb) target remote :1234
> +Remote debugging using :1234
> +Reading symbols from /lib64/ld-linux-x86-64.so.2...(no debugging symbols found)...done.

This line is too long, please break it in 2.

OK with these changes.

Thanks.

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

[Hui Zhu]

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

On 10/26/12 01:31, Eli Zaretskii wrote:
>> From: Hui Zhu <teawater@gmail.com>
>> Date: Sun, 2 Sep 2012 19:20:01 +0800
>> Cc: Hui Zhu <hui_zhu@mentor.com>, gdb-patches@sourceware.org, stan_shebs@mentor.com
>>
>> 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.
>
> Sorry for the long delay.
>
>> +@kindex maint load-target-attributes
>> +@item maint load-target-attributes @var{filename}
>> +Load @ref{Target Attributes} from an XML file.
>
> Please don't let @ref serve double duty, it looks ugly in the manual.
> Something like this is better:
>
>    Load target attributes (@pxref{Target Attributes}) from an XML file.
>
>> +@kindex maint clear-target-attributes
>> +@item maint clear-target-attributes
>> +Remove all @ref{Target Attributes}.
>
> Same here.
>
>> +@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
>
> A few lines in this @smallexample will overflow the page dimensions;
> please break them in two lines.
>
>> +If @samp{target-only-cond-check} set to @samp{yes}, GDB will not check the
>                                                         ^^^
> @value{GDBN}
>
>> +condition of breakpoint in its side.  If @samp{target-only-cond-check} not
>> +define, it means @samp{no}.
>     ^^^^^^
> "defined"
>
>> +@smallexample
>> +<support software-breakpoint="yes" hardware-breakpoint="yes" hardware-watchpoint="yes" tracepoint="yes"/>
>> +@end smallexample
>
> Too long, please break into 2 lines.
>
>> +This define the breakpoint address range that a target attribute can
>          ^^^^^^
> "defines"
>
>> +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. ^^^^^^^^^^^^^^^^^
>
> Did you mean "not defined"?
>
>> +Target attributes may be used in breakpoint conditions and actions,
>> +as well as being included in expressions and print commands.  The
>                ^^^^^
> "be"
>
>> +of all the breakpoints will reset to 0 when the inferior stops and
>                            ^^^^^^^^^^
> "will be reset"
>
>> +@smallexample
>> +(gdb) target remote :1234
>> +Remote debugging using :1234
>> +Reading symbols from /lib64/ld-linux-x86-64.so.2...(no debugging symbols found)...done.
>
> This line is too long, please break it in 2.
>
> OK with these changes.
>
> Thanks.
>

Thanks for your help.

I post a new version according to your comments.

Best,
Hui

2012-10-31  Hui Zhu  <hui_zhu@mentor.com>
	    Stan Shebs  <stan@codesourcery.com>

	* agentexpr.texi (Bytecode Descriptions): Update "setv" and
	"getv".
	* gdb.texinfo (Maintenance Commands): Add
	"maint load-target-attributes" and "maint clear-target-attributes".
	(General Query Packets): Add "qXfer:target-attributes:read",
	"qTA" and "QTA".
	(Target Attributes): New appendix.


[-- Attachment #2: target_attribute_doc.txt --]
[-- Type: text/plain, Size: 12960 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
@@ -34985,6 +34986,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 target attributes (@pxref{Target Attributes}) from an XML file.
+
+@kindex maint clear-target-attributes
+@item maint clear-target-attributes
+Remove all target attributes (@pxref{Target Attributes}).
+
 @end table
 
 The following command is useful for non-interactive invocations of
@@ -36664,6 +36673,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{-}
@@ -36818,6 +36832,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}).
@@ -37075,6 +37092,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}.
@@ -37302,6 +37328,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
@@ -40362,6 +40418,250 @@ 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}, @value{GDBN} will not check
+the condition of breakpoint in its side.  If @samp{target-only-cond-check} not
+defined, 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 defines 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 not 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 be 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 be 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

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

[Eli Zaretskii]

> Date: Wed, 31 Oct 2012 11:31:55 +0800
> From: Hui Zhu <hui_zhu@mentor.com>
> CC: Hui Zhu <teawater@gmail.com>, <gdb-patches@sourceware.org>,
> 	<stan_shebs@mentor.com>
> 
> +If @var{n} is the id of a target attribute, it is type-converted
> +according to the type of the target attribute..
                                                ^^
Extra period, please delete.

> +This defines the GDB access mode of a target attribute.
                    ^^^
@value{GDBN}

Other than that, OK.  Thanks.

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

[Hui Zhu]

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

On Wed, Oct 31, 2012 at 11:44 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Wed, 31 Oct 2012 11:31:55 +0800
>> From: Hui Zhu <hui_zhu@mentor.com>
>> CC: Hui Zhu <teawater@gmail.com>, <gdb-patches@sourceware.org>,
>>       <stan_shebs@mentor.com>
>>
>> +If @var{n} is the id of a target attribute, it is type-converted
>> +according to the type of the target attribute..
>                                                 ^^
> Extra period, please delete.
>
>> +This defines the GDB access mode of a target attribute.
>                     ^^^
> @value{GDBN}
>
> Other than that, OK.  Thanks.

Thanks for your help.  Post a new version according to your comments.

Best,
Hui

[-- Attachment #2: target_attribute_doc.txt --]
[-- Type: text/plain, Size: 12964 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 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
@@ -35224,6 +35225,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 target attributes (@pxref{Target Attributes}) from an XML file.
+
+@kindex maint clear-target-attributes
+@item maint clear-target-attributes
+Remove all target attributes (@pxref{Target Attributes}).
+
 @end table
 
 The following command is useful for non-interactive invocations of
@@ -36903,6 +36912,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{-}
@@ -37057,6 +37071,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}).
@@ -37314,6 +37331,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}.
@@ -37541,6 +37567,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
@@ -40601,6 +40657,250 @@ 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}, @value{GDBN} will not check
+the condition of breakpoint in its side.  If @samp{target-only-cond-check} not
+defined, 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 @value{GDBN} 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 defines 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 not 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 be 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 be 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

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

[Eli Zaretskii]

> From: Hui Zhu <teawater@gmail.com>
> Date: Wed, 21 Nov 2012 16:49:03 +0800
> Cc: Hui Zhu <hui_zhu@mentor.com>, gdb-patches ml <gdb-patches@sourceware.org>, 
> 	Stan Shebs <stan_shebs@mentor.com>
> 
> >> +If @var{n} is the id of a target attribute, it is type-converted
> >> +according to the type of the target attribute..
> >                                                 ^^
> > Extra period, please delete.
> >
> >> +This defines the GDB access mode of a target attribute.
> >                     ^^^
> > @value{GDBN}
> >
> > Other than that, OK.  Thanks.
> 
> Thanks for your help.  Post a new version according to your comments.

OK, thanks.