[8/9] Documentation for DTrace USDT probes.
Commit Message
This patch modifies the `Static Probe Points' section on the GDB
manual in order to cover the support for DTrace USDT probes, in
addition to SystemTap SDT probes.
gdb/doc:
2014-09-26 Jose E. Marchesi <jose.marchesi@oracle.com>
* gdb.texinfo (Static Probe Points): Add cindex `static probe
point, DTrace'.
(Static Probe Points): Modified to cover DTrace probes in addition
to SystemTap probes.
---
gdb/doc/ChangeLog | 8 +++++++
gdb/doc/gdb.texinfo | 58 +++++++++++++++++++++++++++++++++------------------
2 files changed, 46 insertions(+), 20 deletions(-)
Comments
> From: "Jose E. Marchesi" <jose.marchesi@oracle.com>
> Date: Fri, 26 Sep 2014 11:48:24 +0200
>
> gdb/doc:
>
> 2014-09-26 Jose E. Marchesi <jose.marchesi@oracle.com>
>
> * gdb.texinfo (Static Probe Points): Add cindex `static probe
> point, DTrace'.
> (Static Probe Points): Modified to cover DTrace probes in addition
> to SystemTap probes.
No need to mention the name of the same node twice.
> +@itemize @bullet
> +@item @code{SystemTap} (@uref{http://sourceware.org/systemtap/})
> +@acronym{SDT} probes@footnote{See
> @uref{http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps}
> -for more information on how to add @code{SystemTap} @acronym{SDT} probes
> -in your applications.
> +for more information on how to add @code{SystemTap} @acronym{SDT}
> +probes in your applications.}. @code{SystemTap} probes are usable
> +from assembly, C and C@t{++} languages@footnote{See
> +@uref{http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation}
> +for a good reference on how the @acronym{SDT} probes are implemented.}.
> +@item @code{DTrace} (@uref{http://oss.oracle.com/projects/DTrace})
> +@acronym{USDT} probes. @code{DTrace} probes are usable from C and
> +C@t{++} languages.
> +@end itemize
Please leave an empty line before each @item.
> +Some @code{SystemTap} probes have an associated semaphore variable;
> +for instance, this happens automatically if you defined your probe
> +using a DTrace-style @file{.d} file. If your probe has a semaphore,
> +@value{GDBN} will automatically enable it when you specify a
> +breakpoint using the @samp{-probe-stap} notation. But, if you put a
> +breakpoint at a probe's location by some other method (e.g.,
> +@code{break file:line}), then @value{GDBN} will not automatically set
> +the semaphore. @code{DTrace} probes do not support the notion of
> +semaphores.
The last sentence confused me: you first explain something that seems
to imply semaphores are part of DTrace probes, but then say that they
don't support semaphores. What am I missing?
> +probe being handled. Some @code{DTrace} probes can be enabled or
> +disabled, but @code{SystemTap} probes do not support these notions.
Which "notions"? If you want to say they cannot be disabled, please
say so explicitly.
Thanks.
> +Some @code{SystemTap} probes have an associated semaphore variable;
> +for instance, this happens automatically if you defined your probe
> +using a DTrace-style @file{.d} file. If your probe has a semaphore,
> +@value{GDBN} will automatically enable it when you specify a
> +breakpoint using the @samp{-probe-stap} notation. But, if you put a
> +breakpoint at a probe's location by some other method (e.g.,
> +@code{break file:line}), then @value{GDBN} will not automatically set
> +the semaphore. @code{DTrace} probes do not support the notion of
> +semaphores.
The last sentence confused me: you first explain something that seems
to imply semaphores are part of DTrace probes, but then say that they
don't support semaphores. What am I missing?
The paragraph starts explaining that SystemTap probes may have
associated semaphore variables, followed by a short description on how
gdb handles these variables. That was part of the original
documentation on SystemTap probes.
I just added the last sentence to note that DTrace probes do not support
semaphore variables at all.
I don't see where the confusion is?
> +probe being handled. Some @code{DTrace} probes can be enabled or
> +disabled, but @code{SystemTap} probes do not support these notions.
Which "notions"? If you want to say they cannot be disabled, please
say so explicitly.
No, I want to say that SystemTap probes do not even support the notion
of being enabled or disabled. That is not quite the same than saying
that SystemTap probes cannot be disabled: for example some DTrace probes
cannot be disabled because they are always enabled.
> From: jose.marchesi@oracle.com (Jose E. Marchesi)
> Cc: gdb-patches@sourceware.org
> Date: Mon, 29 Sep 2014 12:31:26 +0200
>
>
> > +Some @code{SystemTap} probes have an associated semaphore variable;
> > +for instance, this happens automatically if you defined your probe
> > +using a DTrace-style @file{.d} file. If your probe has a semaphore,
> > +@value{GDBN} will automatically enable it when you specify a
> > +breakpoint using the @samp{-probe-stap} notation. But, if you put a
> > +breakpoint at a probe's location by some other method (e.g.,
> > +@code{break file:line}), then @value{GDBN} will not automatically set
> > +the semaphore. @code{DTrace} probes do not support the notion of
> > +semaphores.
>
> The last sentence confused me: you first explain something that seems
> to imply semaphores are part of DTrace probes, but then say that they
> don't support semaphores. What am I missing?
>
> The paragraph starts explaining that SystemTap probes may have
> associated semaphore variables, followed by a short description on how
> gdb handles these variables. That was part of the original
> documentation on SystemTap probes.
>
> I just added the last sentence to note that DTrace probes do not support
> semaphore variables at all.
>
> I don't see where the confusion is?
The confusion starts with the fact that "DTrace" is mentioned twice,
the first time in the context of discussing semaphores.
How about the following rewrite:
Some @code{SystemTap} probes have an associated semaphore variable.
If your probe has a semaphore, @value{GDBN} will automatically
enable it when you specify a breakpoint using the @samp{-probe-stap}
notation. But, if you put a breakpoint at a probe's location by
some other method (e.g., @code{break file:line}), then @value{GDBN}
will not automatically set the semaphore. @code{DTrace} probes do
not support semaphore variables associated with them.
> > +probe being handled. Some @code{DTrace} probes can be enabled or
> > +disabled, but @code{SystemTap} probes do not support these notions.
>
> Which "notions"? If you want to say they cannot be disabled, please
> say so explicitly.
>
> No, I want to say that SystemTap probes do not even support the notion
> of being enabled or disabled. That is not quite the same than saying
> that SystemTap probes cannot be disabled: for example some DTrace probes
> cannot be disabled because they are always enabled.
Sorry, I don't see the difference between "cannot be disabled" and
"don't support the notion of being enabled or disabled". A trap that
cannot be disabled is by definition always enabled, right? So from
the user point of view, saying they cannot be disabled says it all,
right?
> > +Some @code{SystemTap} probes have an associated semaphore variable;
> > +for instance, this happens automatically if you defined your probe
> > +using a DTrace-style @file{.d} file. If your probe has a semaphore,
> > +@value{GDBN} will automatically enable it when you specify a
> > +breakpoint using the @samp{-probe-stap} notation. But, if you put a
> > +breakpoint at a probe's location by some other method (e.g.,
> > +@code{break file:line}), then @value{GDBN} will not automatically set
> > +the semaphore. @code{DTrace} probes do not support the notion of
> > +semaphores.
>
> The last sentence confused me: you first explain something that seems
> to imply semaphores are part of DTrace probes, but then say that they
> don't support semaphores. What am I missing?
>
> The paragraph starts explaining that SystemTap probes may have
> associated semaphore variables, followed by a short description on how
> gdb handles these variables. That was part of the original
> documentation on SystemTap probes.
>
> I just added the last sentence to note that DTrace probes do not support
> semaphore variables at all.
>
> I don't see where the confusion is?
The confusion starts with the fact that "DTrace" is mentioned twice,
the first time in the context of discussing semaphores.
Aaah, that mention to the "DTrace-like" file. Yes, I agree, it can be
confusing now that DTrace probes are also supported.
How about the following rewrite:
Some @code{SystemTap} probes have an associated semaphore variable.
If your probe has a semaphore, @value{GDBN} will automatically
enable it when you specify a breakpoint using the @samp{-probe-stap}
notation. But, if you put a breakpoint at a probe's location by
some other method (e.g., @code{break file:line}), then @value{GDBN}
will not automatically set the semaphore. @code{DTrace} probes do
not support semaphore variables associated with them.
I think that is indeed better than the current wording. Thanks.
> > +probe being handled. Some @code{DTrace} probes can be enabled or
> > +disabled, but @code{SystemTap} probes do not support these notions.
>
> Which "notions"? If you want to say they cannot be disabled, please
> say so explicitly.
>
> No, I want to say that SystemTap probes do not even support the notion
> of being enabled or disabled. That is not quite the same than saying
> that SystemTap probes cannot be disabled: for example some DTrace probes
> cannot be disabled because they are always enabled.
Sorry, I don't see the difference between "cannot be disabled" and
"don't support the notion of being enabled or disabled". A trap that
cannot be disabled is by definition always enabled, right? So from
the user point of view, saying they cannot be disabled says it all,
right?
Well... right, from the user perspective SystemTap probes are always
enabled... Ok, I will follow your suggestion and just mention that
SystemTap probes cannot be disabled.
@@ -1,5 +1,13 @@
2014-09-26 Jose E. Marchesi <jose.marchesi@oracle.com>
+ * gdb.texinfo (Static Probe Points): Add cindex `static probe
+ point, DTrace'.
+ (Static Probe Points): Modified to cover DTrace probes in addition
+ to SystemTap probes. Also modified to cover the `enable probe'
+ and `disable probe' commands.
+
+2014-09-26 Jose E. Marchesi <jose.marchesi@oracle.com>
+
* gdb.texinfo (Static Probe Points): Cover the `enable probe' and
`disable probe' commands.
@@ -4932,34 +4932,49 @@ that can no longer be recreated.
@subsection Static Probe Points
@cindex static probe point, SystemTap
+@cindex static probe point, DTrace
@value{GDBN} supports @dfn{SDT} probes in the code. @acronym{SDT} stands
for Statically Defined Tracing, and the probes are designed to have a tiny
-runtime code and data footprint, and no dynamic relocations. They are
-usable from assembly, C and C@t{++} languages. See
-@uref{http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation}
-for a good reference on how the @acronym{SDT} probes are implemented.
+runtime code and data footprint, and no dynamic relocations.
+
+Currently, the following types of probes are supported on
+ELF-compatible systems:
-Currently, @code{SystemTap} (@uref{http://sourceware.org/systemtap/})
-@acronym{SDT} probes are supported on ELF-compatible systems. See
+@itemize @bullet
+@item @code{SystemTap} (@uref{http://sourceware.org/systemtap/})
+@acronym{SDT} probes@footnote{See
@uref{http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps}
-for more information on how to add @code{SystemTap} @acronym{SDT} probes
-in your applications.
+for more information on how to add @code{SystemTap} @acronym{SDT}
+probes in your applications.}. @code{SystemTap} probes are usable
+from assembly, C and C@t{++} languages@footnote{See
+@uref{http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation}
+for a good reference on how the @acronym{SDT} probes are implemented.}.
+@item @code{DTrace} (@uref{http://oss.oracle.com/projects/DTrace})
+@acronym{USDT} probes. @code{DTrace} probes are usable from C and
+C@t{++} languages.
+@end itemize
@cindex semaphores on static probe points
-Some probes have an associated semaphore variable; for instance, this
-happens automatically if you defined your probe using a DTrace-style
-@file{.d} file. If your probe has a semaphore, @value{GDBN} will
-automatically enable it when you specify a breakpoint using the
-@samp{-probe-stap} notation. But, if you put a breakpoint at a probe's
-location by some other method (e.g., @code{break file:line}), then
-@value{GDBN} will not automatically set the semaphore.
+Some @code{SystemTap} probes have an associated semaphore variable;
+for instance, this happens automatically if you defined your probe
+using a DTrace-style @file{.d} file. If your probe has a semaphore,
+@value{GDBN} will automatically enable it when you specify a
+breakpoint using the @samp{-probe-stap} notation. But, if you put a
+breakpoint at a probe's location by some other method (e.g.,
+@code{break file:line}), then @value{GDBN} will not automatically set
+the semaphore. @code{DTrace} probes do not support the notion of
+semaphores.
You can examine the available static static probes using @code{info
probes}, with optional arguments:
@table @code
@kindex info probes
-@item info probes stap @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
+@item info probes @r{[}@var{type}@r{]} @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
+If given, @var{type} is either @code{stap} for listing
+@code{SystemTap} probes or @code{dtrace} for listing @code{DTrace}
+probes. If omitted all probes are listed regardless of their types.
+
If given, @var{provider} is a regular expression used to match against provider
names when selecting which probes to list. If omitted, probes by all
probes from all providers are listed.
@@ -4979,8 +4994,8 @@ List the available static probes, from all types.
@cindex enabling and disabling probes
Some probe points can be enabled and/or disabled. The effects
associated to enabling or disabling a probe depend on the type of
-probe being handled. @code{SystemTap} probes do not support these
-notions.
+probe being handled. Some @code{DTrace} probes can be enabled or
+disabled, but @code{SystemTap} probes do not support these notions.
You can enable (or disable) one or more probes using the following
commands, with optional arguments:
@@ -5011,8 +5026,11 @@ A probe may specify up to twelve arguments. These are available at the
point at which the probe is defined---that is, when the current PC is
at the probe's location. The arguments are available using the
convenience variables (@pxref{Convenience Vars})
-@code{$_probe_arg0}@dots{}@code{$_probe_arg11}. Each probe argument is
-an integer of the appropriate size; types are not preserved. The
+@code{$_probe_arg0}@dots{}@code{$_probe_arg11}. In @code{SystemTap}
+probes each probe argument is an integer of the appropriate size;
+types are not preserved. In @code{DTrace} probes types are preserved
+provided that they are recognized as such by @value{GDBN}; otherwise
+the value of the probe argument will be a long integer. The
convenience variable @code{$_probe_argc} holds the number of arguments
at the current probe point.