systemtap markers and gdb

[Tom Tromey]

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