Add documentation for context.stp and networking.stp.

5 files changed, 664 insertions, 7 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>
diff --git a/tapset/context.stp b/tapset/context.stp
index 017c934c..ff8db87b 100644
--- a/tapset/context.stp
+++ b/tapset/context.stp
@@ -7,12 +7,37 @@
 // Public License (GPL); either version 2, or (at your option) any
 // later version.
 
+///<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>
 function print_regs () %{
 	if (CONTEXT->regs) {
 		_stp_print_regs (CONTEXT->regs);
 	}
 %}
 
+///<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>
 function print_backtrace () %{
 	if (CONTEXT->regs) {
 		_stp_stack_print(CONTEXT->regs, 1, CONTEXT->pi, MAXTRACE);
@@ -21,6 +46,14 @@ function print_backtrace () %{
 	}
 %}
 
+///<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>
 function backtrace:string () %{ /* pure */
 	if (CONTEXT->regs)
 		_stp_stack_snprint (THIS->__retvalue, MAXSTRINGLEN, CONTEXT->regs, 0, CONTEXT->pi, MAXTRACE);
@@ -28,18 +61,46 @@ function backtrace:string () %{ /* pure */
 		strlcpy (THIS->__retvalue, "", MAXSTRINGLEN);
 %}
 
+///<formalpara id="execname">
+///  <title>execname:string()</title>
+///  <indexterm><primary>execname</primary></indexterm>
+///  <para>
+///     Return the name of the current process.
+///  </para>
+///</formalpara>
 function execname:string () %{ /* pure */
 	strlcpy (THIS->__retvalue, current->comm, MAXSTRINGLEN);
 %}
 
+///<formalpara id="pid">
+///  <title>pid:long ()</title>
+///  <indexterm><primary>pid</primary></indexterm>
+///  <para>
+///	Return the id of the current process.
+///  </para>
+///</formalpara>
 function pid:long () %{ /* pure */
 	THIS->__retvalue = current->tgid;
 %}
 
+///<formalpara id="tid">
+///  <title>tid:long()</title>
+///  <indexterm><primary>tid</primary></indexterm>
+///  <para>
+///	Return the id of the current thread.
+///  </para>
+///</formalpara>
 function tid:long () %{ /* pure */
 	THIS->__retvalue = current->pid;
 %}
 
+///<formalpara id="ppid">
+///  <title>ppid:long()</title>
+///  <indexterm><primary>ppid</primary></indexterm>
+///  <para>
+///	Return the id of the parent process.
+///  </para>
+///</formalpara>
 function ppid:long () %{ /* pure */
 #if defined(STAPCONF_REAL_PARENT)
 	THIS->__retvalue = current->real_parent->tgid;
@@ -48,6 +109,13 @@ function ppid:long () %{ /* pure */
 #endif
 %}
 
+///<formalpara id="pexecname">
+///  <title>pexecname:string()</title>
+///  <indexterm><primary>pexecname</primary></indexterm>
+///  <para>
+///	Return the name of the parent process.
+///  </para>
+///</formalpara>
 function pexecname:string () %{ /* pure */
 #if defined(STAPCONF_REAL_PARENT)
 	strlcpy (THIS->__retvalue, current->real_parent->comm, MAXSTRINGLEN);
@@ -56,30 +124,86 @@ function pexecname:string () %{ /* pure */
 #endif
 %}
 
+///<formalpara id="gid">
+///  <title>gid:long()</title>
+///  <indexterm><primary>gid</primary></indexterm>
+///  <para>
+///	Return the gid of the current process.
+///  </para>
+///</formalpara>
 function gid:long () %{ /* pure */
 	THIS->__retvalue = current->gid;		
 %}
 
+///<formalpara id="egid">
+///  <title>egid:long()</title>
+///  <indexterm><primary>egid</primary></indexterm>
+///  <para>
+///    Return the effective gid of the current process.
+///  </para>
+///</formalpara>
 function egid:long () %{ /* pure */
 	THIS->__retvalue = current->egid;		
 %}
 
+///<formalpara id="uid">
+///  <title>uid:long()</title>
+///  <indexterm><primary>uid</primary></indexterm>
+///  <para>
+///	Return the uid of the current process.
+///  </para>
+///</formalpara>
 function uid:long () %{ /* pure */
 	THIS->__retvalue = current->uid;		
 %}
 
+///<formalpara id="euid">
+///  <title>euid:long()</title>
+///  <indexterm><primary>euid</primary></indexterm>
+///  <para>
+///	Return the effective uid of the current process.
+///  </para>
+///</formalpara>
 function euid:long () %{ /* pure */
 	THIS->__retvalue = current->euid;		
 %}
 
+///<formalpara id="cpuid">
+///  <title>cpuid:long()</title>
+///  <indexterm><primary>cpuid</primary></indexterm>
+///  <para>
+///     Return the current cpu number.
+///  </para>
+///</formalpara>
+// FIXME is cpuid() or cpu() depricated?
 function cpuid:long () %{ /* pure */
 	THIS->__retvalue = smp_processor_id();
 %}
 
+///<formalpara id="cpu">
+///  <title>cpu:long()</title>
+///  <indexterm><primary>cpu</primary></indexterm>
+///  <para>
+///     Return the current cpu number.
+///  </para>
+///</formalpara>
+// FIXME is cpuid() or cpu() depricated?
 function cpu:long () %{ /* pure */
 	THIS->__retvalue = smp_processor_id();
 %}
 
+///<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>
 function print_stack(stk:string) %{
 	char *ptr = THIS->stk;
 	char *tok = strsep(&ptr, " ");
@@ -91,10 +215,25 @@ function print_stack(stk:string) %{
 	}
 %}
 
+///<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>
 function pp:string () %{ /* pure */
 	strlcpy (THIS->__retvalue, CONTEXT->probe_point, MAXSTRINGLEN);
 %}
 
+///<formalpara id="probefunc">
+///  <title>probefunc:string()</title>
+///  <indexterm><primary>probefunc</primary></indexterm>
+///  <para>
+///	Return the probe point's function name, if known.
+///  </para>
+///</formalpara>
 function probefunc:string () %{ /* pure */
 	char *ptr, *start;
 
@@ -126,6 +265,13 @@ function probefunc:string () %{ /* pure */
 	}
 %}
 
+///<formalpara id="probemod">
+///  <title>probemod:string()</title>
+///  <indexterm><primary>probemod</primary></indexterm>
+///  <para>
+///	Return the probe point's module name, if known.
+///  </para>
+///</formalpara>
 function probemod:string () %{ /* pure */
 	char *ptr, *start;
 
@@ -144,10 +290,27 @@ function probemod:string () %{ /* pure */
 	}
 %}
 
+///<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>
 function registers_valid:long () %{ /* pure */
 	THIS->__retvalue = (CONTEXT->regs != NULL);
 %}
 
+///<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>
 function user_mode:long () %{ /* pure */ /* currently a user-mode address? */
   if (CONTEXT->regs) {
 #if defined(__i386__) || defined(__x86_64__)
@@ -160,6 +323,14 @@ function user_mode:long () %{ /* pure */ /* currently a user-mode address? */
   }
 %}
 
+///<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>
 function is_return:long () %{ /* pure */
 	if (CONTEXT->pi)
 		THIS->__retvalue = 1;
@@ -167,37 +338,83 @@ function is_return:long () %{ /* pure */
 		THIS->__retvalue = 0;	
 %}
 
+///<formalpara id="target">
+///  <title>target:long()</title>
+///  <indexterm><primary>target</primary></indexterm>
+///  <para>
+///	Return the pid of the target process.
+///  </para>
+///</formalpara>
 function target:long () %{ /* pure */
         THIS->__retvalue = _stp_target;
 %}
 
+///<formalpara id="module_name">
+///  <title>module_name:string()</title>
+///  <indexterm><primary>module_name</primary></indexterm>
+///  <para>
+///	FIXME: need description.
+///  </para>
+///</formalpara>
 function module_name:string () %{ /* pure */
 	strlcpy(THIS->__retvalue, THIS_MODULE->name, MAXSTRINGLEN);
 %}
 
+///<formalpara id="stp_pid">
+///  <title>stp_pid:long()</title>
+///  <indexterm><primary>stp_pid</primary></indexterm>
+///  <para>
+///	FIXME: need description.
+///  </para>
+///</formalpara>
 function stp_pid:long () %{ /* pure */
         THIS->__retvalue = _stp_pid;
 %}
 
-# return the size of the stack
+///<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>
 function stack_size:long () %{ /* pure */
         THIS->__retvalue = THREAD_SIZE;
 %}
 
-# return how many bytes are currently used in the stack
+///<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>
 function stack_used:long () %{ /* pure */
 	char a;
         THIS->__retvalue = THREAD_SIZE - ((long)&a & (THREAD_SIZE-1));
 %}
 
-# return how many bytes are currently unused in the stack
+///<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>
 function stack_unused:long () %{ /* pure */
 	char a;
         THIS->__retvalue = (long)&a & (THREAD_SIZE-1);
 %}
 
-# Return the address of the calling function. Works only for
-# return probes at this time.
+///<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>
 function caller_addr:long () %{ /* pure */
         if (CONTEXT->pi)
 		THIS->__retvalue = (int64_t)(long)_stp_ret_addr_r(CONTEXT->pi);
@@ -205,8 +422,14 @@ function caller_addr:long () %{ /* pure */
 		THIS->__retvalue = 0;
 %}
 
-# Return the address and name of the calling function. Works 
-# only for return probes at this time.
+///<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>
 function caller:string() %{ /* pure */
         if (CONTEXT->pi) 
 		_stp_symbol_snprint( THIS->__retvalue, MAXSTRINGLEN, 
@@ -214,3 +437,5 @@ function caller:string() %{ /* pure */
         else
 		strlcpy(THIS->__retvalue,"unknown",MAXSTRINGLEN);
 %}
+
+///</chapter>
diff --git a/tapset/networking.stp b/tapset/networking.stp
index f32953fd..9bd742da 100644
--- a/tapset/networking.stp
+++ b/tapset/networking.stp
@@ -6,10 +6,72 @@
 // Public License (GPL); either version 2, or (at your option) any
 // later version.
 
+///<chapter id="networking.stp">
+///  <title>Networking Tapset</title>
+///  <para>
+///	This family of probe points is used to probe the activities of
+///     network device. 
+///  </para>
+
 %{
 #include <linux/netdevice.h>
 %}
 
+///<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>
 /* Main device receive routine, be called when packet arrives on network device */
 probe netdev.receive
 	=  kernel.function("netif_receive_skb")
@@ -20,6 +82,39 @@ probe netdev.receive
 	truesize = $skb->truesize
 }
 
+///<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>
 /* Queue a buffer for transmission to a network device */
 probe netdev.transmit
 	=  kernel.function("dev_queue_xmit")
@@ -29,3 +124,5 @@ probe netdev.transmit
 	protocol = $skb->protocol
 	truesize = $skb->truesize
 }
+
+///</chapter>