Add documentation for context.stp and networking.stp.

3 files changed, 335 insertions, 0 deletions

diff --git a/doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.xml b/doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.xml
index 4603b238..f10159b8 100644
--- a/doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.xml
+++ b/doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.xml
@@ -7,6 +7,8 @@
 <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 <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="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" />
 <index />
diff --git a/doc/SystemTap_Tapset_Reference/en-US/context.xml b/doc/SystemTap_Tapset_Reference/en-US/context.xml
new file mode 100644
index 00000000..df271d0f
--- /dev/null
+++ b/doc/SystemTap_Tapset_Reference/en-US/context.xml
@@ -0,0 +1,233 @@
+<?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="context_stp">
+  <title>Context Functions</title>
+  <para>
+    The context functions provide additional information about the where
+    the event occurred.
+    The contact functions can provide information such as a backtrace
+    where the event occured
+    and the current register values for the processor.
+  </para>
+<formalpara id="print_regs">
+  <title>print_regs()</title>
+  <indexterm><primary>print_regs</primary></indexterm>
+  <para>
+	Print a register dump.
+  </para>
+</formalpara>
+<formalpara id="print_backtrace">
+  <title>print_backtrace()</title>
+  <indexterm><primary>print_backtrace</primary></indexterm>
+  <para>
+     Equivalent to <command>print_stack(backtrace())</command>,
+     except that deeper stack nesting may be supported.  Return nothing.
+  </para>
+</formalpara>
+<formalpara id="backtrace">
+  <title>backtrace:string()</title>
+  <indexterm><primary>backtrace</primary></indexterm>
+  <para>
+	Return a string of hex addresses that are a backtrace of the
+     stack.  It may be truncated due to maximum string length.
+  </para>
+</formalpara>
+<formalpara id="execname">
+  <title>execname:string()</title>
+  <indexterm><primary>execname</primary></indexterm>
+  <para>
+     Return the name of the current process.
+  </para>
+</formalpara>
+<formalpara id="pid">
+  <title>pid:long ()</title>
+  <indexterm><primary>pid</primary></indexterm>
+  <para>
+	Return the id of the current process.
+  </para>
+</formalpara>
+<formalpara id="tid">
+  <title>tid:long()</title>
+  <indexterm><primary>tid</primary></indexterm>
+  <para>
+	Return the id of the current thread.
+  </para>
+</formalpara>
+<formalpara id="ppid">
+  <title>ppid:long()</title>
+  <indexterm><primary>ppid</primary></indexterm>
+  <para>
+	Return the id of the parent process.
+  </para>
+</formalpara>
+<formalpara id="pexecname">
+  <title>pexecname:string()</title>
+  <indexterm><primary>pexecname</primary></indexterm>
+  <para>
+	Return the name of the parent process.
+  </para>
+</formalpara>
+<formalpara id="gid">
+  <title>gid:long()</title>
+  <indexterm><primary>gid</primary></indexterm>
+  <para>
+	Return the gid of the current process.
+  </para>
+</formalpara>
+<formalpara id="egid">
+  <title>egid:long()</title>
+  <indexterm><primary>egid</primary></indexterm>
+  <para>
+    Return the effective gid of the current process.
+  </para>
+</formalpara>
+<formalpara id="uid">
+  <title>uid:long()</title>
+  <indexterm><primary>uid</primary></indexterm>
+  <para>
+	Return the uid of the current process.
+  </para>
+</formalpara>
+<formalpara id="euid">
+  <title>euid:long()</title>
+  <indexterm><primary>euid</primary></indexterm>
+  <para>
+	Return the effective uid of the current process.
+  </para>
+</formalpara>
+<formalpara id="cpuid">
+  <title>cpuid:long()</title>
+  <indexterm><primary>cpuid</primary></indexterm>
+  <para>
+     Return the current cpu number.
+  </para>
+</formalpara>
+<formalpara id="cpu">
+  <title>cpu:long()</title>
+  <indexterm><primary>cpu</primary></indexterm>
+  <para>
+     Return the current cpu number.
+  </para>
+</formalpara>
+<formalpara id="print_stack">
+  <title>print_stack(stk:string)</title>
+  <indexterm><primary>print_stack</primary></indexterm>
+  <para>
+     Perform a symbolic lookup of the addresses in the given  string,
+     which  is  assumed  to  be  the  result of a prior call to 
+	<xref linkend="backtrace"/>.
+     Print one line per address, including the address, the
+     name  of the function containing the address, and an estimate of
+     its position within that function.  Return nothing.
+  </para>
+</formalpara>
+<formalpara id="pp">
+  <title>pp:string()</title>
+  <indexterm><primary>pp</primary></indexterm>
+  <para>
+     Return the probe point associated with the currently running
+     probe handler, including alias and wildcard expansion effects.
+  </para>
+</formalpara>
+<formalpara id="probefunc">
+  <title>probefunc:string()</title>
+  <indexterm><primary>probefunc</primary></indexterm>
+  <para>
+	Return the probe point's function name, if known.
+  </para>
+</formalpara>
+<formalpara id="probemod">
+  <title>probemod:string()</title>
+  <indexterm><primary>probemod</primary></indexterm>
+  <para>
+	Return the probe point's module name, if known.
+  </para>
+</formalpara>
+<formalpara id="registers_valid">
+  <title>registers_valid:long()</title>
+  <indexterm><primary>registers_valid</primary></indexterm>
+  <para>
+	Return 1 if register() and u_register() can be used
+     in the current context, or 0 otherwise.
+     For example, <command>registers_valid()</command> returns 0
+     when called from a begin or end probe.
+  </para>
+</formalpara>
+<formalpara id="user_mode">
+  <title>user_mode:long()</title>
+  <indexterm><primary>user_mode</primary></indexterm>
+  <para>
+	Return 1 if the probe point occurred in user-mode.
+  </para>
+</formalpara>
+<formalpara id="is_return">
+  <title>is_return:long()</title>
+  <indexterm><primary>is_return</primary></indexterm>
+  <para>
+	Return 1 if the probe point is a return probe.
+     <emphasis>Deprecated.</emphasis>
+  </para>
+</formalpara>
+<formalpara id="target">
+  <title>target:long()</title>
+  <indexterm><primary>target</primary></indexterm>
+  <para>
+	Return the pid of the target process.
+  </para>
+</formalpara>
+<formalpara id="module_name">
+  <title>module_name:string()</title>
+  <indexterm><primary>module_name</primary></indexterm>
+  <para>
+	FIXME: need description.
+  </para>
+</formalpara>
+<formalpara id="stp_pid">
+  <title>stp_pid:long()</title>
+  <indexterm><primary>stp_pid</primary></indexterm>
+  <para>
+	FIXME: need description.
+  </para>
+</formalpara>
+<formalpara id="stack_size">
+  <title>stack_size:long()</title>
+  <indexterm><primary>stack_size</primary></indexterm>
+  <para>
+	Return the size of the kernel stack.
+  </para>
+</formalpara>
+<formalpara id="stack_used">
+  <title>stack_used:long ()</title>
+  <indexterm><primary>stack_used</primary></indexterm>
+  <para>
+	Return how many bytes are currently used in the kernel stack.
+  </para>
+</formalpara>
+<formalpara id="stack_unused">
+  <title>stack_unused:long()</title>
+  <indexterm><primary>stack_unused</primary></indexterm>
+  <para>
+	Return how many bytes are currently available in the kernel stack.
+  </para>
+</formalpara>
+<formalpara id="caller_addr">
+  <title>caller_addr:long()</title>
+  <indexterm><primary>caller_addr</primary></indexterm>
+  <para>
+    Return the address of the calling function.
+    <emphasis> Works only for return probes at this time.</emphasis>
+	
+  </para>
+</formalpara>
+<formalpara id="caller">
+  <title>caller:string()</title>
+  <indexterm><primary>caller</primary></indexterm>
+  <para>
+     Return the address and name of the calling function.
+	<emphasis>Works only for return probes at this time.</emphasis>
+  </para>
+</formalpara>
+</chapter>
diff --git a/doc/SystemTap_Tapset_Reference/en-US/networking.xml b/doc/SystemTap_Tapset_Reference/en-US/networking.xml
new file mode 100644
index 00000000..ce93739b
--- /dev/null
+++ b/doc/SystemTap_Tapset_Reference/en-US/networking.xml
@@ -0,0 +1,100 @@
+<?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="networking.stp">
+  <title>Networking Tapset</title>
+  <para>
+	This family of probe points is used to probe the activities of
+     network device. 
+  </para>
+<formalpara id="netdev.receive">
+  <title>netdev.receive</title>
+  <indexterm><primary>netdev.receive</primary></indexterm>
+  <para>Fires when data arrives on network device.</para>
+</formalpara>
+<para>
+  <variablelist><title>Arguments:</title>
+    <varlistentry><term>dev_name</term>
+       <listitem><para>
+          The name of the device. e.g: eth0, ath1
+       </para></listitem>
+    </varlistentry>
+
+    <varlistentry><term>length</term>
+       <listitem><para>
+           The length of the receiving buffer
+       </para></listitem>
+    </varlistentry>
+
+    <varlistentry><term>protocol</term>
+       <listitem><para>The possible values of protocol could be:
+         <table frame='all'><title>Protocol Values</title>
+         <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+         <colspec colname='Value'/>
+         <colspec colname='Protocol'/>
+	    <thead>
+   	    <row><entry>Value</entry><entry>Protocol</entry></row>
+	    </thead>
+	    <tbody>
+   	    <row><entry>0800</entry><entry>IP</entry></row>
+   	    <row><entry>8100</entry><entry>802.1Q VLAN</entry></row>
+   	    <row><entry>0001</entry><entry>802.3</entry></row>
+   	    <row><entry>0002</entry><entry>AX.25</entry></row>
+   	    <row><entry>0004</entry><entry>802.2</entry></row>
+   	    <row><entry>8035</entry><entry>RARP</entry></row>
+   	    <row><entry>0005</entry><entry>SNAP</entry></row>
+   	    <row><entry>0805</entry><entry>X.25</entry></row>
+   	    <row><entry>0806</entry><entry>ARP</entry></row>
+   	    <row><entry>8137</entry><entry>IPX</entry></row>
+   	    <row><entry>0009</entry><entry>Localtalk</entry></row>
+   	    <row><entry>86DD</entry><entry>IPv6</entry></row>
+	    </tbody>
+	    </tgroup>
+	    </table>
+       </para></listitem>
+    </varlistentry>
+
+    <varlistentry><term>truesize</term>
+       <listitem><para>
+           The size of the received data.
+       </para></listitem>
+    </varlistentry>
+
+  </variablelist>
+</para>
+<formalpara id="netdev.transmit">
+  <title>netdev.transmit</title>
+  <indexterm><primary>netdev.transmit</primary></indexterm>
+  <para> Fires when the network device wants to transmit a buffer.</para>
+</formalpara>
+<para>
+  <variablelist><title>Arguments:</title>
+    <varlistentry><term>dev_name</term>
+       <listitem><para>
+          The name of the device. e.g: eth0, ath1
+       </para></listitem>
+    </varlistentry>
+
+    <varlistentry><term>length</term>
+       <listitem><para>
+         The length of the transmit buffer
+       </para></listitem>
+    </varlistentry>
+
+    <varlistentry><term>protocol</term>
+       <listitem><para>
+         The protocol of this packet.
+       </para></listitem>
+    </varlistentry>
+
+    <varlistentry><term>truesize</term>
+       <listitem><para>
+         The size of the the data to be transmitted.
+       </para></listitem>
+    </varlistentry>
+
+  </variablelist>
+</para>
+</chapter>