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