* SystemTap Language Reference: Userspace probing patch
@ 2009-07-14 23:09 Robb Romans
2009-07-15 23:11 ` Jim Keniston
0 siblings, 1 reply; 2+ messages in thread
From: Robb Romans @ 2009-07-14 23:09 UTC (permalink / raw)
To: systemtap; +Cc: Prerna Saxena
[-- Attachment #1: Type: text/plain, Size: 391 bytes --]
Hi,
Here is a patch that adds information about userspace probing to the
Language Reference Guide. Please review. I would like clarification on
the final paragraph about PATH. Is it correct? Thanks.
02-LangRef-userspace_probing.diff (attached)
Signed-off-by: Robb Romans <robb@linux.vnet.ibm.com>
Regards,
Robb
--
Robb Romans
IBM LTC Information Development
robb@linux.vnet.ibm.com
[-- Attachment #2: 02-LangRef-userspace_probing.diff --]
[-- Type: text/x-patch, Size: 4717 bytes --]
commit 3d16ab00806872e7c23bc72025e9b340aec07878
Author: Robb Romans <robb@linux.vnet.ibm.com>
Date: Tue Jul 14 13:55:37 2009 -0500
Add subsection about userspace probing.
diff --git a/doc/langref.tex b/doc/langref.tex
index 35ff331..210524e 100644
--- a/doc/langref.tex
+++ b/doc/langref.tex
@@ -50,7 +50,8 @@
\maketitle
\newpage{}
-This document was derived from other documents contributed to the SystemTap project by employees of Red Hat, IBM and Intel.\newline
+This document was derived from other documents contributed to the
+SystemTap project by employees of Red Hat, IBM and Intel.\newline
Copyright \copyright\space 2007 Red Hat Inc.\newline
Copyright \copyright\space 2007-2009 IBM Corp.\newline
@@ -1088,6 +1089,111 @@ read\_counter is a function passed to the handle for a perfmon probe. It
returns the current count for the event.
\end{comment}
+
+\subsection{Userspace probing}
+\index{userspace probing}
+
+Prototype support for \emph{userspace probing} is available in the
+form of the following non-symbolic probe point:
+
+\begin{vindent}
+\begin{verbatim}
+process(PID).statement(ADDRESS).absolute
+\end{verbatim}
+\end{vindent}
+
+This probe point is analogous to
+\texttt{kernel.statement(ADDRESS).absolute} in that both use raw
+(unverified) virtual addresses and provide no
+\texttt{\$variables}. The target PID parameter must identify a running
+process and ADDRESS must identify a valid instruction address. All
+threads of that process will be probed.
+
+Additional userspace probing is available in the following forms:
+
+\begin{vindent}
+\begin{verbatim}
+process(PID).begin
+process("PATH").begin
+process.begin
+process(PID).thread.begin
+process("PATH").thread.begin
+process.thread.begin
+process(PID).end
+process("PATH").end
+process.end
+process(PID).thread.end
+process("PATH").thread.end
+process.thread.end
+process(PID).syscall
+process("PATH").syscall
+process.syscall
+process(PID).syscall.return
+process("PATH").syscall.return
+process.syscall.return
+process(PID).itrace
+process("PATH").itrace
+process("PATH").mark("LABEL")
+\end{verbatim}
+\end{vindent}
+
+Here is how these probes are called:
+\begin{description}
+\item A \texttt{.begin} probe is called when a new process described
+ by PID or PATH is created.
+
+\item A \texttt{.thread.begin} probe is called when a new thread
+ described by PID or PATH is created.
+
+\item An \texttt{.end} probe is called when a process described by PID
+ or PATH dies.
+
+\item A \texttt{.thread.end} probe is called when a thread described
+ by PID or PATH dies.
+
+\item A \texttt{.syscall} probe is called when a thread described by
+ PID or PATH makes a system call. You can get the system call number
+ from the \texttt{\$syscall} context variable. You can get the first
+ six arguments of the system call from the \texttt{\$argN} context
+ variable. For example, use \texttt{\$arg1}, \texttt{\$arg2}, and so
+ on.
+
+\item A \texttt{.syscall.return} probe is called when a thread
+ described by PID or PATH returns from a system call. You can get the
+ system call number from the \texttt{\$syscall} context variable and
+ the return value of the system call from the \texttt{\$return}
+ context variable.
+
+\item An \texttt{.itrace} probe is called for every single step of
+ the process described by PID or PATH.
+
+\item A \texttt{.mark} probe is called from a static probe defined in
+ the application by the following statement:
+ \begin{vindent}
+\begin{verbatim}
+STAP_PROBE1(handle, LABEL, arg1)
+\end{verbatim}
+ \end{vindent}
+ This is defined in the sdt.h header file. The \texttt{handle} is an
+ application handle, LABEL corresponds to the \texttt{.mark}
+ argument, and \texttt{arg1} is the argument. Use STAP\_PROBE1 for
+ probes with one argument, STAP\_PROBE2 for probes with two
+ arguments, and so on. You can get the arguments of the probe from
+ the context variables\texttt{ \$arg1}, \texttt{\$arg2}, and so
+ on. You can use the STAP\_PROBE macros or use the dtrace script to
+ create custom macros.
+
+\item PATH names refer to executables that are searched for in the
+ same way that shells search for executables. That is, the translator
+ searches relative to the top-level directory if the command begins
+ with a slash (/) character or relative to the current directory if
+ the command begins with a dot-slash (./) sequence. If no preceding
+ slash or dot-slash is given, the translator looks for the executable
+ in the directories defined in the PATH variable. If you specify a
+ process probe without a PID or a PATH, all user threads are probed.
+\end{description}
+
+
\section{Language elements\label{sec:Language-Elements}}
^ permalink raw reply [flat|nested] 2+ messages in thread
* Re: SystemTap Language Reference: Userspace probing patch
2009-07-14 23:09 SystemTap Language Reference: Userspace probing patch Robb Romans
@ 2009-07-15 23:11 ` Jim Keniston
0 siblings, 0 replies; 2+ messages in thread
From: Jim Keniston @ 2009-07-15 23:11 UTC (permalink / raw)
To: Robb Romans; +Cc: systemtap, Prerna Saxena
On Tue, 2009-07-14 at 18:09 -0500, Robb Romans wrote:
> Hi,
>
> Here is a patch that adds information about userspace probing to the
> Language Reference Guide. Please review. I would like clarification on
> the final paragraph about PATH. Is it correct? Thanks.
>
> 02-LangRef-userspace_probing.diff (attached)
> Signed-off-by: Robb Romans <robb@linux.vnet.ibm.com>
>
>
> Regards,
> Robb
>
+Prototype support for \emph{userspace probing} is available in the
+form of the following non-symbolic probe point:
+
+\begin{vindent}
+\begin{verbatim}
+process(PID).statement(ADDRESS).absolute
+\end{verbatim}
+\end{vindent}
+
+This probe point is analogous to
+\texttt{kernel.statement(ADDRESS).absolute} in that both use raw
+(unverified) virtual addresses and provide no
+\texttt{\$variables}. The target PID parameter must identify a running
+process and ADDRESS must identify a valid instruction address. All
+threads of that process will be probed.
+
This (along with the stapprobes man page) seems about a year out of
date. Support for
probe process(PID).statement(ADDRESS).absolute
was dropped last summer, when Frank & co. added support for the
following:
probe process("PATH").function(PATTERN)
probe process("PATH").function(PATTERN).return
probe process("PATH").statement(PATTERN)
And pretty much all the context-variable constructs documented in the
(kernel) DWARF section above are also supported for user-space probes.
I'm no longer actively participating on the SystemTap team, but I doubt
that all this work has been backed out in the past couple of months.
You should probably get fche or dsmith to take a closer look at this.
Jim
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2009-07-15 23:11 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2009-07-14 23:09 SystemTap Language Reference: Userspace probing patch Robb Romans
2009-07-15 23:11 ` Jim Keniston
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).