From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 15957 invoked by alias); 31 Aug 2012 19:25:26 -0000 Received: (qmail 15787 invoked by uid 22791); 31 Aug 2012 19:25:21 -0000 X-SWARE-Spam-Status: No, hits=-4.1 required=5.0 tests=AWL,BAYES_00,KHOP_THREADED,RCVD_IN_DNSWL_NONE,RCVD_IN_HOSTKARMA_NO,RCVD_IN_NIX_SPAM,SPF_SOFTFAIL X-Spam-Check-By: sourceware.org Received: from mtaout20.012.net.il (HELO mtaout20.012.net.il) (80.179.55.166) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Fri, 31 Aug 2012 19:24:58 +0000 Received: from conversion-daemon.a-mtaout20.012.net.il by a-mtaout20.012.net.il (HyperSendmail v2007.08) id <0M9M00I00WCPXR00@a-mtaout20.012.net.il> for gdb-patches@sourceware.org; Fri, 31 Aug 2012 22:24:39 +0300 (IDT) Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout20.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0M9M00IG3WL2WJ10@a-mtaout20.012.net.il>; Fri, 31 Aug 2012 22:24:39 +0300 (IDT) Date: Fri, 31 Aug 2012 19:25:00 -0000 From: Eli Zaretskii Subject: Re: [PATCH] target attributes [5/5] doc In-reply-to: <503DCEE4.2010706@mentor.com> To: Hui Zhu Cc: gdb-patches@sourceware.org, stan_shebs@mentor.com Reply-to: Eli Zaretskii Message-id: <83sjb2q2yw.fsf@gnu.org> References: <503DCEE4.2010706@mentor.com> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2012-08/txt/msg00901.txt.bz2 > Date: Wed, 29 Aug 2012 16:12:20 +0800 > From: Hui Zhu > > 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 > + > + > + > + > + > + > + This line is too long, please break it into 2. > + > + Likewise. > + 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 > + > +@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 > + > +@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 > + > +@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