Add xml documentation for memory.stp.

4 files changed, 366 insertions, 36 deletions

diff --git a/doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.xml b/doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.xml
index f10159b8..404b6543 100644
--- a/doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.xml
+++ b/doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.xml
@@ -8,6 +8,7 @@
 <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 <xi:include href="Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 <xi:include href="context.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<xi:include href="memory.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 <xi:include href="networking.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 <xi:include href="timestamp.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
diff --git a/doc/SystemTap_Tapset_Reference/en-US/memory.xml b/doc/SystemTap_Tapset_Reference/en-US/memory.xml
new file mode 100644
index 00000000..7bceaa16
--- /dev/null
+++ b/doc/SystemTap_Tapset_Reference/en-US/memory.xml
@@ -0,0 +1,182 @@
+<?xml version='1.0'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<!-- This file is extracted from the tapset files 
+   Do not modify this file -->
+<chapter id="memory_stp">
+  <title>Memory Tapset</title>
+  <para>
+	This family of probe  points is used to probe page fault events.
+     It contains the following probe points:
+  </para>
+<formalpara id="vm.pagefault">
+  <title>vm.pagefault</title>
+  <indexterm><primary>vm.pagefault</primary></indexterm>
+  <para>
+    Records that a page fault occurred.
+    The context is the process which triggered the fault.</para>
+</formalpara>
+<para>
+  <variablelist><title>Arguments:</title>
+    <varlistentry><term>address</term>
+       <listitem><para>
+         The address of the faulting memory access.
+       </para></listitem>
+    </varlistentry>
+    <varlistentry><term>write_access</term>
+       <listitem><para>
+          Indicates whether this was a write.
+       </para></listitem>
+    </varlistentry>
+  </variablelist>
+</para>
+<formalpara id="vm.pagefault.return">
+  <title>vm.pagefault.return</title>
+  <indexterm><primary>vm.pagefault.return</primary></indexterm>
+  <para>
+    Records type of fault that occurred.
+    The context is the process which triggered the fault.
+  </para>
+</formalpara>
+<para>
+  <variablelist><title>Arguments:</title>
+    <varlistentry><term>fault_type</term>
+      <listitem><para>The possible values of fault_type are:
+        <table frame='all'><title>Fault values</title>
+        <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+        <colspec colname='Define'/>
+        <colspec colname='Value'/>
+        <colspec colname='Reason'/>
+	   <thead>
+   	   <row><entry>Define</entry><entry>Value</entry><entry>Reason</entry></row>
+	   </thead>
+	   <tbody>
+	   <row>
+	     <entry>VM_FAULT_OOM</entry>
+	     <entry>0</entry>
+	     <entry>out of memory</entry>
+	   </row>
+	   <row>
+		<entry>VM_FAULT_SIGBUS</entry>
+		<entry>1</entry>
+		<entry>if not oom, minor, or major fault, this val</entry>
+	   </row>
+	   <row>
+		<entry>VM_FAULT_MINOR</entry>
+		<entry>2</entry>
+		<entry>no blocking operation to handle fault</entry>
+	   </row>
+	   <row>
+		<entry>VM_FAULT_MAJOR</entry>
+		<entry>3</entry>
+		<entry>required blocking operation to handle fault</entry>
+	   </row>
+	 </tbody>
+	 </tgroup>
+	 </table>
+      </para></listitem>
+    </varlistentry>
+  </variablelist>
+</para>
+<formalpara id="vm.write_shared">
+  <title>vm.write_shared</title>
+  <indexterm><primary>vm.write_shared</primary></indexterm>
+  <para>
+    Fires when a process attempts to write to a shared page.
+    If a copy is necessary, this will be followed by a
+    <xref linkend="vm.write_shared_copy"/>.
+    The context is the process attempting the write.
+  </para>
+</formalpara>
+<para>
+  <variablelist><title>Arguments:</title>
+    <varlistentry><term>address</term>
+       <listitem><para>The address of the shared write.</para></listitem>
+    </varlistentry>
+  </variablelist>
+</para>
+<formalpara id="vm.write_shared_copy">
+  <title>vm.write_shared_copy</title>
+  <indexterm><primary>vm.write_shared_copy</primary></indexterm>
+  <para>
+    Fires when a write to a shared page requires a page copy.
+    This is always preceded by a <xref linkend="vm.write_shared"/>.
+    The context is the process attempting the write.
+</para>
+</formalpara>
+<para>
+  <variablelist><title>Arguments:</title>
+    <varlistentry><term>address</term>
+       <listitem><para>
+	    The address of the shared write.
+       </para></listitem>
+    </varlistentry>
+    <varlistentry><term>zero</term>
+       <listitem><para>
+	  Boolean indicating whether it is a zero page
+       (can do a clear instead of a copy).
+       </para></listitem>
+    </varlistentry>
+  </variablelist>
+</para>
+<formalpara id="vm.mmap">
+  <title>vm.mmap</title>
+  <indexterm><primary>vm.mmap</primary></indexterm>
+  <para>
+    Fires when an mmap is requested. 
+    The context is the process calling mmap.
+  </para>
+</formalpara>
+<para>
+  <variablelist><title>Arguments:</title>
+    <varlistentry><term>address</term>
+      <listitem><para>The requested address.</para></listitem>
+    </varlistentry>
+    <varlistentry><term>length</term>
+      <listitem><para>The length of the memory segment.</para></listitem>
+    </varlistentry>
+  </variablelist>
+</para>
+<formalpara id="vm.munmap">
+  <title>vm.munmap</title>
+  <indexterm><primary>vm.munmap</primary></indexterm>
+  <para>Fires when an munmap is requested.</para>
+</formalpara>
+<para>
+  <variablelist><title>Arguments:</title>
+    <varlistentry><term>address</term>
+       <listitem><para>The requested address.</para></listitem>
+    </varlistentry>
+    <varlistentry><term>length</term>
+       <listitem><para>The length of the memory segment.</para></listitem>
+    </varlistentry>
+  </variablelist>
+</para>
+<formalpara id="vm.brk">
+  <title>vm.brk</title>
+  <indexterm><primary>vm.brk</primary></indexterm>
+  <para>Fires when a brk is requested (resizing a heap).</para>
+</formalpara>
+<para>
+  <variablelist><title>Arguments:</title>
+    <varlistentry><term>address</term>
+       <listitem><para>The requested address.</para></listitem>
+    </varlistentry>
+    <varlistentry><term>length</term>
+       <listitem><para>The length of the memory segment.</para></listitem>
+    </varlistentry>
+  </variablelist>
+</para>
+<formalpara id="vm.oom_kill">
+  <title>vm.oom_kill</title>
+  <indexterm><primary>vm.oom_kill</primary></indexterm>
+  <para>Fires when a thread is targetted by the OOM killer.</para>
+</formalpara>
+<para>
+  <variablelist><title>Arguments:</title>
+    <varlistentry><term>task</term>
+       <listitem><para>The task being killed.</para></listitem>
+    </varlistentry>
+  </variablelist>
+</para>
+</chapter>
diff --git a/tapset/ChangeLog b/tapset/ChangeLog
index 48dcf38a..f895e7ce 100644
--- a/tapset/ChangeLog
+++ b/tapset/ChangeLog
@@ -1,3 +1,7 @@
+2008-11-13  William Cohen  <wcohen@redhat.com>
+	
+	* memory.stp: Add xml documentation.
+
 2008-11-12  William Cohen  <wcohen@redhat.com>
 
 	* context.stp: Remove cpuid() documentation.
diff --git a/tapset/memory.stp b/tapset/memory.stp
index a2d9cc19..03568ad0 100644
--- a/tapset/memory.stp
+++ b/tapset/memory.stp
@@ -7,17 +7,34 @@
 // Public License (GPL); either version 2, or (at your option) any
 // later version.
 
-/* probe vm.pagefault
- *
- *  Records that a page fault occurred.
- *
- * Context:
- *  The process which triggered the fault.
- *
- * Arguments:
- *  address - the address of the faulting memory access.
- *  write_access - indicates whether this was a write
- */
+///<chapter id="memory_stp">
+///  <title>Memory Tapset</title>
+///  <para>
+///	This family of probe  points is used to probe page fault events.
+///     It contains the following probe points:
+///  </para>
+
+///<formalpara id="vm.pagefault">
+///  <title>vm.pagefault</title>
+///  <indexterm><primary>vm.pagefault</primary></indexterm>
+///  <para>
+///    Records that a page fault occurred.
+///    The context is the process which triggered the fault.</para>
+///</formalpara>
+///<para>
+///  <variablelist><title>Arguments:</title>
+///    <varlistentry><term>address</term>
+///       <listitem><para>
+///         The address of the faulting memory access.
+///       </para></listitem>
+///    </varlistentry>
+///    <varlistentry><term>write_access</term>
+///       <listitem><para>
+///          Indicates whether this was a write.
+///       </para></listitem>
+///    </varlistentry>
+///  </variablelist>
+///</para>
 probe vm.pagefault = kernel.function("__handle_mm_fault@mm/memory.c") ?,
                      kernel.function("handle_mm_fault@mm/memory.c") ?
 {
@@ -25,20 +42,54 @@ probe vm.pagefault = kernel.function("__handle_mm_fault@mm/memory.c") ?,
 	address =  $address
 }
 
-/* probe vm.pagefault.return
- *
- *  Records type of fault that occurred.
- *
- * Context:
- *  The process which triggered the fault.
- *
- * Arguments:
- *  fault_type - type of fault
- *	VM_FAULT_OOM	0	out of memory
- *	VM_FAULT_SIGBUS	1	if not oom, minor, or major fault, this val
- *	VM_FAULT_MINOR	2	no blocking operation to handle fault
- *	VM_FAULT_MAJOR	3	required blocking operation to handle fault
- */
+///<formalpara id="vm.pagefault.return">
+///  <title>vm.pagefault.return</title>
+///  <indexterm><primary>vm.pagefault.return</primary></indexterm>
+///  <para>
+///    Records type of fault that occurred.
+///    The context is the process which triggered the fault.
+///  </para>
+///</formalpara>
+///<para>
+///  <variablelist><title>Arguments:</title>
+///    <varlistentry><term>fault_type</term>
+///      <listitem><para>The possible values of fault_type are:
+///        <table frame='all'><title>Fault values</title>
+///        <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+///        <colspec colname='Define'/>
+///        <colspec colname='Value'/>
+///        <colspec colname='Reason'/>
+///	   <thead>
+///   	   <row><entry>Define</entry><entry>Value</entry><entry>Reason</entry></row>
+///	   </thead>
+///	   <tbody>
+///	   <row>
+///	     <entry>VM_FAULT_OOM</entry>
+///	     <entry>0</entry>
+///	     <entry>out of memory</entry>
+///	   </row>
+///	   <row>
+///		<entry>VM_FAULT_SIGBUS</entry>
+///		<entry>1</entry>
+///		<entry>if not oom, minor, or major fault, this val</entry>
+///	   </row>
+///	   <row>
+///		<entry>VM_FAULT_MINOR</entry>
+///		<entry>2</entry>
+///		<entry>no blocking operation to handle fault</entry>
+///	   </row>
+///	   <row>
+///		<entry>VM_FAULT_MAJOR</entry>
+///		<entry>3</entry>
+///		<entry>required blocking operation to handle fault</entry>
+///	   </row>
+///	 </tbody>
+///	 </tgroup>
+///	 </table>
+///      </para></listitem>
+///    </varlistentry>
+///  </variablelist>
+///</para>
 probe vm.pagefault.return = kernel.function("__handle_mm_fault@mm/memory.c").return ?,
                             kernel.function("handle_mm_fault@mm/memory.c").return ?
 {
@@ -65,22 +116,52 @@ function _IS_ZERO_PAGE:long(from:long, vaddr:long) %{ /* pure */
 %}
 
 
-/* probe vm.write_shared
- *
- *  Fires when a process attempts to write to a shared page.  If a
- *  copy is necessary, this will be followed by a vm.write_shared_copy.
- *
- * Context:
- *  The process attempting the write.
- *
- * Arguments:
- *  address - the address of the shared write.
- */
+///<formalpara id="vm.write_shared">
+///  <title>vm.write_shared</title>
+///  <indexterm><primary>vm.write_shared</primary></indexterm>
+///  <para>
+///    Fires when a process attempts to write to a shared page.
+///    If a copy is necessary, this will be followed by a
+///    <xref linkend="vm.write_shared_copy"/>.
+///    The context is the process attempting the write.
+///  </para>
+///</formalpara>
+///<para>
+///  <variablelist><title>Arguments:</title>
+///    <varlistentry><term>address</term>
+///       <listitem><para>The address of the shared write.</para></listitem>
+///    </varlistentry>
+///  </variablelist>
+///</para>
 probe vm.write_shared = kernel.function("do_wp_page") {
     address = $address
 }
 
 
+///<formalpara id="vm.write_shared_copy">
+///  <title>vm.write_shared_copy</title>
+///  <indexterm><primary>vm.write_shared_copy</primary></indexterm>
+///  <para>
+///    Fires when a write to a shared page requires a page copy.
+///    This is always preceded by a <xref linkend="vm.write_shared"/>.
+///    The context is the process attempting the write.
+///</para>
+///</formalpara>
+///<para>
+///  <variablelist><title>Arguments:</title>
+///    <varlistentry><term>address</term>
+///       <listitem><para>
+///	    The address of the shared write.
+///       </para></listitem>
+///    </varlistentry>
+///    <varlistentry><term>zero</term>
+///       <listitem><para>
+///	  Boolean indicating whether it is a zero page
+///       (can do a clear instead of a copy).
+///       </para></listitem>
+///    </varlistentry>
+///  </variablelist>
+///</para>
 /* probe vm.write_shared_copy
  *
  *  Fires when a write to a shared page requires a page copy.  This is
@@ -100,6 +181,24 @@ probe vm.write_shared_copy = kernel.function("copy_cow_page")? {
 }
 
 
+///<formalpara id="vm.mmap">
+///  <title>vm.mmap</title>
+///  <indexterm><primary>vm.mmap</primary></indexterm>
+///  <para>
+///    Fires when an mmap is requested. 
+///    The context is the process calling mmap.
+///  </para>
+///</formalpara>
+///<para>
+///  <variablelist><title>Arguments:</title>
+///    <varlistentry><term>address</term>
+///      <listitem><para>The requested address.</para></listitem>
+///    </varlistentry>
+///    <varlistentry><term>length</term>
+///      <listitem><para>The length of the memory segment.</para></listitem>
+///    </varlistentry>
+///  </variablelist>
+///</para>
 /* probe vm.mmap
  *
  *  Fires when an mmap is requested.
@@ -117,6 +216,21 @@ probe vm.mmap = kernel.function("do_mmap"), kernel.function("do_mmap2")? {
 }
 
 
+///<formalpara id="vm.munmap">
+///  <title>vm.munmap</title>
+///  <indexterm><primary>vm.munmap</primary></indexterm>
+///  <para>Fires when an munmap is requested.</para>
+///</formalpara>
+///<para>
+///  <variablelist><title>Arguments:</title>
+///    <varlistentry><term>address</term>
+///       <listitem><para>The requested address.</para></listitem>
+///    </varlistentry>
+///    <varlistentry><term>length</term>
+///       <listitem><para>The length of the memory segment.</para></listitem>
+///    </varlistentry>
+///  </variablelist>
+///</para>
 /* probe vm.munmap
  *
  *  Fires when an munmap is requested.
@@ -133,6 +247,21 @@ probe vm.munmap = kernel.function("do_munmap") {
     length = $len
 }
 
+///<formalpara id="vm.brk">
+///  <title>vm.brk</title>
+///  <indexterm><primary>vm.brk</primary></indexterm>
+///  <para>Fires when a brk is requested (resizing a heap).</para>
+///</formalpara>
+///<para>
+///  <variablelist><title>Arguments:</title>
+///    <varlistentry><term>address</term>
+///       <listitem><para>The requested address.</para></listitem>
+///    </varlistentry>
+///    <varlistentry><term>length</term>
+///       <listitem><para>The length of the memory segment.</para></listitem>
+///    </varlistentry>
+///  </variablelist>
+///</para>
 /* probe vm.brk
  *
  *  Fires when a brk is requested (resizing a heap).
@@ -149,6 +278,18 @@ probe vm.brk = kernel.function("do_brk") {
     length = $len
 }
 
+///<formalpara id="vm.oom_kill">
+///  <title>vm.oom_kill</title>
+///  <indexterm><primary>vm.oom_kill</primary></indexterm>
+///  <para>Fires when a thread is targetted by the OOM killer.</para>
+///</formalpara>
+///<para>
+///  <variablelist><title>Arguments:</title>
+///    <varlistentry><term>task</term>
+///       <listitem><para>The task being killed.</para></listitem>
+///    </varlistentry>
+///  </variablelist>
+///</para>
 /* probe vm.oom_kill
  *
  *  Fires when a thread is targetted by the OOM killer.
@@ -163,3 +304,5 @@ probe vm.brk = kernel.function("do_brk") {
 probe vm.oom_kill = kernel.function("__oom_kill_task") {
     task = $p
 }
+
+///</chapter>