summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorRobb Romans <robb@linux.vnet.ibm.com>2009-06-26 14:25:56 -0500
committerJosh Stone <jistone@redhat.com>2009-07-01 16:39:19 -0700
commitf9573fe3e0e68f15ed61293e5567b5c4981c57f3 (patch)
treea5208f74a7217682999914a314d94a26f22365d3
parent3f6b6682ecfbdebefd93bfa503b8f6bd70fee005 (diff)
downloadsystemtap-steved-f9573fe3e0e68f15ed61293e5567b5c4981c57f3.tar.gz
systemtap-steved-f9573fe3e0e68f15ed61293e5567b5c4981c57f3.tar.xz
systemtap-steved-f9573fe3e0e68f15ed61293e5567b5c4981c57f3.zip
SystemTap Language Reference: DWARF-less probing patch
Here is a patch to the Language Reference Guide that adds information about DWARF-less probing. Signed-off-by: Robb Romans <robb@linux.vnet.ibm.com> Signed-off-by: Josh Stone <jistone@redhat.com>
-rw-r--r--doc/langref.tex60
1 files changed, 59 insertions, 1 deletions
diff --git a/doc/langref.tex b/doc/langref.tex
index 5a149d19..6bbd704f 100644
--- a/doc/langref.tex
+++ b/doc/langref.tex
@@ -53,7 +53,7 @@
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 IBM Corp.\newline
+Copyright \copyright\space 2007-2009 IBM Corp.\newline
Copyright \copyright\space 2007 Intel Corporation.\newline
Permission is granted to copy, distribute and/or modify this document
@@ -853,6 +853,64 @@ kernel.statement("bio_init@fs/bio.c+3")
\end{verbatim}
\end{vindent}
+
+\subsection{DWARF-less probing}
+\index{DWARF-less probing}
+
+In the absence of debugging information, you can still use the
+\emph{kprobe} family of probes to examine the entry and exit points of
+kernel and module functions. You cannot look up the arguments or local
+variables of a function using these probes. However, you can access
+the parameters by following this procedure:
+
+When you're stopped at the entry to a function, you can refer to the
+function's arguments by number. For example, when probing the function
+declared:
+
+\begin{vindent}
+\begin{verbatim}
+asmlinkage ssize_t sys_read(unsigned int fd, char __user * buf, size_t
+count)
+\end{verbatim}
+\end{vindent}
+
+You can obtain the values of \texttt{fd}, \texttt{buf}, and
+\texttt{count}, respectively, as \texttt{uint\_arg(1)},
+\texttt{pointer\_arg(2)}, and \texttt{ulong\_arg(3)}. In this case, your
+probe code must first call \texttt{asmlinkage()}, because on some
+architectures the asmlinkage attribute affects how the function's
+arguments are passed.
+
+When you're in a return probe, \texttt{\$return} isn't supported
+without DWARF, but you can call \texttt{returnval()} to get the value
+of the register in which the function value is typically returned, or
+call \texttt{returnstr()} to get a string version of that value.
+
+And at any code probepoint, you can call
+\texttt{{register("regname")}} to get the value of the specified CPU
+register when the probe point was hit.
+\texttt{u\_register("regname")} is like \texttt{register("regname")},
+but interprets the value as an unsigned integer.
+
+SystemTap supports the following constructs:
+\begin{vindent}
+\begin{verbatim}
+kprobe.function(FUNCTION)
+kprobe.function(FUNCTION).return
+kprobe.module(NAME).function(FUNCTION)
+kprobe.module(NAME).function(FUNCTION).return
+kprobe.statement.(ADDRESS).absolute
+\end{verbatim}
+\end{vindent}
+
+Use \textbf{.function} probes for kernel functions and
+\textbf{.module} probes for probing functions of a specified module.
+If you do not know the absolute address of a kernel or module
+function, use \textbf{.statement} probes. Do not use wildcards in
+\textit{FUNCTION} and \textit{MODULE} names. Wildcards cause the probe
+to not register. Also, run statement probes in guru mode only.
+
+
\begin{comment}
\subsection{Marker probes}