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

* 'master' of ssh://sources.redhat.com/git/systemtap:
  Added tests for utrace-syscall probe context variables.
  Add $return context variables on per-process-syscall.return probes
  Add $argN context variables on per-process-syscall probes
  Add $name context variable support on marker probes
  Utrace on ia64 fast fetch-register support
  Add ia64 utrace support
  Correct this_section_offset calculation in _stp_kallsyms_lookup.
  tiny grammar fix in NEWS
  separated Scripts, edited accordingly
  PR1288: runtime functions for avoiding certain addresses
  remove test tag
  added content for Ch1 and 2, to add more later

4 files changed, 110 insertions, 11 deletions

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml b/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml
index 9285d0ae..f60ab2f3 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml
@@ -5,15 +5,36 @@
 <chapter id="introduction">
 	<title>Introduction</title>
 	<para>
-		A short introduction on SystemTap_Beginners_Guide
+		SystemTap is a tracing and probing tool that provides users deep technical insight into what the operating system (particularly, the kernel) is doing at any given time. 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 information that is more "granular" in nature.  
 	</para>
 	
-<formalpara>
+	<para>
+		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.
+	</para>
+	  
+<!--	
+	<para>
+		SystemTap was developed as a Linux version of the DTrace tool (for <trademark>Sun Solaris</trademark>).
+	</para>	
+	-->
+<section id="goals">
 	<title>Goals</title>
-	<para>TBD</para> 
-</formalpara>	
+	<para>The goal of SystemTap is to provide infrastructure to monitor the running Linux kernel for detailed analysis. This can assist in identifying the underlying cause of a performance or functional 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 you to gather the same information by simply running its suite of tools against specific <firstterm>tapsets</firstterm> or SystemTap scripts.</para> 
+		
+	<para>However, SystemTap was initially designed for users with intermediate to advanced knowledge of the kernel. This could present a steep learning curve for administrators or developers whose knowledge of the Linux kernel is little to none.</para>
+	
+	<para>In line with that, the main goal of the <citetitle>SystemTap Beginner's Guide</citetitle> is two-fold:</para>
+	
+	<itemizedlist>
+		<listitem><para>To introduce users to SystemTap, familiarize them with its architecture, and provide setup instructions for all kernel types.</para></listitem>
+		
+		<listitem><para>To provide pre-written SystemTap scripts for monitoring and forensic tasks, along with instructions on how to analyze their output.</para></listitem>  
+	</itemizedlist>	
+<!-- </formalpara>	 -->
 <remark>above,  Short description on the underlying goals of SystemTap_Beginners_Guide, what we want to teach users.</remark>
-
+</section>
 	
 	<section id="intro-usage">
 		<title>Usage</title>
@@ -25,7 +46,7 @@
 	<section id="intro-systemtap-vs-others">
 		<title>SystemTap Versus Other Monitoring Tools</title>
 		<remark>
-			Short summary; when is SystemTap suitable vs other popular monitoring tools (e.g. top, Oprofile, /proc)
+			** Short summary; when is SystemTap suitable vs other popular monitoring tools (e.g. top, Oprofile, /proc)
 		</remark>
 		
 <formalpara>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
new file mode 100644
index 00000000..abb087bc
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
@@ -0,0 +1,46 @@
+<?xml version='1.0'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<section id="scripts">
+	<title>SystemTap Scripts</title>
+	
+	<para>
+		For the most part, SystemTap scripts are the foundation of each SystemTap session. The SystemTap scripts you use or write yourself instruct SystemTap on what type of information to trap, and what to do once that information is trapped.
+	</para>
+	
+	<para>
+		As stated in <xref linkend="understanding-how-systemtap-works"/>, SystemTap scripts are made up of two components: <emphasis>events</emphasis> and <emphasis>handlers</emphasis>. Once a SystemTap session is underway, SystemTap monitors the operating system for the specified events and executes the handlers as they occur. 
+	</para>
+	
+<note>
+	<title>Note</title>
+	<para>An event and its corresponding handler is collectively called a <emphasis>probe</emphasis>. A SystemTap script can have multiple probes, in the same manner that each event can have multiple corresponding handlers.</para>
+</note>	
+	
+	<para>
+		In terms of application development, using events and handlers is similar to inserting <command>print</command> statements in a program's sequence of commands. These <command>print</command> statements allow you to view a history of commands executed once the program is run. 
+	</para>	
+	
+	<para>
+		SystemTap scripts go one step further by allowing you more flexibility with regard to handlers. Events serve as the triggers for handlers to run; handlers can be specified to trap specified data and print it in a certain manner. 
+	</para>
+	
+	
+
+	<section id="systemtapscript-format">
+		<title>Format</title>
+		<para>
+			SystemTap scripts use the following format:
+		</para>
+	</section>
+	
+	<!--	<section id="SystemTap_Beginners_Guide-Test-Section_2_Test">
+		<title>Section 2 Test</title>
+		<para>
+			Test of a section
+		</para>
+	</section>-->
+
+</section>
+
diff --git a/doc/SystemTap_Beginners_Guide/en-US/SystemTap_Beginners_Guide.ent b/doc/SystemTap_Beginners_Guide/en-US/SystemTap_Beginners_Guide.ent
index 46bb6c06..994cf1a4 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/SystemTap_Beginners_Guide.ent
+++ b/doc/SystemTap_Beginners_Guide/en-US/SystemTap_Beginners_Guide.ent
@@ -1,3 +1,4 @@
 <!ENTITY PRODUCT "Red_Hat_Enterprise_Linux 5">
 <!ENTITY BOOKID "SystemTap_Beginners_Guide">
-<!ENTITY YEAR "2009">
\ No newline at end of file
+<!ENTITY YEAR "2009">
+<!ENTITY RHEL "Red Hat Enterprise Linux 5">
\ No newline at end of file
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml b/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml
index b3a1cbed..de5d41b0 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml
@@ -8,21 +8,52 @@
 		Short summary; probes, handlers, events
 	</remark>
 		
+	<para>SystemTap allows users to write and reuse simple scripts to deeply examine the activities of a running Linux system. These scripts can be designed to extract data, filter it, and summarize it quickly (and safely), enabling the diagnosis of complex performance (or even functional) problems.</para>
+	
+	<para>  The essential idea behind a SystemTap script is to name <emphasis>events</emphasis>, and to give them <emphasis>handlers</emphasis>. When SystemTap runs the script, SystemTap monitors for the event; once the event occurs, the Linux kernel then runs the handler as a quick sub-routine, then resumes.</para>
+		
+	<para>There are several kind of events; entering/exiting a function, timer expiration, session termination, etc. A handler is a series of script language statements that specify the work to be done whenever the event occurs. This work normally includes extracting data from the event context, storing them into internal variables, or printing results.</para>
+		
 	<section id="understanding-architecture-tools">
 		<title>Architecture</title>
 		<remark>
-			add diagram, describe architecture, enumerate common tools
+			** add diagram, describe architecture, enumerate common tools
 		</remark>
-	</section>
+		
+		<remark>
+			** architecture diagram must be simpler, if at all included
+		</remark>
+		
+		<remark>
+			** add design advantages? e.g. "building kmods on-the-fly allows safer execution of script etc etc"
+		</remark>	
+		
+		<para>A SystemTap session begins when you run a SystemTap script. This session occurs in the following fashion:</para>
+			
+<procedure>
+	<title>SystemTap Session</title>
+	<step><para>SystemTap first translates the script to C, running the system C compiler to create a kernel module from it.</para></step>
+	
+	<step><para>SystemTap then loads the module, then enables all the probed events by "hooking" those events into the kernel.</para></step>
+		
+	<step><para>As the events occur, their corresponding handlers are executed.</para></step>
 	
+	<step><para>Once the SystemTap session is terminated, the hooked events are disconnected from the kernel; afterwards, the kernel module is unloaded.</para></step>    
+</procedure>
+
+<para>This sequence is driven from a single command-line program: <command>stap</command>. This program is SystemTap's main front-end tool. For more information about <command>stap</command>, refer to <command>man stap</command> (once SystemTap is set up on your machine).</para>
+
+</section>
+<xi:include href="Scripts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<!--	
 	<section id="understanding-scripts">
 		<title>SystemTap Scripts</title>
 		
 		<remark>
-			definition, significance, structure, very basic examples, reference to later chapter (how to read library of preset SystemTap scripts in this book, using them)
+			** definition, significance, structure, very basic examples, reference to later chapter (how to read library of preset SystemTap scripts in this book, using them)
 		</remark>
 	</section>
-	
+	-->
 	<section id="understanding-tapsets">
 		 <title>Tapsets</title>