[PATCH] tracepoint: add new trace command "printf"[3] doc

[PATCH] tracepoint: add new trace command "printf"[3] doc

[Hui Zhu]

[-- Attachment #1: Type: text/plain, Size: 261 bytes --]

Hi guys,

This is the patch for the doc for the tracepoint command printf and
agent op printf.

Thanks,
Hui

2011-02-17  Hui Zhu  <teawater@gmail.com>

	* agentexpr.texi (Bytecode Descriptions): Add printf.
	* gdb.texinfo (Tracepoint Action Lists): Add printf.

[-- Attachment #2: tp_print_doc.txt --]
[-- Type: text/plain, Size: 1481 bytes --]

---
 doc/agentexpr.texi |    7 +++++++
 doc/gdb.texinfo    |    6 ++++++
 2 files changed, 13 insertions(+)

--- a/doc/agentexpr.texi
+++ b/doc/agentexpr.texi
@@ -479,6 +479,13 @@ named @code{trace_quick16}, for consiste
 Record the value of trace state variable number @var{n} in the trace
 buffer.  The handling of @var{n} is as described for @code{getv}.
 
+@item @code{printf} (0x31) @var{n} @var{template}: @result{}
+Print the values in the stack under the control of the string template.
+The end of @var{template} is 0x00.
+If @var{n} is 0, just output the string template.
+If @var{n} is 1, pop a value from the stack and print it under the control
+of the string template.
+
 @item @code{end} (0x27): @result{}
 Stop executing bytecode; the result should be the top element of the
 stack.  If the purpose of the expression was to compute an lvalue or a
--- a/doc/gdb.texinfo
+++ b/doc/gdb.texinfo
@@ -10242,6 +10242,12 @@ state variables (@pxref{Trace State Vari
 values to the trace buffer, as would be the case if the @code{collect}
 action were used.
 
+@kindex printf
+@item printf @var{template}, @var{expressions}@dots{}
+Print the values of one or more @var{expressions} under the control of
+the string @var{template} in @code{gdbserver} part.
+The command format is with simple @code{printf} (@pxref{Output, printf}).
+
 @kindex while-stepping @r{(tracepoints)}
 @item while-stepping @var{n}
 Perform @var{n} single-step instruction traces after the tracepoint,

Re: [PATCH] tracepoint: add new trace command "printf"[3] doc

[Eli Zaretskii]

> From: Hui Zhu <teawater@gmail.com>
> Date: Thu, 17 Feb 2011 16:13:11 +0800
> Cc: Doug Evans <dje@google.com>, Stan Shebs <stan@codesourcery.com>, 
> 	Michael Snyder <msnyder@vmware.com>
> 
> This is the patch for the doc for the tracepoint command printf and
> agent op printf.

Thanks.

> +Print the values in the stack under the control of the string template.

"on the stack", not "in".

Also, you say "values" here, but the rest of the description talks
about one value at most.  Which one is right?

I would remove "the" before "control".

Finally, "template" should be in @var.

> +The end of @var{template} is 0x00.

Not clear what you mean here.  Do you mean that "template" is a
null-terminated string?

> +If @var{n} is 0, just output the string template.
> +If @var{n} is 1, pop a value from the stack and print it under the control
> +of the string template.

Same comments as above: remove "the" before "control" and put
"template" in @var.

> +@kindex printf

We already have one such @kindex entry.  Please change this one to

  @kindex printf, in tracepoint actions

> +@item printf @var{template}, @var{expressions}@dots{}
> +Print the values of one or more @var{expressions} under the control of

"under control", without "the".

> +the string @var{template} in @code{gdbserver} part.

I don't understand what do you mean by "in @code{gdbserver} part".

> +The command format is with simple @code{printf} (@pxref{Output, printf}).

Please rephrase as

  @var{template} is a format string of the same form as used with the
  @value{GDBN} command @code{printf} (@pxref{Output, printf}).

Thanks.

Re: [PATCH] tracepoint: add new trace command "printf"[3] doc

[Hui Zhu]

[-- Attachment #1: Type: text/plain, Size: 2067 bytes --]

On Thu, Feb 17, 2011 at 19:41, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Hui Zhu <teawater@gmail.com>
>> Date: Thu, 17 Feb 2011 16:13:11 +0800
>> Cc: Doug Evans <dje@google.com>, Stan Shebs <stan@codesourcery.com>,
>>       Michael Snyder <msnyder@vmware.com>
>>
>> This is the patch for the doc for the tracepoint command printf and
>> agent op printf.
>
> Thanks.
>
>> +Print the values in the stack under the control of the string template.
>
> "on the stack", not "in".
>
> Also, you say "values" here, but the rest of the description talks
> about one value at most.  Which one is right?
>
> I would remove "the" before "control".
>
> Finally, "template" should be in @var.
>
>> +The end of @var{template} is 0x00.
>
> Not clear what you mean here.  Do you mean that "template" is a
> null-terminated string?
>
>> +If @var{n} is 0, just output the string template.
>> +If @var{n} is 1, pop a value from the stack and print it under the control
>> +of the string template.
>
> Same comments as above: remove "the" before "control" and put
> "template" in @var.
>
>> +@kindex printf
>
> We already have one such @kindex entry.  Please change this one to
>
>  @kindex printf, in tracepoint actions
>
>> +@item printf @var{template}, @var{expressions}@dots{}
>> +Print the values of one or more @var{expressions} under the control of
>
> "under control", without "the".
>
>> +the string @var{template} in @code{gdbserver} part.
>
> I don't understand what do you mean by "in @code{gdbserver} part".
>
>> +The command format is with simple @code{printf} (@pxref{Output, printf}).
>
> Please rephrase as
>
>  @var{template} is a format string of the same form as used with the
>  @value{GDBN} command @code{printf} (@pxref{Output, printf}).
>
> Thanks.
>

Thanks for your help, Eli.

I make a new patch according to your comments.

Best,
Hui

2011-02-17  Hui Zhu  <teawater@gmail.com>

	* agentexpr.texi (Bytecode Descriptions): Add printf.
	* gdb.texinfo (Tracepoint Action Lists): Add printf.

[-- Attachment #2: tp_print_doc.txt --]
[-- Type: text/plain, Size: 1542 bytes --]

---
 doc/agentexpr.texi |    7 +++++++
 doc/gdb.texinfo    |    7 +++++++
 2 files changed, 14 insertions(+)

--- a/doc/agentexpr.texi
+++ b/doc/agentexpr.texi
@@ -479,6 +479,13 @@ named @code{trace_quick16}, for consiste
 Record the value of trace state variable number @var{n} in the trace
 buffer.  The handling of @var{n} is as described for @code{getv}.
 
+@item @code{printf} (0x31) @var{n} @var{template}: @result{}
+Print a value on the stack under control of the string @var{template}.
+@var{template} is a null-terminated string.
+If @var{n} is 0, just output the string template.
+If @var{n} is 1, pop a value from the stack and print it under control
+of the string @var{template}.
+
 @item @code{end} (0x27): @result{}
 Stop executing bytecode; the result should be the top element of the
 stack.  If the purpose of the expression was to compute an lvalue or a
--- a/doc/gdb.texinfo
+++ b/doc/gdb.texinfo
@@ -10242,6 +10242,13 @@ state variables (@pxref{Trace State Vari
 values to the trace buffer, as would be the case if the @code{collect}
 action were used.
 
+@kindex printf, in tracepoint actions
+@item printf @var{template}, @var{expressions}@dots{}
+Print the values of one or more @var{expressions} under control of
+the string @var{template}.
+@var{template} is a format string of the same form as used with the
+@value{GDBN} command @code{printf} (@pxref{Output, printf}).
+
 @kindex while-stepping @r{(tracepoints)}
 @item while-stepping @var{n}
 Perform @var{n} single-step instruction traces after the tracepoint,

Re: [PATCH] tracepoint: add new trace command "printf"[3] doc

[Eli Zaretskii]

> From: Hui Zhu <teawater@gmail.com>
> Date: Thu, 17 Feb 2011 23:48:58 +0800
> Cc: tromey@redhat.com, gdb-patches@sourceware.org, dje@google.com, 
> 	stan@codesourcery.com, msnyder@vmware.com
> 
> Thanks for your help, Eli.
> 
> I make a new patch according to your comments.

This version is okay.  Thanks.

Re: [PATCH] tracepoint: add new trace command "printf"[3] doc

[Hui Zhu]

Thanks Eli.
Checked in.

Best,
Hui

On Fri, Feb 18, 2011 at 03:12, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Hui Zhu <teawater@gmail.com>
>> Date: Thu, 17 Feb 2011 23:48:58 +0800
>> Cc: tromey@redhat.com, gdb-patches@sourceware.org, dje@google.com,
>>       stan@codesourcery.com, msnyder@vmware.com
>>
>> Thanks for your help, Eli.
>>
>> I make a new patch according to your comments.
>
> This version is okay.  Thanks.
>