SystemTap Language Reference: Userspace probing patch

[Robb Romans <robb at linux dot vnet dot ibm dot com>]

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

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