revisions as per dsmith

4 files changed, 61 insertions, 25 deletions

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml b/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml
index 32fdf021..f63d1d70 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml
@@ -30,7 +30,12 @@ foo[execname()] = gettimeofday_s()
 </section>
 <section id="arrayops-readvalues">
 	<title>Reading Values From Arrays</title>
-	<para>You can also use the <command>=</command> operator to read values from an array. This is accomplished by simply including the <command><replaceable>array_name</replaceable>[<replaceable>index_expression</replaceable>]</command> as an element in a mathematical expression. For example:</para>
+	<para>You can also read values from an array the same way you would read the value of a variable. 
+	To do so, include the  
+	<command><replaceable>array_name</replaceable>[<replaceable>index_expression</replaceable>]</command> 
+	statement as an element in a mathematical expression. For example:</para>	
+<!--	
+	<para>You can also use the <command>=</command> operator to read values from an array. This is accomplished by simply including the <command><replaceable>array_name</replaceable>[<replaceable>index_expression</replaceable>]</command> as an element in a mathematical expression. For example:</para>-->
 
 <example id="arrayreadingvaluesfrom">
 	<title>Using Array Values in Simple Computations</title>
@@ -187,7 +192,9 @@ probe timer.s(2)
 	foreach (count in reads+) 
 		printf("%s : %d \n", count, reads[count])
 	if(reads["stapio"] >= 20)
-	{exit()}
+	{
+		exit()
+	}
 }
 </programlisting>
 </example>
@@ -221,7 +228,8 @@ probe timer.s(2)
 	foreach (count in reads+) 
 		printf("%s : %d \n", count, reads[count])
 	if(["stapio"] in reads)
-	{printf("stapio read detected, exiting\n")
+	{
+		printf("stapio read detected, exiting\n")
 		exit()
 	}
 }
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
index 99d57867..568cb74c 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
@@ -63,6 +63,14 @@
       <listitem><para><filename>kernel-devel</filename></para></listitem>
     </itemizedlist>
 
+	<para>
+	    Likewise, the necessary packages for the PAE kernel would be 
+	    <filename>kernel-PAE-debuginfo</filename>, <filename>kernel-PAE-debuginfo-common</filename>,
+	    and <filename>kernel-PAE-devel</filename>.
+	</para>
+		    
+
+    
     <para> To determine what kernel your system is currently using, use:</para>
 		
 <screen>
@@ -82,12 +90,18 @@ uname -r
       <title>Important</title>
 	
       <para>
-	The version and architecture of the <filename>-devel</filename>, <filename>-debuginfo</filename> and <filename>-debuginfo-common</filename> packages must match the kernel you wish to probe with SystemTap <emphasis>exactly</emphasis>.
+	The version, variant, and architecture of the <filename>-devel</filename>, <filename>-debuginfo</filename> and <filename>-debuginfo-common</filename> packages must match the kernel you wish to probe with SystemTap <emphasis>exactly</emphasis>.
       </para>
     </important>
 
 <para>
-	To help ease your deployment of SystemTap, you can use <xref linkend="stapprep"/>. You can use <xref linkend="stapprep"/> to detemine the kernel information packages you need to install in order to run SystemTap. If you run <xref linkend="stapprep"/> (as an ordinary, non-root user) without any arguments, it will display the kernel information packages required for the <emphasis>loaded</emphasis> kernel. You can also pass a specific kernel version to <xref linkend="stapprep"/>  (e.g. <computeroutput>2.6.18-92.el5</computeroutput>) if you wish to probe a kernel that is not currently loaded.
+	To help ease your deployment of SystemTap, you can use <xref linkend="stapprep"/>. 
+	<xref linkend="stapprep"/> determines the kernel information packages you need to install in order
+	to run SystemTap. If you run <xref linkend="stapprep"/> (as an ordinary, non-root user) without 
+	any arguments, it will display the kernel information packages required for the 
+	<emphasis>loaded</emphasis> kernel. You can also pass a specific kernel version to 
+	<xref linkend="stapprep"/>  (e.g. <computeroutput>2.6.18-92.el5</computeroutput>) if you wish 
+	to probe a kernel that is not currently loaded.
 </para>
 
 <note>
@@ -176,13 +190,13 @@ Once you have manually downloaded the required packages to the machine, install
     </para>-->
 
 <screen>
-Pass 1: parsed user script and 45 library script(s) in 340usr/0sys/358real ms.

-Pass 2: analyzed script: 1 probe(s), 1 function(s), 0 embed(s), 0 global(s) in 290usr/260sys/568real ms.

-Pass 3: translated to C into "/tmp/stapiArgLX/stap_e5886fa50499994e6a87aacdc43cd392_399.c" in 490usr/430sys/938real ms.

-Pass 4: compiled C into "stap_e5886fa50499994e6a87aacdc43cd392_399.ko" in 3310usr/430sys/3714real ms.

-Pass 5: starting run.

-read performed

-Pass 5: run completed in 10usr/40sys/73real ms.

+Pass 1: parsed user script and 45 library script(s) in 340usr/0sys/358real ms.
+Pass 2: analyzed script: 1 probe(s), 1 function(s), 0 embed(s), 0 global(s) in 290usr/260sys/568real ms.
+Pass 3: translated to C into "/tmp/stapiArgLX/stap_e5886fa50499994e6a87aacdc43cd392_399.c" in 490usr/430sys/938real ms.
+Pass 4: compiled C into "stap_e5886fa50499994e6a87aacdc43cd392_399.ko" in 3310usr/430sys/3714real ms.
+Pass 5: starting run.
+read performed
+Pass 5: run completed in 10usr/40sys/73real ms.
 </screen>
 
     <para> The last three lines of the output (i.e. beginning with
diff --git a/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml
index b1f40669..fccf0469 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml
@@ -71,18 +71,22 @@ if (<replaceable>condition</replaceable>)
 <example id="simpleifelseexample">
 	<title>ifelse.stp</title>
 <programlisting>
-global countread, countnonread

-probe kernel.function("vfs_read"),kernel.function("vfs_write")

-{

-	if (probefunc()=="vfs_read") {

-	countread ++ }

-	else {countnonread ++}

-}

-probe timer.s(5) { exit() }

-probe end 

-{

-	printf("VFS reads total %d\n VFS writes total %d\n", countread, countnonread)

-}
 
+global countread, countnonread
+probe kernel.function("vfs_read"),kernel.function("vfs_write")
+{
+	if (probefunc()=="vfs_read") {
+		countread ++ 
+	}
+	else {
+		countnonread ++
+	}
+}
+probe timer.s(5) { exit() }
+probe end 
+{
+	printf("VFS reads total %d\n VFS writes total %d\n", countread, countnonread)
+}
+ 
 </programlisting>
 </example>
 
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
index 3324a50d..f1637356 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
@@ -49,8 +49,18 @@
 	<term>stapdev</term>
 	<listitem>
 <para>
-	Members of this group can use <command>stap</command> to run SystemTap scripts, or <command>staprun</command> to run SystemTap instrumentation modules.
+	Members of this group can use <command>stap</command> to run SystemTap scripts, or <command>staprun</command> to run SystemTap instrumentation modules. 
+</para>	
+	
+
+<para>
+	Running <command>stap</command> involves compiling SystemTap scripts into kernel modules and 
+	loading them into the kernel. This requires elevated privileges to the system, which are granted 
+	to <command>stapdev</command> members. Unfortunately, such privileges also grant effective root 
+	access to <command>stapdev</command> members. As such, you should only grant  
+	<command>stapdev</command> group membership to users whom you can trust root access.
 </para>
+	
 	</listitem>
 </varlistentry>