systemtap markers and gdb

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

Re: systemtap markers and gdb

[Phil Muldoon]

Tom Tromey <tromey@redhat.com> writes:

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

Why the catch syntax, and not just an addition to the linespec code so
that we can just set regular breakpoints on them?  It would be neat then
to interface with the upcoming condition/action python code. 

(Though I guess in mediation, though we have no catchpoint support in
the Python API at present, there is no reason that we cannot at some
point).

Cheers

Phil

Re: systemtap markers and gdb

[Tom Tromey]

Phil> Why the catch syntax, and not just an addition to the linespec code so
Phil> that we can just set regular breakpoints on them?  It would be neat then
Phil> to interface with the upcoming condition/action python code. 

We considered this but decided on catchpoints for two reasons.

First, we wanted to expose the marker arguments somehow.  Adding special
behavior to breakpoints for one kind of linespec seemed ugly.

Second, linespec.c is already too gross.


It occurs to me now that I don't know how we'll support letting the user
view the marker arguments outside of "commands".  Maybe instead of a
special convenience function we should just set a bunch of convenience
variables, or a single array-valued convenience variable.

Phil> (Though I guess in mediation, though we have no catchpoint support in
Phil> the Python API at present, there is no reason that we cannot at some
Phil> point).

Yeah, we will want to do that as part of this work.

Tom

Re: systemtap markers and gdb

[Roland McGrath]

There are three flavors of encoding from various different versions of
systemtap.  The nicest one is the most recent (aka v3), which is only
available in the forthcoming systemtap 1.4.  Are you supporting more
than one flavor, or only the latest flavor?  (I think it's fine to
support only this latest flavor.)

It's not clear if 'info markers' tells you what object the markers are
in.  I notice that there is no way to specify a constraint on which
objects you want 'info markers' or 'catch marker' to match.

In contrast, in the systemtap syntax you always say which objects you
want to look for a particular marker in.  It's probably most common that
a given provider name is only used in a single object.  But it doesn't
have to be so.  In particular, a library might provide markers in its
inlines and then those would appear under the library's choice of
provider name, but in the various objects that inlined its calls or
methods.  I suppose it's consistent with the rest of gdb's breakpoint
selection that you don't explicitly say which objects you are talking
about, but I thought I'd mention the issue.

> It occurs to me now that I don't know how we'll support letting the user
> view the marker arguments outside of "commands".  Maybe instead of a
> special convenience function we should just set a bunch of convenience
> variables, or a single array-valued convenience variable.

Given that the probe arguments are only positional (have no names), an
array makes the most sense at first blush.  OTOH, in the latest sdt.h
flavor, there is some nominal degree of type information on the
arguments.  I presume an array-valued convenience variable would have to
convert them all to a single type and hence lose that information
(though perhaps do signedness-aware conversion and so not lose anything
that really matters).  

Today, the type information consists of signedness and size (1,2,4,8)
and all arguments are integers (including pointers treated as
uintptr_t).  But it's possible that in the future the format will be
extended to describe FP types too, or be richer in other ways.  So you
probably don't want to expose a gdb interface now that would need to be
changed later for richer argument types.


Thanks,
Roland

Re: systemtap markers and gdb

[Tom Tromey]

Roland> There are three flavors of encoding from various different versions of
Roland> systemtap.  The nicest one is the most recent (aka v3), which is only
Roland> available in the forthcoming systemtap 1.4.  Are you supporting more
Roland> than one flavor, or only the latest flavor?  (I think it's fine to
Roland> support only this latest flavor.)

We are planning to only support the latest flavor.

Also, FWIW, we weren't planning to integrate this with the existing GDB
marker support.  That code only works for tracepoints and requires the
inferior to use UST.  I think we could do this integration, but my
impression is that right now we don't have many users using tracepoints
-- whereas we have some immediate uses for these catchpoints.

Roland> In contrast, in the systemtap syntax you always say which objects you
Roland> want to look for a particular marker in.  It's probably most common that
Roland> a given provider name is only used in a single object.  But it doesn't
Roland> have to be so.  In particular, a library might provide markers in its
Roland> inlines and then those would appear under the library's choice of
Roland> provider name, but in the various objects that inlined its calls or
Roland> methods.  I suppose it's consistent with the rest of gdb's breakpoint
Roland> selection that you don't explicitly say which objects you are talking
Roland> about, but I thought I'd mention the issue.

Thanks.  I will add an option argument to allow this kind of selection,
like:

    catch marker [objfile] provider name
    info markers [objfile] [provider [name]]

Tom> It occurs to me now that I don't know how we'll support letting the user
Tom> view the marker arguments outside of "commands".  Maybe instead of a
Tom> special convenience function we should just set a bunch of convenience
Tom> variables, or a single array-valued convenience variable.

Roland> Given that the probe arguments are only positional (have no names), an
Roland> array makes the most sense at first blush.  OTOH, in the latest sdt.h
Roland> flavor, there is some nominal degree of type information on the
Roland> arguments.  I presume an array-valued convenience variable would have to
Roland> convert them all to a single type and hence lose that information
Roland> (though perhaps do signedness-aware conversion and so not lose anything
Roland> that really matters).  

Yeah, they would have to all be the same size.

Roland> Today, the type information consists of signedness and size (1,2,4,8)
Roland> and all arguments are integers (including pointers treated as
Roland> uintptr_t).  But it's possible that in the future the format will be
Roland> extended to describe FP types too, or be richer in other ways.  So you
Roland> probably don't want to expose a gdb interface now that would need to be
Roland> changed later for richer argument types.

Thanks.

We can either just go with multiple convenience variables
($_marker_arg0, $_marker_arg1, etc) or a phony struct.  I lean toward
the former since it is simpler and since that is how `define' already
works.

Tom

Re: systemtap markers and gdb

[Tom Tromey]

Tom> Also, FWIW, we weren't planning to integrate this with the existing GDB
Tom> marker support.  That code only works for tracepoints and requires the
Tom> inferior to use UST.  I think we could do this integration, but my
Tom> impression is that right now we don't have many users using tracepoints
Tom> -- whereas we have some immediate uses for these catchpoints.

We were discussing this again on irc yesterday, and Roland had an
intriguing idea about how to handle marker arguments.

The main motivation for implementing marker support using a catchpoint
rather than a breakpoint with a new kind of linespec was that we want to
expose the marker arguments to scripts, but we didn't want to make this
dependent on the kind of linespec in use.

Roland's idea is to make this PC-based -- make the marker arguments
available at a marked PC, regardless of how one ended up at that PC.

So, I think we should change our plans back.  This means rewriting the
UI code on the branch, which I will do.

Using linespecs has a few nice features.  First, it doesn't require any
more Python API, it will all just work.  Ditto for the internal places
where we want to use stap markers (exceptions, longjmp).  Also, it seems
very easy to make marker arguments work with tracepoints.


I also looked at the exist UST-based static tracepoint markers, to see
if we could or should share anything.

From what I can tell, the UST work defines two additional commands: the
static tracepoint command ("strace" -- sigh) and "info
static-tracepoint-markers".

We won't need "strace", since our approach is more general.

"info static-tracepoint-markers" is like our "info markers", but it
includes some columns that are not relevant, and it doesn't seem to have
the notion that a given marker may resolve to more than one address.
So, while maybe we could use the same command, but I think in the first
patch we will not.  It isn't a perfect fit and its name makes it
tracepoint-specific besides.


I didn't rewrite the docs yet, but here is the new proposal.

First, a new linespec that looks like `marker:[OBJFILE]:PROVIDER:NAME'.
E.g.:  (gdb) break marker:glibc:pthread_create

I'll try to make this a bit generic so we could stick in new kinds of
linespec prefixes later.

Second, a bunch of convenience variables, $marker_argc, $marker_arg0
.. $marker_arg9.  These will always be visible, but will throw
exceptions unless the current PC is a marker PC.  These will include a
method to compile the reference to the AX bytecode.

Third, a new "info markers" command, as in the earlier proposal.


Let me know what you think.

Tom

Re: systemtap markers and gdb

[Roland McGrath]

As a (potential) user, that sounds reasonable to me.  

The other cool feature that would follow naturally from a user perspective
is an automagic display of a probe and its arguments at a probepoint.
That would be something that looks a bit like a frame display, e.g.:

#0  probe providername:probename ($arg1=123, $arg2=456)

Possibly this could be a "virtual frame" sort of thing, but most likely
people don't want it to obscure the actual frame that contains the probe.
It's more useful if it's just extra information displayed at the same times
you would display frame info (at a stop, at up/down/frame commands, etc.)
when the frame PC has a probe there.

Since a probe site is an extra nop instruction where the breakpoint goes,
it might actually be useful to display this at the instruction immediately
before it or immediately after it, or even on the source lines containing
the instructions right around it.  Or maybe something even fuzzier, where
it might not be able to show the probe argument values, e.g., if the probe
precedes or follows a call, then having "up" et al display what probe site
is right there could be nice, even if the probe arguments are clobbered by
the call, or are dependent on the call's return value.  Those ideas are all
extra gravy after direct support at the probe site PC itself, of course.

> First, a new linespec that looks like `marker:[OBJFILE]:PROVIDER:NAME'.

I assume that is actually `marker:[OBJFILE:]PROVIDER:NAME'.  Note that in
the stap syntaxes, specifying the PROVIDER part is also optional, since
some probe names are quite distinctive already.  So perhaps it should
really be `marker:[OBJFILE:][PROVIDER:]NAME'.  (And personally I would go
with "probe" rather than "marker", since the macros to create them are
called *_PROBE.  OTOH, the stap syntax is `[.provider("NAME")].mark("NAME")'.
Also note that in stap syntax, each NAME is actually a glob pattern.)

> E.g.:  (gdb) break marker:glibc:pthread_create

BTW, as currently proposed, the provider names for the glibc static probes
will be the library basename, i.e. libc or libpthread.

> Second, a bunch of convenience variables, $marker_argc, $marker_arg0
> .. $marker_arg9.  These will always be visible, but will throw
> exceptions unless the current PC is a marker PC.  These will include a
> method to compile the reference to the AX bytecode.

I'd prefer slightly less verbose names for the variables, but it's not a
significant issue.


Thanks,
Roland

Re: systemtap markers and gdb

[Tom Tromey]

Roland> The other cool feature that would follow naturally from a user
Roland> perspective is an automagic display of a probe and its arguments
Roland> at a probepoint.

Ok, I will look into this a bit.

Tom> First, a new linespec that looks like `marker:[OBJFILE]:PROVIDER:NAME'.

Roland> I assume that is actually `marker:[OBJFILE:]PROVIDER:NAME'.

Yes.

Roland> So perhaps it should really be
Roland> `marker:[OBJFILE:][PROVIDER:]NAME'.

Ok.

Roland> (And personally I would go with "probe" rather than "marker",
Roland> since the macros to create them are called *_PROBE.

I forget why we picked "marker" in the first place.  I don't mind
changing it.  Systemtap docs seem to use them interchangeably.

Tom

Re: systemtap markers and gdb

[Tom Tromey]

Tom> I didn't rewrite the docs yet, but here is the new proposal.

Here's my new doc patch.

Tom

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 7f8c785..a93ddf3 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -3304,6 +3304,7 @@ all breakpoints in that range are operated on.
 * Conditions::                  Break conditions
 * Break Commands::              Breakpoint command lists
 * Save Breakpoints::            How to save breakpoints in a file
+* Static Probe Points::         Listing static probe points
 * Error in Breakpoints::        ``Cannot insert breakpoints''
 * Breakpoint-related Warnings:: ``Breakpoint address adjusted...''
 @end menu
@@ -4517,6 +4518,49 @@ and remove the breakpoint definitions you're not interested in, or
 that can no longer be recreated.
 @end table
 
+@node Static Probe Points
+@subsection Static Probe Points
+
+@cindex SystemTap static probe point
+The @sc{gnu}/Linux tool @code{SystemTap} provides a way for
+applications to embed static probes.  @value{GDBN} can list the
+available probes, and you can put breakpoints at the probe points
+(@pxref{Specify Location}).
+
+You can examine the available @code{SystemTap} static probes using
+@code{info probes}:
+
+@table @code
+@kindex info probes
+@item info probes [@var{provider} [@var{name} [@var{objfile}]]]
+List the available @code{SystemTap} static probes.
+
+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
+probes to list.  If omitted, all probes are listed.
+
+If given, @var{objfile} is a regular expression used to select which
+object files (executable or shared libraries) to examine.  If not
+given, all object files are considered.
+@end table
+
+@vindex $_probe_arg@r{, convenience variable}
+A probe may specify up to ten 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_arg9}.  Each probe argument is
+an integer of the appropriate size; types are not preserved.  The
+convenience variable @code{$_probe_argc} holds the number of arguments
+at the current probe point.
+
+These variable are always available, but attempts to access them at
+any location other than a probe point will cause @value{GDBN} to give
+an error.
+
+
 @c  @ifclear BARETARGET
 @node Error in Breakpoints
 @subsection ``Cannot insert breakpoints''
@@ -6429,6 +6473,21 @@ specify the function unambiguously, e.g., if there are several
 functions with identical names in different source files.
 @end table
 
+@cindex SystemTap static probe point
+@item probe:@r{[}@var{objfile}:@r{]}@r{[}@var{provider}:@r{]}@var{name}
+The @sc{gnu}/Linux tool @code{SystemTap} provides a way for
+applications to embed static probes.  This form of linespec specifies
+the location of such a static probe.  See
+@uref{http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps}
+for more information on static probes.
+
+If @var{objfile} is given, only probes coming from that shared library
+or executable are considered.  If @var{provider} is given, then only
+probes from that provider are considered.
+
+@xref{Static Probe Points}, for more information on finding and using
+static probes.
+
 @end table
 
 
@@ -8503,6 +8562,10 @@ to match the format in which the data was printed.
 The variable @code{$_exitcode} is automatically set to the exit code when
 the program being debugged terminates.
 
+@item $_probe_argc
+@itemx $_probe_arg0@dots{}$_probe_arg9
+Arguments to a SystemTap static probe.  @xref{Static Probe Points}.
+
 @item $_sdata
 @vindex $_sdata@r{, inspect, convenience variable}
 The variable @code{$_sdata} contains extra collected static tracepoint

Re: systemtap markers and gdb

[Roland McGrath]

> I forget why we picked "marker" in the first place.  I don't mind
> changing it.  Systemtap docs seem to use them interchangeably.

I think it has to do with the history of similar features, which started in
the kernel variant of the implementation of the essentially similar scheme.
The first such thing the kernel had was called "markers", though the one
now in use there is called "tracepoints" (an unfortunate parallel invention
of the same term already used for something quite different in gdb).

Anyway, the aversion to the name "marker" is just my opinion.  You should
probably work out with Frank what the preferred terminology really is.


Thanks,
Roland