From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <archer-return-2293-listarch-archer=sourceware.org@sourceware.org>
Received: (qmail 11220 invoked by alias); 13 Jan 2011 15:39:20 -0000
Mailing-List: contact archer-help@sourceware.org; run by ezmlm
Sender: <archer@sourceware.org>
Precedence: bulk
List-Post: <mailto:archer@sourceware.org>
List-Help: <mailto:archer-help@sourceware.org>
List-Subscribe: <mailto:archer-subscribe@sourceware.org>
List-Id: <archer.sourceware.org>
Received: (qmail 10941 invoked by uid 22791); 13 Jan 2011 15:39:18 -0000
X-SWARE-Spam-Status: No, hits=-6.8 required=5.0
	tests=AWL,BAYES_00,RCVD_IN_DNSWL_HI,SPF_HELO_PASS,T_RP_MATCHES_RCVD
X-Spam-Check-By: sourceware.org
From: Tom Tromey <tromey@redhat.com>
To: Project Archer <archer@sourceware.org>
Subject: systemtap markers and gdb
Date: Thu, 13 Jan 2011 15:39:00 -0000
Message-ID: <m3wrm8g6eb.fsf@fleche.redhat.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
X-SW-Source: 2011-q1/txt/msg00011.txt.bz2

Sergio and I are working on letting gdb stop when a systemtap static
marker is hit.

I thought I would post the documentation for the user-facing bits for
comments.

The diff below is missing a little context.  The main new command is:

    catch marker PROVIDER NAME

Let me know what you think.

Tom

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 7f8c785..3b31704 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -4100,6 +4101,22 @@ and @sc{gnu}/Linux.
 A call to @code{vfork}.  This is currently only available for HP-UX
 and @sc{gnu}/Linux.
 
+@item marker @var{provider} @var{name}
+A @code{SystemTap} static marker was hit.
+
+The @sc{gnu}/Linux tool @code{SystemTap} provides a way for
+applications to embed static markers.  @value{GDBN} can detect when a
+marker was hit.
+
+The marker's arguments are available to any condition or commands
+attached to the catchpoint via the @code{_marker_arg} convenience
+function.  @xref{Convenience Vars}, for more information on
+convenience functions, or below for details on @code{_marker_arg}.
+
+@var{provider} and @var{name} specify the marker to be used.  See
+@uref{http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps}
+for more information on static markers.
+
 @end table
 
 @item tcatch @var{event}
@@ -4161,6 +4178,40 @@ a specific exception is raised.  You can use multiple conditional
 breakpoints to stop your program when any of a number of exceptions are
 raised.
 
+You can examine the available @code{SystemTap} static markers using
+@code{info markers}:
+
+@table @code
+@kindex info markers
+@item info markers [@var{provider} [@var{name}]]
+List the available @code{SystemTap} static markers.
+
+If given, @var{provider} is a regular expression used to select which
+providers to list.  If omitted, all providers are listed.
+
+If given, @var{name} is a regular expression used to select which
+markers to list.  If omitted, all markers are listed.
+@end table
+
+In the condition or commands for a @code{catch marker} catchpoint, you
+can use the @code{_marker_arg} convenience function to extract
+arguments:
+
+@table @code
+@kindex marker arguments
+@kindex _marker_arg convenience function
+@item _marker_arg (@var{n})
+Return the value of an argument to a @code{SystemTap} static marker.
+The argument @var{n} is an integer which indicates which argument to
+return.  Arguments are numbered starting from 0.
+
+The result will be an integer of the appropriate size; types are not
+preserved.
+
+A call to this function is only valid in the condition or commands of
+a @code{catch marker} catchpoint; in other contexts it will give an
+error.
+@end table
 
 @node Delete Breaks
 @subsection Deleting Breakpoints