[V2,8/9] Documentation for DTrace USDT probes.

Message ID 1412961772-16249-9-git-send-email-jose.marchesi@oracle.com
State Superseded
Headers

Commit Message

Jose E. Marchesi Oct. 10, 2014, 5:22 p.m. UTC
  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/ChangeLog:

  2014-10-10  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.
---
 gdb/doc/ChangeLog   |    8 +++++++
 gdb/doc/gdb.texinfo |   58 +++++++++++++++++++++++++++++++++------------------
 2 files changed, 46 insertions(+), 20 deletions(-)
  

Comments

Eli Zaretskii Oct. 10, 2014, 6:18 p.m. UTC | #1
> From: "Jose E. Marchesi" <jose.marchesi@oracle.com>
> Date: Fri, 10 Oct 2014 19:22:51 +0200
> 
> 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.

Thanks.

> -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

Please insert an empty line before each @item in the above list.

> +the semaphore.  @code{DTrace} probes do not support the notion of
> +semaphores.     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   ^^^^^^^^^^

I thought we agreed on a different wording of this.

> +probe being handled.  Some @code{DTrace} probes can be enabled or
> +disabled, but @code{SystemTap} probes do not support these notions.

Likewise here.
  
Jose E. Marchesi Oct. 11, 2014, 9:47 p.m. UTC | #2
Hi Eli.

    > -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
    
    Please insert an empty line before each @item in the above list.
    
    > +the semaphore.  @code{DTrace} probes do not support the notion of
    > +semaphores.     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
       ^^^^^^^^^^
    
    I thought we agreed on a different wording of this.
    
    > +probe being handled.  Some @code{DTrace} probes can be enabled or
    > +disabled, but @code{SystemTap} probes do not support these notions.
    
    Likewise here.

Somehow these changes missed the patches I sent.  Fixed in a new
series.  Thanks for noticing.
  

Patch

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index a9c70b0..8cf550a 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -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.