1 files changed, 118 insertions, 8 deletions
diff --git a/doc/langref.tex b/doc/langref.tex
index aa583c2e..29de4534 100644
--- a/doc/langref.tex
+++ b/doc/langref.tex
@@ -52,7 +52,7 @@
 \newpage{}
 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 Red Hat Inc.\newline
 Copyright \copyright\space  2007-2009 IBM Corp.\newline
 Copyright \copyright\space  2007 Intel Corporation.\newline
 
@@ -327,18 +327,17 @@ two probes.
 
 \begin{vindent}
 \begin{verbatim}
-probe kernel.function("sys_mkdir") { log ("enter") }
+probe kernel.function("sys_mkdir").call { log ("enter") }
 probe kernel.function("sys_mkdir").return { log ("exit") }
 \end{verbatim}
 \end{vindent}
 
-To list the probe-able functions in the kernel, use the last-pass option
-to the translator. The output needs to be filtered because each inlined function
-instance is listed separately. The following statement is an example.
+To list the probe-able functions in the kernel, use the listing option
+(\texttt{\textbf{-l}}).  For example:
 
 \begin{vindent}
 \begin{verbatim}
-# stap -p2 -e 'probe kernel.function("*") {}' | sort | uniq
+# stap -l 'kernel.function("*")' | sort
 \end{verbatim}
 \end{vindent}
 
@@ -601,11 +600,11 @@ are examples.
 \begin{verbatim}
 function add_one (val) %{
     THIS->__retvalue = THIS->val + 1;
-}
+%}
 function add_one_str (val) %{
     strlcpy (THIS->__retvalue, THIS->val, MAXSTRINGLEN);
     strlcat (THIS->__retvalue, "one", MAXSTRINGLEN);
-}
+%}
 \end{verbatim}
 \end{vindent}
 The function argument and return value types must be inferred by the translator
@@ -911,6 +910,48 @@ function, use \textbf{.statement} probes. Do not use wildcards in
 to not register. Also, run statement probes in guru mode only.
 
 
+\subsection{PROCFS probes}
+\index{PROCFS probes}
+
+These probe points allow procfs pseudo-files in
+\texttt{/proc/systemtap/\textit{MODNAME}} to be created, read and
+written.  Specify the name of the systemtap module as
+\texttt{\textit{MODNAME}}.  There are four probe point variants
+supported by the translator:
+\begin{vindent}
+\begin{verbatim}
+procfs("PATH").read
+procfs("PATH").write
+procfs.read
+procfs.write
+\end{verbatim}
+\end{vindent}
+
+\texttt{PATH} is the file name to be created, relative to
+\texttt{/proc/systemtap/MODNAME}.  If no \texttt{PATH} is specified
+(as in the last two variants in the previous list), \texttt{PATH}
+defaults to "command".
+
+When a user reads \texttt{/proc/systemtap/MODNAME/PATH}, the
+corresponding procfs read probe is triggered.  Assign the string data
+to be read to a variable named \texttt{\$value}, as follows:
+\begin{vindent}
+\begin{verbatim}
+procfs("PATH").read { $value = "100\n" }
+\end{verbatim}
+\end{vindent}
+
+When a user writes into \texttt{/proc/systemtap/MODNAME/PATH}, the
+corresponding procfs write probe is triggered.  The data the user
+wrote is available in the string variable named \texttt{\$value}, as
+follows:
+\begin{vindent}
+\begin{verbatim}
+procfs("PATH").write { printf("User wrote: %s", $value) }
+\end{verbatim}
+\end{vindent}
+
+
 \subsection{Marker probes}
 \index{marker probes}
 This family of probe points connects to static probe markers inserted
@@ -951,6 +992,75 @@ For more information about marker probes, see
 \url{http://sourceware.org/systemtap/wiki/UsingMarkers}.
 
 
+\subsection{Syscall probes}
+\label{sec:syscall}
+\index{syscall probes}
+The \texttt{syscall.*}  aliases define several hundred probes.  They
+use the following syntax:
+\begin{vindent}
+\begin{verbatim}
+syscall.NAME
+syscall.NAME.return
+\end{verbatim}
+\end{vindent}
+
+Generally, two probes are defined for each normal system call as
+listed in the syscalls(2) manual page: one for entry and one for
+return.   System calls that never return do not have a
+corresponding \texttt{.return} probe.
+
+Each probe alias defines a variety of variables. Look at the tapset
+source code to find the most reliable source of variable definitions.
+Generally, each variable listed in the standard manual page is
+available as a script-level variable. For example,
+\texttt{syscall.open} exposes file name, flags, and mode.  In addition,
+a standard suite of variables is available at most aliases, as follows:
+
+\begin{itemize}
+\item \texttt{argstr}: A pretty-printed form of the entire argument
+  list, without parentheses.
+\item \texttt{name}: The name of the system call.
+\item \texttt{retstr}: For return probes, a pretty-printed form of the
+  system call result.
+\end{itemize}
+
+Not all probe aliases obey all of these general guidelines.  Please
+report exceptions that you encounter as a bug.
+
+
+\subsection{Tracepoints}
+\label{sec:tracepoints}
+\index{tracepoints}
+
+This family of probe points hooks to static probing tracepoints
+inserted into the kernel or kernel modules.  As with marker probes,
+these tracepoints are special macro calls inserted by kernel
+developers to make probing faster and more reliable than with
+DWARF-based probes.  DWARF debugging information is not required to
+probe tracepoints.  Tracepoints have more strongly-typed parameters
+than marker probes.
+
+Tracepoint probes begin with \texttt{kernel}.  The next part names the
+tracepoint itself: \texttt{trace("name")}.  The tracepoint
+\texttt{name} string, which can contain wildcard characters, is
+matched against the names defined by the kernel developers in the
+tracepoint header files.
+
+The handler associated with a tracepoint-based probe can read the
+optional parameters specified at the macro call site.  These
+parameters are named according to the declaration by the tracepoint
+author.  For example, the tracepoint probe
+\texttt{kernel.trace("sched\_switch")} provides the parameters
+\texttt{\$rq}, \texttt{\$prev}, and \texttt{\$next}.  If the parameter
+is a complex type such as a struct pointer, then a script can access
+fields with the same syntax as DWARF \texttt{\$target} variables.
+Tracepoint parameters cannot be modified; however, in guru mode a
+script can modify fields of parameters.
+
+The name of the tracepoint is available in \texttt{\$\$name}, and a
+string of \texttt{name=value} pairs for all parameters of the
+tracepoint is available in \texttt{\$\$vars} or \texttt{\$\$parms}.
+
 
 \subsection{Timer probes}
 \index{timer probes}