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

Hui Zhu
2012-11-21T08:51:09Z

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