[PATCH] target attributes [5/5] doc

[Hui Zhu]

Ping.

Thanks,
Hui

On Sun, Sep 2, 2012 at 7:20 PM, Hui Zhu <teawater@gmail.com> 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 <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