[PATCH] target attributes [5/5] doc

[Hui Zhu <hui_zhu@mentor.com>]

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