Redistribute the Target Variable information

Redistribute the information about target variables in the manual. Also
added index entries for the information and edited the text.

diff --git a/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml
index 7077891065f658f1ee5ea7e08df8c36f1f8103ec..058dd71020f5c4f25d0aa8219273a08ae2659324 100644 (file)
--- a/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml
@@ -118,6 +118,134 @@ probe timer.ms(12345)
 </note>
        -->
 </section>
+
+<section id="targetvariables">
+       <title>Target Variables</title>
+
+<indexterm>
+<primary>handlers</primary>
+<secondary>target variables</secondary>
+</indexterm>
+
+<indexterm>
+<primary>target variables</primary>
+</indexterm>
+
+<para>
+The probe events that map to actual locations in the code (for example
+<command>kernel.function("<replaceable>function</replaceable>")</command>  and
+<command>kernel.statement("<replaceable>statement</replaceable>")</command>)
+allow the use of <emphasis>target variables</emphasis> to obtain the value of
+variables visible at that location in the code.
+You can use the -L option to list the target variable available at a
+probe point.
+If the debug information is installed for the running kernel,
+you can run the following command to find out what target variables
+are available for the <command>vfs_read</command> function:
+</para>
+
+<screen>stap -L 'kernel.function("vfs_read")'</screen>
+
+<para>
+This will yield something similar to the following:
+</para>
+
+<screen>kernel.function("vfs_read@fs/read_write.c:277") $file:struct file* $buf:char* $count:size_t $pos:loff_t*</screen>
+
+<para>
+Each target variable is proceeded by a <quote>$</quote> and 
+the type of the target variable follows the <quote>:</quote>.
+The kernel's <command>vfs_read</command> function has
+<command>$file</command> (pointer to structure describing the file),
+<command>$buf</command> (pointer to the userspace to store the read data),
+<command>$count</command> (number of bytes to read),
+and <command>$pos</command> (position to start reading from in the file)
+target variable at the entry to the function.
+</para>
+
+<para>
+SystemTap tracks the typing information of the target variable and can
+examine the fields of a structure with the <command>-></command> operator.
+The <command>-></command> operator can be chained to look at data structures
+contained within data structures and follow pointers to other data structures.
+The <command>-></command> operator will obtain the value in the field of the
+structure.
+The <command>-></command> operator is used regardless whether accessing a field
+in a substructure or accessing another structure through a pointer.
+</para>
+
+<para>
+For pointers to base types such as integers and strings
+there are a number of functions listed below to access kernel-space data.
+The first argument for each functions is the pointer to the data item.
+Similar functions are described in <xref linkend="utargetvariable"/> for
+accessing target variables in user-space code.
+</para>
+
+<variablelist>
+
+<varlistentry>
+<term>kernel_char(<replaceable>address</replaceable>)</term>
+<listitem>
+<para>
+Obtain the character at <replaceable>address</replaceable> from kernel memory.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>kernel_short(<replaceable>address</replaceable>)</term>
+<listitem>
+<para>
+Obtain the short at <replaceable>address</replaceable> from kernel memory.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>kernel_int(<replaceable>address</replaceable>)</term>
+<listitem>
+<para>
+Obtain the int at <replaceable>address</replaceable> from kernel memory.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>kernel_long(<replaceable>address</replaceable>)</term>
+<listitem>
+<para>
+Obtain the long at <replaceable>address</replaceable> from kernel memory
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>kernel_string(<replaceable>address</replaceable>)</term>
+<listitem>
+<para>
+Obtain the string at <replaceable>address</replaceable> from kernel memory.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>kernel_string_n(<replaceable>address</replaceable>, <replaceable>n</replaceable>)</term>
+<listitem>
+<para>
+Obtain the string at <replaceable>address</replaceable> from the kernel memory
+and limits the string to <replaceable>n</replaceable> bytes.
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+<!-- FIXME should mention the $$arg, $$parms, pretty printing -->
+
+
+</section>
+
 <section id="handlerconditionalstatements">
        <title>Conditional Statements</title>
 <indexterm>

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Userspace_probing.xml b/doc/SystemTap_Beginners_Guide/en-US/Userspace_probing.xml
index c811b8e4d42355a29bcff61f5fb78f3c4b370ff7..3a2af0675ffb1cac567b6414a251d4dad09da57f 100644 (file)
--- a/doc/SystemTap_Beginners_Guide/en-US/Userspace_probing.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Userspace_probing.xml
@@ -55,6 +55,11 @@ If this occurs, you need to generate a uprobes.ko module for the kernel as direc
 <section id="uevents">
        <title>User-Space Events</title>
 
+<indexterm>
+<primary>Events</primary>
+<secondary>user-space</secondary>
+</indexterm>
+
 <para>
 All user-space event probes begin with <emphasis>process</emphasis>.
 The process events can be limited to a specific running process by specifying the process ID.
@@ -93,8 +98,8 @@ and <command>.return</command> suffix.
 <term>process("<replaceable>PATH</replaceable>").statement("<replaceable>statement</replaceable>")</term>
 <listitem>
 <para>
-The earliest instruction in the code for <replaceable>statement</replaceable>. This is the user-space analogue of the
-<command>kernel.statement("<replaceable>statement</replaceable>)</command>.
+The earliest instruction in the code for <replaceable>statement</replaceable>. This is the user-space analogue of 
+<command>kernel.statement("<replaceable>statement</replaceable>")</command>.
 </para>
 </listitem>
 </varlistentry>
@@ -174,48 +179,20 @@ executable.</para>
 
 </section>
 
-<section id="ufunctions">
-       <title>Accessing User-Space Data</title>
-
-<para>
-The probe events that map to actual locations in the user-space code  
-(<command>process("<replaceable>PATH</replaceable>").function("<replaceable>function</replaceable>")</command>  and
-<command>process("<replaceable>PATH</replaceable>").statement("<replaceable>statement</replaceable>")</command>)
-allow the use of <emphasis>target variables</emphasis> to obtain the value of user-space variables
-available at the probe.
-You can use the -L option to list the target variable available at a
-probe point.
-If the debug information is installed for the ls command,
-you can run the following command to find out what target variables are available for the <command>main</command> function:
-</para>
-
-<screen>stap -L 'process("/bin/ls").function("main")'</screen>
-
-<para>
-This will yield something similar to the following:
-</para>
-
-<screen>process("/bin/ls").function("main@/usr/src/debug/coreutils-8.4/src/ls.c:1230") $argc:int $argv:char** $sig:int[] const $__PRETTY_FUNCTION__:char[] const</screen>
+<section id="utargetvariable">
+       <title>Accessing User-Space Target Variables</title>
 
-<para>
-Each target variables is proceeded by a '$' and 
-the type of the target variable follows the ':'.
-In C code the <command>main</command> function has two standard arguments,
-<command>$argc</command> (the number of command line arguments) and
-<command>$argv</command> (an array of strings with the argument values)
-passed into the function.
-The <command>$sig</command> is a static variable within the function and
-function.
-<command>$__PRETTY_FUNCTION__</command> is a variable used by the assert
-function.
-</para>
+<indexterm>
+<primary>target variables</primary>
+<secondary>user-space</secondary>
+</indexterm>
 
 <para>
-SystemTap tracks the typing information of the target variable and can
-examine the fields of a structure with the "->" operator.
-The "->" operator can be chained to look at data structures contained
-within data structures and follow pointers to other data structures.
-The "->" operator will print the value in the field of the structure.
+User-space target variables can be accessed in the same manner as described in
+<xref linkend="targetvariables"/>.
+However, in Linux there are separate address spaces for the user and
+kernel code.
+When using "->" operator SystemTap will access the appropriate address space.
 For pointers to base types such as integers and strings
 there are a number of functions listed below to access user-space data.
 The first argument for each functions is the pointer to the data item.
@@ -285,8 +262,6 @@ user process and limits the string to <replaceable>n</replaceable> bytes.
 
 </variablelist>
 
-<!-- FIXME should mention the $$arg, $$parms, pretty printing -->
-
 </section>
 
 <!--