From 6d8f08ed5132777fe772555ab7870d080c745671 Mon Sep 17 00:00:00 2001
From: Robb Romans <robb@linux.vnet.ibm.com>
Date: Tue, 8 Sep 2009 15:15:37 -0500
Subject: Add error probe information.

---
 doc/langref.tex | 35 +++++++++++++++++++++++++++--------
 1 file changed, 27 insertions(+), 8 deletions(-)

(limited to 'doc/langref.tex')

diff --git a/doc/langref.tex b/doc/langref.tex
index 3d08234d..eb5393bd 100644
--- a/doc/langref.tex
+++ b/doc/langref.tex
@@ -1031,14 +1031,33 @@ of an \texttt{exit} function call, or an interruption from the user. In the
 case of an shutdown triggered by error, \texttt{end} probes are not run.
 
 
-\subsubsection{begin and end probe sequence}
-\index{sequence}
-\texttt{begin} and \texttt{end} probes are specified with an optional sequence
-number that controls the order in which they are run. If no sequence number
-is provided, the sequence number defaults to zero and probes are run in the
-order that they occur in the script file. Sequence numbers may be either
-positive or negative, and are especially useful for tapset writers who want
-to do initialization in a \texttt{begin} probe. The following are examples.
+\subsubsection{error}
+\index{error}
+The \emph{error} probe point is similar to the end
+probe, except the probe handler runs when the session ends if an error
+occurred.  In this case, an \texttt{end} probe is skipped, but each
+\texttt{error} probe is still attempted.  You can use an
+\texttt{error} probe to clean up or perform a final action on script
+termination.
+
+Here is a simple example:
+\begin{vindent}
+\begin{verbatim}
+probe error { println ("Oops, errors occurred. Here's a report anyway.")
+              foreach (coin in mint) { println (coin) } }
+\end{verbatim}
+\end{vindent}
+
+
+\subsubsection{begin, end, and error probe sequence}
+\index{probe sequence}
+\texttt{begin}, \texttt{end}, and \texttt{error} probes can be
+specified with an optional sequence number that controls the order in
+which they are run. If no sequence number is provided, the sequence
+number defaults to zero and probes are run in the order that they
+occur in the script file. Sequence numbers may be either positive or
+negative, and are especially useful for tapset writers who want to do
+initialization in a \texttt{begin} probe. The following are examples.
 
 \begin{vindent}
 \begin{verbatim}
-- 
cgit 


From 0f99bb4fc41f9b81f2bea9cf637d942898d3d3af Mon Sep 17 00:00:00 2001
From: Robb Romans <robb@linux.vnet.ibm.com>
Date: Tue, 8 Sep 2009 15:34:10 -0500
Subject: Add pointer typecasting information to Language Reference.

---
 doc/langref.tex | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 66 insertions(+), 1 deletion(-)

(limited to 'doc/langref.tex')

diff --git a/doc/langref.tex b/doc/langref.tex
index eb5393bd..92081730 100644
--- a/doc/langref.tex
+++ b/doc/langref.tex
@@ -1107,9 +1107,74 @@ read\_counter is a function passed to the handle for a perfmon probe. It
 returns the current count for the event.
 \end{comment}
 
-\section{Language elements\label{sec:Language-Elements}}
+\subsection{Pointer typecasting}
+\index{Pointer typecasting}
+
+\emph{Typecasting} is supported using the \texttt{@cast()} operator. A
+script can define a pointer type for a \emph{long} value, then access
+type members using the same syntax as with \texttt{\$target}
+variables. After a pointer is saved into a script integer variable,
+the translator loses the necessary type information to access members
+from that pointer.  The \texttt{@cast()} operator tells the translator
+how to read a pointer.
+
+The following statement interprets \texttt{p} as a pointer to a struct
+or union named \texttt{type\_name} and dereferences the
+\texttt{member} value:
+\begin{vindent}
+\begin{verbatim}
+@cast(p, "type_name"[, "module"])->member
+\end{verbatim}
+\end{vindent}
+
+The optional \texttt{module} parameter tells the translator where to
+look for information about that type. You can specify multiple modules
+as a list with colon (\texttt{:}) separators. If you do not specify
+the module parameter, the translator defaults to either the probe
+module for dwarf probes or to \textit{kernel} for functions and all
+other probe types.
+
+The following statement retrieves the parent PID from a kernel
+task\_struct:
+\begin{vindent}
+\begin{verbatim}
+@cast(pointer, "task_struct", "kernel")->parent->tgid
+\end{verbatim}
+\end{vindent}
 
+The translator can create its own module with type information from a
+header surrounded by angle brackets (\texttt{< >}) if normal debugging
+information is not available.  For kernel headers, prefix it with
+\texttt{kernel} to use the appropriate build system.  All other
+headers are built with default GCC parameters into a user module. The
+following statements are examples.
+\begin{vindent}
+\begin{verbatim}
+@cast(tv, "timeval", "<sys/time.h>")->tv_sec
+@cast(task, "task_struct", "kernel<linux/sched.h>")->tgid
+\end{verbatim}
+\end{vindent}
 
+In guru mode, the translator allows scripts to assign new values to
+members of typecasted pointers.
+
+Typecasting is also useful in the case of \texttt{void*} members whose
+type might be determinable at run time.
+\begin{vindent}
+\begin{verbatim}
+probe foo {
+   if ($var->type == 1) {
+      value = @cast($var->data, "type1")->bar
+   } else {
+      value = @cast($var->data, "type2")->baz
+   }
+   print(value)
+}
+\end{verbatim}
+\end{vindent}
+
+
+\section{Language elements\label{sec:Language-Elements}}
 \subsection{Identifiers}
 \index{identifiers}
 \emph{Identifiers} are used to name variables and functions. They are an
-- 
cgit 


From eaec8e2b4cf10fc293a0cb2524692ae25a810ec9 Mon Sep 17 00:00:00 2001
From: Robb Romans <robb@linux.vnet.ibm.com>
Date: Wed, 9 Sep 2009 11:49:19 -0500
Subject: Update marker probe information in Language Reference.

Signed-off-by: Robb Romans <robb@linux.vnet.ibm.com>
---
 doc/langref.tex | 56 ++++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 38 insertions(+), 18 deletions(-)

(limited to 'doc/langref.tex')

diff --git a/doc/langref.tex b/doc/langref.tex
index 92081730..aa583c2e 100644
--- a/doc/langref.tex
+++ b/doc/langref.tex
@@ -911,26 +911,46 @@ function, use \textbf{.statement} probes. Do not use wildcards in
 to not register. Also, run statement probes in guru mode only.
 
 
-\begin{comment}
 \subsection{Marker probes}
+\index{marker probes}
+This family of probe points connects to static probe markers inserted
+into the kernel or a module. These markers are special macro calls in
+the kernel that make probing faster and more reliable than with
+DWARF-based probes.  DWARF debugging information is not required to
+use probe markers.
+
+Marker probe points begin with a \texttt{kernel} prefix which
+identifies the source of the symbol table used for finding
+markers. The suffix names the marker itself:
+\texttt{mark.("MARK")}. The marker name string, which can contain
+wildcard characters, is matched against the names given to the marker
+macros when the kernel or module is compiled.  Optionally, you can
+specify \texttt{format("FORMAT")}.  Specifying the marker format
+string allows differentiation between two markers with the same name
+but different marker format strings.
+
+The handler associated with a marker probe reads any optional
+parameters specified at the macro call site named \texttt{\$arg1}
+through \texttt{\$argNN}, where \texttt{NN} is the number of
+parameters supplied by the macro. Number and string parameters are
+passed in a type-safe manner.
+
+The marker format string associated with a marker is available in
+\texttt{\$format}. The marker name string is available in
+\texttt{\$name}.
+
+Here are the marker probe constructs:
+\begin{vindent}
+\begin{verbatim}
+kernel.mark("MARK")
+kernel.mark("MARK").format("FORMAT")
+\end{verbatim}
+\end{vindent}
+
+For more information about marker probes, see
+\url{http://sourceware.org/systemtap/wiki/UsingMarkers}.
+
 
-This family of probe points connects to static probe markers inserted into
-the kernel or a module. These markers are special macro calls in the kernel
-that make probing faster and more reliable than with DWARF-based probes.
-DWARF debugging information is not required to use probe markers.
-
-Marker probe points begin with a kernel or module(\char`\"{}\emph{name}\char`\"{})
-prefix, the same as DWARF probes. This prefix identifies the source of the
-symbol table used for finding markers. The suffix names the marker itself:
-mark(\char`\"{}\emph{name}\char`\"{}). The marker name string, which may
-contain wildcard characters, is matched against the names given to the marker
-macros when the kernel or module was compiled.
-
-The handler associated with a marker probe reads any optional parameters
-specified at the macro call site named \$arg1 through \$argNN, where NN is
-the number of parameters supplied by the macro. Number and string parameters
-are passed in a type-safe manner.
-\end{comment}
 
 \subsection{Timer probes}
 \index{timer probes}
-- 
cgit 


From f3e3c3e3863523382df6b7d07b57b16ef43546db Mon Sep 17 00:00:00 2001
From: Josh Stone <jistone@redhat.com>
Date: Tue, 15 Sep 2009 12:46:22 -0700
Subject: Fix some probe examples in the language reference

* doc/langref.tex (section{Components of a SystemTap script}): Use
  .call/.return for the example of tracing function entry/exit.  Also
  mention "-l" for listing probeable functions.
  (subsection{Embedded C functions}): Close the examples with '%}'.
---
 doc/langref.tex | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

(limited to 'doc/langref.tex')

diff --git a/doc/langref.tex b/doc/langref.tex
index aa583c2e..e460defd 100644
--- a/doc/langref.tex
+++ b/doc/langref.tex
@@ -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
-- 
cgit 


From 24fcff20ed7a4a9f2b772c572db28ee8df49161f Mon Sep 17 00:00:00 2001
From: Josh Stone <jistone@redhat.com>
Date: Tue, 15 Sep 2009 13:19:41 -0700
Subject: Update the langref copyright notice

---
 doc/langref.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/langref.tex')

diff --git a/doc/langref.tex b/doc/langref.tex
index e460defd..9a56e5f2 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
 
-- 
cgit 

