Re: [PATCH] target attributes [5/5] doc

Eli Zaretskii
2012-08-31T19:25:26Z

> 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