This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.
Index Nav: | [Date Index] [Subject Index] [Author Index] [Thread Index] | |
---|---|---|
Message Nav: | [Date Prev] [Date Next] | [Thread Prev] [Thread Next] |
Other format: | [Raw text] |
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:
target_attribute_doc.txt
Description: Text document
Index Nav: | [Date Index] [Subject Index] [Author Index] [Thread Index] | |
---|---|---|
Message Nav: | [Date Prev] [Date Next] | [Thread Prev] [Thread Next] |