From 3c0ed97c9ddfe3406d47ce2ad6c6d9d008a5d7ac Mon Sep 17 00:00:00 2001
From: William Cohen <wcohen@redhat.com>
Date: Fri, 27 Aug 2010 17:14:08 -0400
Subject: [PATCH] Clean up the timeout.stp and topsys.stp example text

---
 .../en-US/Useful_Scripts-timeout.xml          | 31 +++++---------
 .../en-US/Useful_Scripts-topsys.xml           | 40 ++++++++-----------
 2 files changed, 26 insertions(+), 45 deletions(-)

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-timeout.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-timeout.xml
index 3fdfd839d..00b992832 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-timeout.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-timeout.xml
@@ -51,7 +51,10 @@ uses systemtap/testsuite/systemtap.examples/profiling/timeout.stp
 </formalpara>
 
 	<para>
-		<xref linkend="timeouts"/> tracks how many times each application used the following system calls over time:
+		<xref linkend="timeouts"/> tracks how many times each
+		of the following system calls completed 
+		due to time expiring rather than due to an actual event
+		occurring:
 	</para>
 
 	<itemizedlist>
@@ -64,14 +67,6 @@ uses systemtap/testsuite/systemtap.examples/profiling/timeout.stp
 		<listitem><para><command>signal</command></para></listitem>
 	</itemizedlist>
 
-	<para>
-		In some applications, these system calls are used excessively. As such, they are normally identified as "likely
-		culprits" for polling applications. Note, however, that an application may be using a different system
-		call to poll excessively; sometimes, it is useful to find out the top system calls used by the system (refer to
-		<xref linkend="topsyssect"/> for instructions). Doing so can help you identify any additional suspects, which you
-		can add to <xref linkend="timeouts"/> for tracking.
-	</para>
-
 
 <indexterm>
 <primary>script examples</primary>
@@ -112,21 +107,13 @@ uses systemtap/testsuite/systemtap.examples/profiling/timeout.stp
 29548 |      0    1440       0       0       0       0       0| httpd
  1862 |      0       0       0       0       0    1438       0| iscsid</screen>
 </example>
-<!--probe kernel.function(@1) {  # probe function passed as argument from stdin
-called[probefunc()] &lt;&lt;&lt; 1  # add a count efficiently
-}
-global called
-probe end,timer.ms(30000) {
-foreach (fn+ in called)  # Sort by function name
-#       (fn in called-)  # Sort by call count (in decreasing order)
-printf("%s %d\n", fn, @count(called[fn]))
-exit()
-}-->
 <para>
-	You can increase the sample time by editing the timer in the second probe (<command>timer.s()</command>).
-	The output of <xref linkend="countcalls"/> contains the name and UID of the top 20 polling applications,
+	You can increase the sample time by editing the second probe (<command>timer.s(1)</command>).
+	The output of <xref linkend="timeouts"/> contains the name and UID of the top 20 polling applications,
 	along with how many times each application performed each polling system call (over time).
-	<xref linkend="timeoutsoutput"/> contains an excerpt of the script:
+	<xref linkend="timeoutsoutput"/> contains an excerpt of the script.
+	In this particular example firefox is doing an excessive amount of
+	polling due to a plugin module.
 </para>
 	</section>
 
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-topsys.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-topsys.xml
index cd2c6f32c..7487b52f5 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-topsys.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-topsys.xml
@@ -32,30 +32,24 @@
 <secondary>examples of SystemTap scripts</secondary>
 </indexterm>
 
-<remark>
-uses systemtap/testsuite/systemtap.examples/profiling/topsys.stp
-</remark>
-
-
-	<para>
-		<xref linkend="timeouts"/> from <xref linkend="timeoutssect"/> helps you identify which applications
-		are polling by pointing out which ones used the following system calls most frequently:
-	</para>
-
-	<itemizedlist>
-		<listitem><para><command>poll</command></para></listitem>
-		<listitem><para><command>select</command></para></listitem>
-		<listitem><para><command>epoll</command></para></listitem>
-		<listitem><para><command>itimer</command></para></listitem>
-		<listitem><para><command>futex</command></para></listitem>
-		<listitem><para><command>nanosleep</command></para></listitem>
-		<listitem><para><command>signal</command></para></listitem>
-	</itemizedlist>
-
 	<para>
-		However, in some systems, a different system call might be responsible for excessive polling. If you suspect
-		that a polling application is using a different system call to poll, you need to identify first the top
-		system calls used by the system. To do this, use <xref linkend="topsys"/>.
+		<xref linkend="timeouts"/> from <xref linkend="timeoutssect"/>
+		helps you identify which applications
+		are polling by examining a small subset of system calls (
+		<command>poll</command>,
+		<command>select</command>,
+		<command>epoll</command>,
+		<command>itimer</command>,
+		<command>futex</command>,
+		<command>nanosleep</command>, and
+		<command>signal</command>).
+		However, in some systems, an excessive number of system calls
+		outside that small subset
+		might be responsible for time spent in the
+		kernel. If you suspect that an application is using
+		system calls excessively, you need to
+		identify the most frequently used system calls on the
+		system. To do this, use <xref linkend="topsys"/>.
 	</para>
 
 <formalpara id="topsys">
-- 
2.43.5