added Counting Function Calls Made, other minor edits

3 files changed, 82 insertions, 2 deletions

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
index 7914e79c..92dd8f1c 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
@@ -430,7 +430,7 @@ probe syscall.* {
 
 	<para>When <xref linkend="targetexample"/> is run with the argument <command>-x <replaceable>process ID</replaceable></command>, it watches all system calls (as specified by the event <command>syscall.*</command>) and prints out the name of all system calls made by the specified process.</para>
 	
-	<para>This has the same effect as specifying <command>if (pid() == <replaceable>process ID</replaceable></command> each time you wish to target a specific process. However, using <command>target()</command> makes it easier for you to re-use the script, giving you the ability to simply pass a process ID as an argument each time you wish to run the script (e.g. <command>stap targetexample.stp -x <replaceable>process ID</replaceable></command>).</para>
+	<para>This has the same effect as specifying <command>if (pid() == <replaceable>process ID</replaceable>)</command> each time you wish to target a specific process. However, using <command>target()</command> makes it easier for you to re-use the script, giving you the ability to simply pass a process ID as an argument each time you wish to run the script (e.g. <command>stap targetexample.stp -x <replaceable>process ID</replaceable></command>).</para>
 <!--		
 <note>
 	<title>Note</title>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-functioncalls.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-functioncalls.xml
new file mode 100644
index 00000000..d108e4fe
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-functioncalls.xml
@@ -0,0 +1,80 @@
+<?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="countcallssect">
+		<title>Counting Function Calls Made</title>
+		
+		
+<remark>
+	WAR STORY: Function call count http://sourceware.org/systemtap/wiki/WSFunctionCallCount?highlight=((WarStories))
+</remark>
+		
+<remark>
+no script in examples
+</remark>	
+				
+		
+	<para>This section describes how to identify how many times the system called a specific kernel function in a 30-second sample. Depending on your use of wildcards, you can also use this script to target multiple kernel functions.</para>
+	
+<formalpara id="countcalls">
+		<title>countcalls.stp</title>
+<para>
+<programlisting>
+probe kernel.function(@1) {  # probe every function in any C file under mm/
+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()
+}
+</programlisting>
+</para>
+</formalpara>		
+
+<para><xref linkend="countcalls"/> takes the targeted kernel function as an argument. The argument supports wildcards, which enables you to target multiple kernel functions up to a certain extent.</para>
+
+<para>You can increase the sample time by editing the timer in the second probe (<command>timer.ms()</command>). <xref linkend="countcallsoutput"/> contains an excerpt from the output of <command>stap countcalls.stp "*@mm/*.c"</command>:
+	
+
+<example id="countcallsoutput">
+	<title><xref linkend="countcalls"/> Sample Output</title>
+<screen>
+[...]
+__vma_link 97
+__vma_link_file 66
+__vma_link_list 97
+__vma_link_rb 97
+__xchg 103
+add_page_to_active_list 102
+add_page_to_inactive_list 19
+add_to_page_cache 19
+add_to_page_cache_lru 7
+all_vm_events 6
+alloc_pages_node 4630
+alloc_slabmgmt 67
+anon_vma_alloc 62
+anon_vma_free 62
+anon_vma_lock 66
+anon_vma_prepare 98
+anon_vma_unlink 97
+anon_vma_unlock 66
+arch_get_unmapped_area_topdown 94
+arch_get_unmapped_exec_area 3
+arch_unmap_area_topdown 97
+atomic_add 2
+atomic_add_negative 97
+atomic_dec_and_test 5153
+atomic_inc 470
+atomic_inc_and_test 1
+[...]
+</screen>
+</example>
+
+
+	</section>
+
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
index d3d592ca..7145b622 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
@@ -28,7 +28,7 @@
 	<xi:include href="Useful_Scripts-paracallgraph.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Useful_Scripts-inodewatch.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Useful_Scripts-inodewatch2.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />	
-	
+	<xi:include href="Useful_Scripts-functioncalls.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 <!--	<xi:include href="Useful_Scripts-Network.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Useful_Scripts-Signals.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Useful_Scripts-Syscalls.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />