Merge branch 'master' of ssh://sources.redhat.com/git/systemtap

5 files changed, 107 insertions, 125 deletions

diff --git a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml
index a16e4f48..5e29307c 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml
@@ -23,37 +23,23 @@
   </para>
 	
   <para>
-    Normally, however, SystemTap scripts can only be run on systems where
-    SystemTap is deployed (as in <xref linkend="installproper"/>). This could
-    mean that if you want to run SystemTap on ten systems, you would need to
-    deploy SystemTap on <emphasis>all</emphasis> those systems.  In some cases,
-    this may be neither feasible nor desired to fully deploy SystemTap on those
-    systems. For instance corporate policy may prohibit an administrator from
-    installing RPMs that provide compilers or debug information on specific
-    machines, which will prevent the deployment of SystemTap.
+    Normally, however, SystemTap scripts can only be run on systems where SystemTap is deployed (as in <xref linkend="installproper"/>). This could mean that if you want to run SystemTap on ten systems, you would need to deploy SystemTap on <emphasis>all</emphasis> those systems.  In some cases, this may be neither feasible nor desired. For instance, corporate policy may prohibit an administrator from installing RPMs that provide compilers or debug information on specific machines, which will prevent the deployment of SystemTap.
   </para>
 	
   <para>
-    To work around this, you can resort to
-    <firstterm>cross-instrumentation</firstterm>. Cross-instrumentation is the
-    process of generating SystemTap instrumentation module from a SystemTap
-    script on one computer to be used on another computer. This process offers
-    the following benefits:
+    To work around this, you can resort to <firstterm>cross-instrumentation</firstterm>. Cross-instrumentation is the process of generating SystemTap instrumentation module from a SystemTap script on one computer to be used on another computer. This process offers the following benefits:
   </para>
 	
   <itemizedlist>
     <listitem>
       <para>
-	The debug RPMs for various machines can be installed on a single system:
-	the host machine.
+	The kernel information packages for various machines can be installed on a single <emphasis>host machine</emphasis>.
       </para>
     </listitem>
 
     <listitem>
       <para>
-	Each target machine only needs one RPM to installed to use
-	the generated SystemTap instrumentation module:
-	<filename>systemtap-runtime</filename>.
+	Each <emphasis>target machine</emphasis> only needs one RPM to installed to use the generated SystemTap instrumentation module: <filename>systemtap-runtime</filename>.
       </para>
     </listitem>
   </itemizedlist>
@@ -186,10 +172,9 @@
     appropriate values):
   </para>
 
-  <para>
-    <command>stap -r <replaceable>kernel_version</replaceable> <replaceable>script</replaceable> -m
-    <replaceable>module_name</replaceable></command>
-  </para>
+<screen>
+stap -r <replaceable>kernel_version</replaceable> <replaceable>script</replaceable> -m <replaceable>module_name</replaceable>
+</screen>
 
   <para>
     Here, <command><replaceable>kernel_version</replaceable></command> refers to
@@ -214,9 +199,9 @@
     it to the <emphasis>target system</emphasis> and load it using:
   </para>
 
-  <para>
-    <command>staprun <replaceable>module_name</replaceable>.ko</command>
-  </para>
+<screen>
+staprun <replaceable>module_name</replaceable>.ko
+</screen>
 
   <para>
     For example, to create the <emphasis>instrumentation module</emphasis>
@@ -249,7 +234,7 @@
     <para>
       The <emphasis>host system</emphasis> must be the same architecture and
       running the same distribution of Linux as the <emphasis>target
-      system</emphasis> in order for the <emphasis>instrumentation
+      system</emphasis> in order for the built <emphasis>instrumentation
       module</emphasis> to work.
     </para>
   </important>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
index f2c0cd92..e5384abc 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
@@ -34,10 +34,9 @@
   </important>
 
 <section id="installproper">
-    <title>Installating SystemTap</title>
+    <title>Installing SystemTap</title>
 
-    <para> For the Systemtap Beginner's Guide the following two SystemTap RPMs
-    need to be installed:
+    <para>To deploy Systemtap, you will need to to install the following RPMs:
     </para>
 
     <itemizedlist>
@@ -45,24 +44,15 @@
       <listitem><para><filename>systemtap-runtime</filename></para></listitem>
     </itemizedlist>
 	
-    <para>Assuming that the computer system has been configured to use Red Hat
-      Network (RHN) or <command>yum</command> is available,
-      the two rpms can be installed with <command>yum install
-      systemtap systemtap-runtime</command>. Before you use SystemTap the
-      additional kernel information will need to be installed as described in
-      the following section.
+    <para>Assuming that your system is configured to use Red Hat Network (RHN) or <command>yum</command> is available, these two rpms can be installed with <command>yum install systemtap systemtap-runtime</command>. Note that before you can use SystemTap, you will still need to install the required kernel information RPMs.
     </para>
 
 </section>
 
 <section id="install-kinfo">
-    <title>Installing Needed Kernel Information</title>
+    <title>Installing Required Kernel Information RPMs</title>
 
-    <para> SystemTap makes use of the information in additional kernel RPMs to
-      determine where to place instrumentation in the kernel and how to generate
-      code for the instrumentation. You will need to download and install the
-      necessary <filename>-devel</filename> and <filename>-debuginfo</filename>
-      packages for your kernel. The necessary <filename>-devel</filename> and
+    <para> SystemTap needs information about the kernel in order to place instrumentation in it (i.e. probe it). This information also allows SystemTap to generate the code for the instrumentation. This information is contained in the matching <filename>-devel</filename> and <filename>-debuginfo</filename> packages for your kernel. The necessary <filename>-devel</filename> and
       <filename>-debuginfo</filename> packages for the ordinary "vanilla" kernel
       are as follows:
     </para>
@@ -75,14 +65,11 @@
 
     <para> To determine what kernel your system is currently using, use:</para>
 		
-    <screen>
-      uname -r
-    </screen>
-
-    <para>For example, if you wish to use SystemTap on kernel version
-      <filename>2.6.18-53.el5</filename> on an i686 machine,
-      then you would need to download and
-      install the following RPMs:
+<screen>
+uname -r
+</screen>
+
+    <para>For example, if you wish to use SystemTap on kernel version <filename>2.6.18-53.el5</filename> on an i686 machine, then you would need to download and install the following RPMs:
     </para>
 
     <itemizedlist>
@@ -95,21 +82,30 @@
       <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 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> The script <xref linkend="stapprep"/> can be used by normal users to
-	  determine what supporting kernel RPMs need to be installed on the
-	  machine to use SystemTap with a particular kernel.  The script run
-	  without any arguments detemines the RPMs needed for the currently
-	  running kernel. The script can also accept one argument, the output
-	  <command>uname -r</command>, to determine the related RPMs required
-	  for a kernel that may not be currently running on the machine.
-    </para>
+<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.
+</para>
+
+<note>
+	<title>Note</title>
+	<para>Running <xref linkend="stapprep"/> as root will display the required kernel packages <emphasis>and</emphasis> install them as well, provided that <command>yum</command> and <command>yum-utils</command> are configured properly.</para>
+</note>	
+	
+<!--	Running <xref linkend="stapprep"/> without any arguments will display and install the required kernel information packages for the currently loaded kernel. If you wish to probe a kernel other than the one currently loaded, you can pass a specific kernel version as an argument to <xref linkend="stapprep"/>; the script will then install that kernel's corresponding kernel information packages.
+</para>	-->
+    
+<!--    
+<para>
+	To determine what kernel information RPMs you need to install in order to run SystemTap, run the <xref linkend="stapprep"/>. Running <xref linkend="stapprep"/> without any arguments will display what packages you 
+    
+    
+    
+    <para> The script <xref linkend="stapprep"/> can be used by normal users to determine what supporting kernel RPMs need to be installed on the machine to use SystemTap with a particular kernel.  The script run without any arguments detemines the RPMs needed for the currently running kernel. The script can also accept one argument, the output <command>uname -r</command>, to determine the related RPMs required for a kernel that may not be currently running on the machine.
+    </para>-->
 
     <formalpara id="stapprep">
       <title>stapprep.sh</title>
@@ -119,44 +115,36 @@
 	</programlisting>
       </para>
     </formalpara>
-
+<!--
     <para>
-      If the yum-utils package is installed on the computer and has access to
-      the <command>yum</command> repositories,
-      the <command>stapprep.sh</command> script can be run
-      by root to download and install the needed kernel packages via
-      <command>yum</command> and <command>rpm</command> commands. Thus, the
-      system administrator should be able to install the needed RPMs with the
-      script on the machine:
-    </para>
+	    If the <filename>yum-utils</filename> package is installed and the <command>yum</command> repositories are set up properly, you can run the <xref linkend="stapprep"/> script as root. <xref linkend="stapprep"/> will automatically download and install the required packages via <command>yum</command> and <command>rpm</command> commands (assuming that the kernel you wish to probe is currently loaded).
+    </para>-->
 
-    <screen>
-      ./stapprep.sh
-    </screen>
 <!-- The script assumes the Red Hat Enterprise Linux debuginfo repository,
 <filename>rhel-debuginfo</filename>, but this could be changed.  One could
 search the /etc/yum.repo.d/ directory for debuginfo repositories -->
 
-    <para>
-	If <command>yum</command> is not available on a Red Hat Enterprise Linux
-	5 machine, the following lines of bash script will generate the URL for
-	the debuginfo RPM directory:
-    </para>
-
-<screen>
+<para>
+	If you do not have <command>yum</command> and <command>yum-utils</command> installed (and you are unable to install them), you will have to manually download and install the required kernel information packages. To generate the URL from which to download the required packages, use the following script:
+</para>	
+	
+<formalpara condition="RedHat">
+	<title>systemtapurl.sh</title>
+<para>
+<programlisting>
 pkg=`grep distroverpkg /etc/yum.conf |awk -F= '{print $2}'`
 releasever=`rpm -q --qf "%{version}" $pkg`
 base=`uname -m`
 echo "ftp://ftp.redhat.com/pub/redhat/linux/enterprise/$releasever/en/os/$base"
-</screen>
+</programlisting>
+</para>
+</formalpara>
 
-    <para>
-      If <command>yum</command> in not available on a Fedora system, the
-      following lines of bash script will generate the URL for the location to
-      find the needed kernel RPMs:
-    </para>
 
-<screen>
+<formalpara condition="fedora">
+	<title>systemtapurl.sh</title>
+<para>
+	<programlisting>
 echo -n "Enter nvr of kernel-debuginfo (e.g. 2.6.25-14.fc9.x86_64) " ; \
 read NVR; \
 BASE=`uname -m` ; \
@@ -165,13 +153,11 @@ VERSION=`echo $NVR | awk -F- '{print $1}'` ; \
 RELEASE=`echo $NVR | awk -F- '{print $2}'` ; \
 echo "http://kojipkgs.fedoraproject.org/\
 packages/kernel/$VERSION/$RELEASE/$BASE/"
-</screen>
-
+</programlisting>
+</para>
+</formalpara>
     <para>
-      The package RPMs can be manually downloaded and copied to the
-      machine.  Once you have manually copied the packages to the
-      machine, install the RPMs by running <command>rpm --force -ivh
-      <replaceable>package_names</replaceable></command>.
+Once you have manually downloaded the required packages to the machine, install the RPMs by running <command>rpm --force -ivh <replaceable>package_names</replaceable></command>.
     </para>
 	
   </section>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml b/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml
index 36dd3c44..dbca02fc 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml
@@ -8,11 +8,16 @@
 		SystemTap is a tracing and probing tool that allows users to study and monitor the activities of the operating system (particularly, the kernel) in fine detail. It provides information similar to the output of tools like <command>netstat</command>, <command>ps</command>, <command>top</command>, and <command>iostat</command>; however, SystemTap is designed to provide more filtering and analysis options for collected information.
 	</para>
 	
-	<para>
+	<para condition="RedHat">
 		For system administrators, SystemTap can be used as a performance monitoring tool for &PROD;. It is most useful when other similar tools cannot precisely pinpoint a bottleneck in the system, requiring a deep analysis of kernel activity. In the same manner, application developers can also use SystemTap to monitor, in finer detail, how their application behaves within the Linux system.
 	</para>
 	
 	
+	<para condition="fedora">
+		For system administrators, SystemTap can be used as a performance monitoring tool for &PROD2;. It is most useful when other similar tools cannot precisely pinpoint a bottleneck in the system, requiring a deep analysis of kernel activity. In the same manner, application developers can also use SystemTap to monitor, in finer detail, how their application behaves within the Linux system.
+	</para>	
+	
+	
 <!--	
 	<para>
 		SystemTap was developed as a Linux version of the DTrace tool (for <trademark>Sun Solaris</trademark>).
@@ -20,7 +25,7 @@
 	-->
 <section id="goals">
 	<title>Documentation Goals</title>
-	<para>SystemTap provides the infrastructure to monitor the running Linux kernel for detailed analysis. This can assist administrators and developers in identifying the underlying cause of a performance or functional problem.</para>
+	<para>SystemTap provides the infrastructure to monitor the running Linux kernel for detailed analysis. This can assist administrators and developers in identifying the underlying cause of a bug or performance problem.</para>
 	
 	<para>Without SystemTap, monitoring the activity of a running kernel would require a tedious instrument, recompile, install, and reboot sequence. SystemTap is designed to eliminate this, allowing users to gather the same information by simply running user-written SystemTap scripts.</para> 
 		
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch.xml
index 2ac1366d..e747771b 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch.xml
@@ -27,6 +27,9 @@ no script in examples
 </para>
 </formalpara>		
 
+<remark>need to add references to sources/man pages that explain how "dev_nr = $file->f_dentry->d_inode->i_sb->s_dev" and "($1 &lt;&lt; 20 | $2)".</remark>
+
+
 <para><xref linkend="inodewatch"/> takes the following information about the file as an argument:</para>
 
 <itemizedlist>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
index 98fc54a8..7fc93e8b 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
@@ -28,14 +28,44 @@
 		<para>
 			SystemTap scripts are run through the command <command>stap</command>. <command>stap</command> can run SystemTap scripts from standard input or from file.
 		</para>
-		
+<!--		
 <important>
 	<title>Important</title>
 <para>Running SystemTap requires root privileges. As such, you need to either log in as root or configure <command>sudo</command> accordingly for specific users who need to run SystemTap (refer to <command>man sudo</command> or <command>man visudo</command> for more information.</para> 
 
 </important>
-		
-		
+		-->
+
+<!--<formalpara>
+	<title>stapdev and stapusr</title>-->
+	<para>Running <command>stap</command> and <command>staprun</command> requires elevated privileges to the system. However, not all users can be granted root access just to run SystemTap. In some cases, for instance, you may want to allow a non-privileged user to run SystemTap instrumentation on his machine.</para>
+<!-- </formalpara> -->
+
+<para>To allow ordinary users to run SystemTap without root access, add them to one of these user groups:</para>
+
+<variablelist>
+	
+<varlistentry>
+	<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.
+</para>
+	</listitem>
+</varlistentry>
+
+<varlistentry>
+	<term>stapusr</term>
+	<listitem>
+<para>
+	Members of this group can only run <command>staprun</command> to run SystemTap instrumentation modules. In addition, they can only run those modules from <filename>/lib/modules/<replaceable>kernel_version</replaceable>/systemtap/</filename>. Note that this directory must be owned only by the root user, and must only be writable by the root user.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>		
+
+
+
 		<para> Below is a list of commonly used <command>stap</command> options: </para>
 		
 <variablelist>
@@ -110,33 +140,6 @@ echo "probe timer.s(1) {exit()}" | stap -
 	<para>The <command>stap</command> options <command>-v</command> and <command>-o</command> also work for <command>staprun</command>. For more information about <command>staprun</command>, refer to <command>man staprun</command>.</para>
 </note>	
 
-<formalpara>
-	<title>stapdev and stapusr</title>
-	<para>Running <command>stap</command> and <command>staprun</command> requires elevated privileges to the system. However, not all users can be granted root access just to run SystemTap. In some cases, for instance, you may want to allow a non-privileged user to run SystemTap instrumentation on his machine.</para>
-</formalpara>
-
-<para>To allow ordinary users to run SystemTap without root access, add them to one of these user groups:</para>
-
-<variablelist>
-	
-<varlistentry>
-	<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.
-</para>
-	</listitem>
-</varlistentry>
-
-<varlistentry>
-	<term>stapusr</term>
-	<listitem>
-<para>
-	Members of this group can only run <command>staprun</command> to run SystemTap instrumentation modules. In addition, they can only run those modules from <filename>/lib/modules/<replaceable>kernel_version</replaceable>/systemtap/</filename>. Note that this directory must be owned only by the root user, and must only be writable by the root user.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
 	</section>
 
 </chapter>