From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 10039 invoked by alias); 24 Oct 2012 17:18:53 -0000 Received: (qmail 10009 invoked by uid 22791); 24 Oct 2012 17:18:51 -0000 X-SWARE-Spam-Status: No, hits=-4.7 required=5.0 tests=AWL,BAYES_00,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FROM,KHOP_RCVD_TRUST,KHOP_THREADED,RCVD_IN_DNSWL_LOW,RCVD_IN_HOSTKARMA_YE X-Spam-Check-By: sourceware.org Received: from mail-vc0-f169.google.com (HELO mail-vc0-f169.google.com) (209.85.220.169) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Wed, 24 Oct 2012 17:18:45 +0000 Received: by mail-vc0-f169.google.com with SMTP id fl17so924526vcb.0 for ; Wed, 24 Oct 2012 10:18:43 -0700 (PDT) Received: by 10.52.16.110 with SMTP id f14mr22135577vdd.8.1351099122609; Wed, 24 Oct 2012 10:18:42 -0700 (PDT) MIME-Version: 1.0 Received: by 10.220.159.147 with HTTP; Wed, 24 Oct 2012 10:18:02 -0700 (PDT) In-Reply-To: References: <503DCEE4.2010706@mentor.com> <83sjb2q2yw.fsf@gnu.org> From: Hui Zhu Date: Wed, 24 Oct 2012 17:18:00 -0000 Message-ID: Subject: Re: [PATCH] target attributes [5/5] doc To: Eli Zaretskii Cc: Hui Zhu , gdb-patches@sourceware.org, stan_shebs@mentor.com Content-Type: text/plain; charset=ISO-8859-1 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-10/txt/msg00464.txt.bz2 Ping. Thanks, Hui On Sun, Sep 2, 2012 at 7:20 PM, Hui Zhu wrote: > 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 wrote: >>> 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