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

* 'master' of ssh://sources.redhat.com/git/systemtap:
  added sections to Useful Scripts (graphs, disktop)
  added file
  added gnuplot sample image
  correcting a tag error
  added Usage item
  committing
  added cross-instrumentation, deploying systemtap
  minor, added notes for Using SystemTap chapter
  added section on tapsets
  revisions as per sghosh

1 files changed, 87 insertions, 43 deletions

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
index bbd265c2..160597bf 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
@@ -45,7 +45,7 @@ probe	<replaceable>[event]</replaceable>,
 	exit()
 }
 </programlisting>		
-	<para>The <replaceable>exit()</replaceable> condition is optional, but it is recommended since it safely terminates the session once the script successfully traps the required information.</para>	
+	<para>The <replaceable>exit()</replaceable> condition is optional; this condition safely terminates the session once the script successfully traps the required information the first time.</para>	
 	
 <important>
 	<title>Important</title>
@@ -56,29 +56,19 @@ probe	<replaceable>[event]</replaceable>,
 	<section id="systemtapscript-events">
 		<title>Events</title>
 	
-<para>
-	SystemTap supports multiple events per probe; as shown in <xref linkend="scriptformats"/>, multiple events are delimited by a comma (<command>,</command>). Sample <replaceable>[event]</replaceable>s include:</para>
+<para>SystemTap events can be broadly classified into two types: <firstterm>synchronous</firstterm> and <firstterm>asynchronous</firstterm>.</para>
 
-<variablelist>
-	
-<varlistentry>
-	<term>begin</term>
-	<listitem>
-		<para>The startup of a SystemTap session; i.e. as soon as the SystemTap script is run.</para>
-	</listitem>	
-</varlistentry>	
+<formalpara><title>Synchronous Events</title>
+	<para>A <firstterm>synchronous</firstterm> event occurs when any processor executes an instruction matched by the specification. This gives other events a reference point (or instruction address) from which more contextual data may be available.</para>
+</formalpara>
 
-<varlistentry>
-	<term>end</term>
-	<listitem>
-		<para>The end of a SystemTap session.</para>
-	</listitem>	
-</varlistentry>
+<para>Examples of synchronous events include:</para>
 
+<variablelist>
 <varlistentry>
 	<term>kernel.function("<replaceable>[function]</replaceable>")</term>
 	<listitem>
-		<para>The entry to the kernel function <replaceable>function</replaceable>. For example, <command>kernel.function("sys_open")</command> refers to the "event" that the kernel function <command>sys_open</command> is used. To specify the <emphasis>return</emphasis> of the kernel function <command>sys_open</command>, append the <command>return</command> string to the event statement; i.e. <command>kernel.function("sys_open").return</command>.</para>
+		<para>The entry to the kernel function <replaceable>function</replaceable>. For example, <command>kernel.function("sys_open")</command> refers to the "event" that occurs when the kernel function <command>sys_open</command> is called by any thread in the system. To specify the <emphasis>return</emphasis> of the kernel function <command>sys_open</command>, append the <command>return</command> string to the event statement; i.e. <command>kernel.function("sys_open").return</command>.</para>
 		
 		<para>When defining functions, you can use asterisk (<command>*</command>) for wildcards. You can also trace the entry/exit of a function in a kernel source file. Consider the following example:</para>
 <example id="wildcards"><title>Wildcards and Kernel Source Files in an Event</title>
@@ -100,9 +90,59 @@ probe kernel.function("*@net/socket.c").return { }
 		<para>To identify what system calls are made by a specific program/command, use <command>strace <replaceable>command</replaceable></command>.</para>
 	</listitem>	
 </varlistentry>
+	
+<varlistentry>
+	<term>module("<replaceable>[module]</replaceable>").function("<replaceable>[function]</replaceable>")</term>
+	<listitem>
+		<para>Allows you to probe functions within modules. For example:</para>
+		
+		<example id="eventsmodules"><title>Module Probe</title>
+			<programlisting>
+				probe module("ext3").function("*") { }
+				probe module("ext3").function("*").return { }
+			</programlisting>	
+		</example>
+		
+		<para>
+			The first probe in <xref linkend="eventsmodules"/> points to the entry of <emphasis>all</emphasis> functions for the <filename>ext3</filename> module. The second probe points to the exits of all entries for that same module; the use of the <command>.return</command> suffix is similar to <command>kernel.function()</command>. Note that the probes in <xref linkend="eventsmodules"/> also do not contain probe bodies, and as such will not print any useful data (as in <xref linkend="wildcards"/>). 
+		</para>	
+		
+		<para>
+			A system's loaded modules are typically located in <filename>/lib/modules/<replaceable>[kernel version]</replaceable></filename>, where <replaceable>kernel version</replaceable> refers to the currently loaded kernel. Modules use the filename extension <filename>.ko</filename>. 
+		</para>	
+		
+	</listitem>	
+</varlistentry>	
+</variablelist>	
+
+	
+<formalpara>
+	<title>Asynchronous Events</title>
+	<para><firstterm>Asynchronous</firstterm> events, on the other hand, do not point to any reference point. This family of probe points consists mainly of counters, timers, and similar constructs.</para>
+</formalpara>
 
+	<para>Examples of asynchronous events include:</para>
+
+<variablelist>
+	
 <varlistentry>
-	<term>timer.ms()</term>
+	<term>begin</term>
+	<listitem>
+		<para>The startup of a SystemTap session; i.e. as soon as the SystemTap script is run.</para>
+	</listitem>	
+</varlistentry>	
+
+<varlistentry>
+	<term>end</term>
+	<listitem>
+		<para>The end of a SystemTap session.</para>
+	</listitem>	
+</varlistentry>
+
+
+
+<varlistentry>
+	<term>timer events</term>
 	<listitem>
 		<para>An event that specifies a handler to be executed "after X number of milliseconds". For example:</para>
 		
@@ -116,34 +156,29 @@ probe timer.ms(4000)
 </example>
 
 <para>
-	<xref linkend="timer"/> is an example of a probe that allows you to terminate the script after 4000 milliseconds (or 4 seconds). When used in conjunction with another probe that traps a large quantity of data, a probe using <command>timer.ms()</command> allows you to limit the information your script is collecting (and printing out).
+	<xref linkend="timer"/> is an example of a probe that allows you to terminate the script after 4000 milliseconds. Note that you can also use the following timer events:
+</para>
+	
+<itemizedlist>
+<listitem><para><command>timer.s(<replaceable>[seconds]</replaceable>)</command></para></listitem>
+
+<listitem><para><command>timer.us(<replaceable>[microseconds]</replaceable>)</command></para></listitem>
+
+<listitem><para><command>timer.ns(<replaceable>[nanoseconds]</replaceable>)</command></para></listitem>
+
+<listitem><para><command>timer.hz(<replaceable>[hertz]</replaceable>)</command></para></listitem>
+
+<listitem><para><command>timer.jiffies(<replaceable>[jiffies]</replaceable>)</command></para></listitem>
+
+</itemizedlist>
+<para>
+	When used in conjunction with another probe that traps a large quantity of data, timer events allow you to limit the information your script is collecting (and printing out).
 </para>	
 		
 	</listitem>	
 </varlistentry>
 
-<varlistentry>
-	<term>module("<replaceable>[module]</replaceable>").function("<replaceable>[function]</replaceable>")</term>
-	<listitem>
-		<para>Allows you to probe functions within modules. For example:</para>
-		
-<example id="eventsmodules"><title>Module Probe</title>
-<programlisting>
-probe module("ext3").function("*") { }

-probe module("ext3").function("*").return { }
-</programlisting>	
-</example>
 
-	<para>
-		The first probe in <xref linkend="eventsmodules"/> points to the entry of <emphasis>all</emphasis> functions for the <filename>ext3</filename> module. The second probe points to the exits of all entries for that same module; the use of the <command>.return</command> suffix is similar to <command>kernel.function()</command>. Note that the probes in <xref linkend="eventsmodules"/> also do not contain probe bodies, and as such will not print any useful data (as in <xref linkend="wildcards"/>). 
-	</para>	
-	
-	<para>
-		A system's loaded modules are typically located in <filename>/lib/modules/<replaceable>[kernel version]</replaceable></filename>, where <replaceable>kernel version</replaceable> refers to the currently loaded kernel. Modules use the filename extension <filename>.ko</filename>. 
-	</para>	
-
-	</listitem>	
-</varlistentry>
 
 <!--<remark>add timer.ms() to events list!</remark>-->
 <!--	
@@ -164,7 +199,12 @@ probe module("ext3").function("*").return { }
 	</para>	
 </important>
 
+<para>
+	SystemTap supports multiple events per probe; as shown in <xref linkend="scriptformats"/>, multiple events are delimited by a comma (<command>,</command>). If multiple events are specified in a single probe, SystemTap will execute the handler when any of the specified events occur. 
+</para>	
+
 <remark>is reference appropriate? too advanced for readers (it seems so to me)? please advise.</remark> 
+
 	</section>
 	
 	<section id="systemtapscript-handlers">
@@ -191,11 +231,10 @@ probe begin
 <formalpara id="printf">
 	<title>printf ( ) Statements</title>
 <para>
-	The <command>printf ()</command> statement is one of the simplest handler tools for printing data. <command>printf ()</command> can also be used to trap data using a wide variety of SystemTap handler functions using the following format:
+	The <command>printf ()</command> statement is one of the simplest functions for printing data. <command>printf ()</command> can also be used to trap data using a wide variety of SystemTap handler functions using the following format:
 </para>
 
 </formalpara>
-<remark>is "handler tool" appropriate?</remark>
 
 
 <programlisting>
@@ -210,6 +249,11 @@ printf ("<replaceable>[format string]</replaceable>\n", <replaceable>[argument]<
 	You can use the variables <command>%s</command> (for strings) and <command>%d</command> (for numbers) in format strings, depending on your list of arguments. Format strings can have multiple variables, each matching a corresponding argument; multiple arguments are delimited by a comma (<command>,</command>) and space.
 </para>
 
+<note>
+	<title>Note</title>
+	<para>Semantically, the SystemTap <command>printf</command> function is very similar to its C language counterpart. The aforementioned syntax and format for SystemTap's <command>printf</command> function is identical to that of the C-style <command>printf</command>.</para>
+</note>	
+
 <para>
 	To illustrate this, consider the following probe example:
 </para>