From patchwork Fri Oct 10 17:22:51 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Jose E. Marchesi" X-Patchwork-Id: 3197 Received: (qmail 32137 invoked by alias); 10 Oct 2014 17:18:15 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Delivered-To: mailing list gdb-patches@sourceware.org Received: (qmail 31981 invoked by uid 89); 10 Oct 2014 17:18:15 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.2 required=5.0 tests=AWL, BAYES_00, LIKELY_SPAM_BODY, RP_MATCHES_RCVD, SPF_PASS, UNPARSEABLE_RELAY autolearn=no version=3.3.2 X-HELO: userp1040.oracle.com Received: from userp1040.oracle.com (HELO userp1040.oracle.com) (156.151.31.81) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES256-SHA encrypted) ESMTPS; Fri, 10 Oct 2014 17:18:11 +0000 Received: from ucsinet21.oracle.com (ucsinet21.oracle.com [156.151.31.93]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id s9AHI9q9029155 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Fri, 10 Oct 2014 17:18:10 GMT Received: from aserz7021.oracle.com (aserz7021.oracle.com [141.146.126.230]) by ucsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s9AHI8iQ011733 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Fri, 10 Oct 2014 17:18:09 GMT Received: from abhmp0008.oracle.com (abhmp0008.oracle.com [141.146.116.14]) by aserz7021.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s9AHI8QQ025865 for ; Fri, 10 Oct 2014 17:18:08 GMT Received: from termi.uk.oracle.com (/10.175.211.52) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Fri, 10 Oct 2014 10:18:08 -0700 From: "Jose E. Marchesi" To: gdb-patches@sourceware.org Subject: [PATCH V2 8/9] Documentation for DTrace USDT probes. Date: Fri, 10 Oct 2014 19:22:51 +0200 Message-Id: <1412961772-16249-9-git-send-email-jose.marchesi@oracle.com> In-Reply-To: <1412961772-16249-1-git-send-email-jose.marchesi@oracle.com> References: <1412961772-16249-1-git-send-email-jose.marchesi@oracle.com> X-IsSubscribed: yes 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 * 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(-) 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.