This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
Forw: rroman: Re: [PATCH doc/langref.tex] Add pointer typecasting information
- From: "Frank Ch. Eigler" <fche at redhat dot com>
- To: systemtap at sources dot redhat dot com
- Date: Thu, 3 Sep 2009 14:56:50 -0400
- Subject: Forw: rroman: Re: [PATCH doc/langref.tex] Add pointer typecasting information
Hi -
Until we sort out some email problems with Robb, here's a note he's
been trying to get through:
----- Forwarded message from Robb Romans <robb@linux.vnet.ibm.com> -----
Date: Wed, 2 Sep 2009 18:14:28 -0500 (CDT)
From: Robb Romans <robb@linux.vnet.ibm.com>
To: systemtap@sources.redhat.com
Subject: Re: [PATCH doc/langref.tex] Add pointer typecasting information
(fwd)
Looks like the attachment may have blocked it from the list? Resending
without.
--
Robb Romans
IBM LTC Information Development
robb@linux.vnet.ibm.com
---------- Forwarded message ----------
Date: Wed, 2 Sep 2009 16:54:55 -0500 (CDT)
From: Robb Romans <robb@linux.vnet.ibm.com>
To: Josh Stone <jistone@redhat.com>
Cc: systemtap@sources.redhat.com, Prerna Saxena <prerna@linux.vnet.ibm.com>
Subject: Re: [PATCH doc/langref.tex] Add pointer typecasting information
On Tue, 1 Sep 2009, Josh Stone wrote:
>It may be that you were sent an old version of the manpage. @cast with
>multiple modules came in 0.9.5, and @casting headers came in 0.9.7.
>This is all in the main manpage, stap.1.in.
Thanks. Here's an updated patch. To make it easier to review, I've attached
a PDF of the formatted page.
Signed-off-by: Robb Romans <robb@linux.vnet.ibm.com>
---
doc/langref.tex | 66
++++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 files changed, 65 insertions(+), 1 deletions(-)
diff --git a/doc/langref.tex b/doc/langref.tex
index 3d08234..99827e3 100644
--- a/doc/langref.tex
+++ b/doc/langref.tex
@@ -1088,9 +1088,73 @@ 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->pid
+\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
--
1.6.0.4
--
Robb Romans
IBM LTC Information Development
robb@linux.vnet.ibm.com
----- End forwarded message -----