From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 5671 invoked by alias); 14 Jul 2009 23:09:57 -0000 Received: (qmail 5662 invoked by uid 22791); 14 Jul 2009 23:09:57 -0000 X-SWARE-Spam-Status: No, hits=-2.6 required=5.0 tests=BAYES_00 X-Spam-Check-By: sourceware.org Received: from e4.ny.us.ibm.com (HELO e4.ny.us.ibm.com) (32.97.182.144) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Tue, 14 Jul 2009 23:09:50 +0000 Received: from d01relay04.pok.ibm.com (d01relay04.pok.ibm.com [9.56.227.236]) by e4.ny.us.ibm.com (8.13.1/8.13.1) with ESMTP id n6EN4Ddr001394 for ; Tue, 14 Jul 2009 19:04:13 -0400 Received: from d01av02.pok.ibm.com (d01av02.pok.ibm.com [9.56.224.216]) by d01relay04.pok.ibm.com (8.13.8/8.13.8/NCO v9.2) with ESMTP id n6EN9ldm255094 for ; Tue, 14 Jul 2009 19:09:47 -0400 Received: from d01av02.pok.ibm.com (loopback [127.0.0.1]) by d01av02.pok.ibm.com (8.12.11.20060308/8.13.3) with ESMTP id n6EN7EtF031275 for ; Tue, 14 Jul 2009 19:07:14 -0400 Received: from skyhawk.localnet (skyhawk.austin.ibm.com [9.41.41.33]) by d01av02.pok.ibm.com (8.12.11.20060308/8.12.11) with ESMTP id n6EN7DfF031237 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Tue, 14 Jul 2009 19:07:13 -0400 From: Robb Romans To: systemtap@sourceware.org Subject: SystemTap Language Reference: Userspace probing patch Date: Tue, 14 Jul 2009 23:09:00 -0000 User-Agent: KMail/1.11.4 (Linux/2.6.28-13-generic; KDE/4.2.4; i686; ; ) Cc: Prerna Saxena MIME-Version: 1.0 Content-Type: Multipart/Mixed; boundary="Boundary-00=_5ARXKfo0ThAFuc8" Message-Id: <200907141809.45230.robb@linux.vnet.ibm.com> X-IsSubscribed: yes Mailing-List: contact systemtap-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Post: List-Help: , Sender: systemtap-owner@sourceware.org X-SW-Source: 2009-q3/txt/msg00104.txt.bz2 --Boundary-00=_5ARXKfo0ThAFuc8 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Content-Disposition: inline Content-length: 391 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 Regards, Robb -- Robb Romans IBM LTC Information Development robb@linux.vnet.ibm.com --Boundary-00=_5ARXKfo0ThAFuc8 Content-Type: text/x-patch; charset="UTF-8"; name="02-LangRef-userspace_probing.diff" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="02-LangRef-userspace_probing.diff" Content-length: 4717 commit 3d16ab00806872e7c23bc72025e9b340aec07878 Author: Robb Romans 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}} --Boundary-00=_5ARXKfo0ThAFuc8--