Add documentation for context.stp and networking.stp.

1 files changed, 232 insertions, 7 deletions

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>