Merge branch 'master' of git://sources.redhat.com/git/systemtap

13 files changed, 173 insertions, 103 deletions

diff --git a/tapset/context-symbols.stp b/tapset/context-symbols.stp
index 46eab841..4a08ec60 100644
--- a/tapset/context-symbols.stp
+++ b/tapset/context-symbols.stp
@@ -6,7 +6,11 @@
 // redistribute it and/or modify it under the terms of the GNU General
 // Public License (GPL); either version 2, or (at your option) any
 // later version.
-
+// <tapsetdescription>
+// Context functions provide additional information about where an event occurred. These functions can 
+//provide information such as a backtrace to where the event occured and the current register values for the 
+//processor.
+// </tapsetdescription>
 %{
 #ifndef STP_NEED_SYMBOL_DATA
 #define STP_NEED_SYMBOL_DATA 1
diff --git a/tapset/context-unwind.stp b/tapset/context-unwind.stp
index a0836ed6..5c1253b8 100644
--- a/tapset/context-unwind.stp
+++ b/tapset/context-unwind.stp
@@ -6,7 +6,11 @@
 // redistribute it and/or modify it under the terms of the GNU General
 // Public License (GPL); either version 2, or (at your option) any
 // later version.
-
+// <tapsetdescription>
+// Context functions provide additional information about where an event occurred. These functions can 
+//provide information such as a backtrace to where the event occured and the current register values for the 
+//processor.
+// </tapsetdescription>
 %{
 #ifndef STP_NEED_UNWIND_DATA
 #define STP_NEED_UNWIND_DATA 1
diff --git a/tapset/context.stp b/tapset/context.stp
index 7fd961c8..f4b0207a 100644
--- a/tapset/context.stp
+++ b/tapset/context.stp
@@ -6,7 +6,11 @@
 // redistribute it and/or modify it under the terms of the GNU General
 // Public License (GPL); either version 2, or (at your option) any
 // later version.
-
+// <tapsetdescription>
+// Context functions provide additional information about where an event occurred. These functions can 
+//provide information such as a backtrace to where the event occured and the current register values for the 
+//processor.
+// </tapsetdescription>
 /**
  * sfunction print_regs - Print a register dump.
  */
diff --git a/tapset/ioscheduler.stp b/tapset/ioscheduler.stp
index d7a71aca..875ccea9 100644
--- a/tapset/ioscheduler.stp
+++ b/tapset/ioscheduler.stp
@@ -5,15 +5,17 @@
 // redistribute it and/or modify it under the terms of the GNU General
 // Public License (GPL); either version 2, or (at your option) any
 // later version.
-
+// <tapsetdescription>
+// This family of probe points is used to probe IO scheduler activities. 
+// </tapsetdescription>
 %{
 #include <linux/blkdev.h>
 #include <linux/elevator.h>
 %}
 
 /**
- * probe ioscheduler.elv_next_request - Retrieve request from request queue
- * @elevator_name: The elevator name
+ * probe ioscheduler.elv_next_request - Fires when a request is retrieved from the request queue
+ * @elevator_name: The type of I/O elevator currently enabled
  */
 probe ioscheduler.elv_next_request
 	=  kernel.function("elv_next_request")
@@ -26,7 +28,7 @@ probe ioscheduler.elv_next_request
 }
 
 /**
- * probe ioscheduler.elv_next_request.return - Return from retrieving a request
+ * probe ioscheduler.elv_next_request.return - Fires when a request retrieval issues a return signal
  * @req: Address of the request
  * @req_flags: Request flags
  * @disk_major: Disk major number of the request
@@ -58,14 +60,14 @@ probe ioscheduler.elv_next_request.return
 }
 
 /**
- * probe ioscheduler.elv_add_request - Add a request into request queue
- * @elevator_name: The elevator name
+ * probe ioscheduler.elv_add_request -A request was added to the request queue
+ * @elevator_name: The type of I/O elevator currently enabled
  * @req: Address of the request
  * @req_flags: Request flags
  * @disk_major: Disk major number of the request
  * @disk_minor: Disk minor number of the request
  */
-/* when a request is added to the request queue */
+// when a request is added to the request queue
 probe ioscheduler.elv_add_request
 	= kernel.function("__elv_add_request")
 {
@@ -96,8 +98,8 @@ probe ioscheduler.elv_add_request
 }
 
 /**
- * probe ioscheduler.elv_completed_request - Request is completed
- * @elevator_name: The elevator name
+ * probe ioscheduler.elv_completed_request - Fires when a request is completed
+ * @elevator_name: The type of I/O elevator currently enabled
  * @req: Address of the request
  * @req_flags: Request flags
  * @disk_major: Disk major number of the request
diff --git a/tapset/memory.stp b/tapset/memory.stp
index 961cca38..9dbe3fba 100644
--- a/tapset/memory.stp
+++ b/tapset/memory.stp
@@ -6,6 +6,9 @@
 // redistribute it and/or modify it under the terms of the GNU General
 // Public License (GPL); either version 2, or (at your option) any
 // later version.
+// <tapsetdescription>
+// This family of probe points is used to probe memory-related events. 
+// </tapsetdescription>
 %{
 #include <linux/mm.h>
 %}
@@ -97,7 +100,7 @@ function addr_to_node:long(addr:long) %{ /* pure */
 		}
 %}
 
-/* Return whether a page to be copied is a zero page. */
+// Return whether a page to be copied is a zero page.
 function _IS_ZERO_PAGE:long(from:long, vaddr:long) %{ /* pure */
     THIS->__retvalue = (THIS->from == (long) ZERO_PAGE(THIS->vaddr));
 %}
diff --git a/tapset/networking.stp b/tapset/networking.stp
index a147441a..f6d78536 100644
--- a/tapset/networking.stp
+++ b/tapset/networking.stp
@@ -5,7 +5,9 @@
 // redistribute it and/or modify it under the terms of the GNU General
 // Public License (GPL); either version 2, or (at your option) any
 // later version.
-
+// <tapsetdescription>
+// This family of probe points is used to probe the activities of the network device. 
+// </tapsetdescription>
 /**
  * probe netdev.receive - Data recieved from network device.
  * @dev_name: The name of the device. e.g: eth0, ath1.
@@ -49,7 +51,7 @@
 ///
 ///  </variablelist>
 ///</para>
-/* Main device receive routine, be called when packet arrives on network device */
+// Main device receive routine, be called when packet arrives on network device
 probe netdev.receive
 	=  kernel.function("netif_receive_skb")
 {
@@ -67,7 +69,7 @@ probe netdev.receive
  * @truesize: The size of the the data to be transmitted.
  *
  */
-/* Queue a buffer for transmission to a network device */
+// Queue a buffer for transmission to a network device
 probe netdev.transmit
 	=  kernel.function("dev_queue_xmit")
 {
diff --git a/tapset/process.stp b/tapset/process.stp
index ca49aa67..e39f740a 100644
--- a/tapset/process.stp
+++ b/tapset/process.stp
@@ -5,7 +5,9 @@
 // redistribute it and/or modify it under the terms of the GNU General
 // Public License (GPL); either version 2, or (at your option) any
 // later version.
-
+// <tapsetdescription>
+//  This family of probe points is used to probe process-related activities.
+// </tapsetdescription>
 
 function _IS_ERR:long(ptr:long) %{ /* pure */
     THIS->__retvalue = IS_ERR((const void *)(long)THIS->ptr);
diff --git a/tapset/scsi.stp b/tapset/scsi.stp
index 6d332e8b..8ff3dcca 100644
--- a/tapset/scsi.stp
+++ b/tapset/scsi.stp
@@ -5,7 +5,9 @@
 // redistribute it and/or modify it under the terms of the GNU General
 // Public License (GPL); either version 2, or (at your option) any
 // later version.
-
+// <tapsetdescription>
+// This family of probe points is used to probe SCSI activities.  
+// </tapsetdescription>
 %{
 #include <linux/types.h>
 #include <scsi/scsi_cmnd.h>
@@ -21,7 +23,7 @@
   * @disk_minor: The minor number of the disk (-1 if no information)
   * @device_state: The current state of the device.
   */
-/* FIXME describe the device_state */
+// FIXME describe the device_state
 probe scsi.ioentry
 	= module("scsi_mod").function("scsi_prep_fn@drivers/scsi/scsi_lib.c")?,
 	  kernel.function("scsi_prep_fn@drivers/scsi/scsi_lib.c")?
@@ -107,7 +109,7 @@ probe scsi.iodone
  *                  the device
  * @goodbytes: The bytes completed.
  */
-/* mid-layer processes the completed IO */
+// mid-layer processes the completed IO
 probe scsi.iocompleted
 	= module("scsi_mod").function("scsi_io_completion@drivers/scsi/scsi_lib.c")?,
 	  kernel.function("scsi_io_completion@drivers/scsi/scsi_lib.c")?
diff --git a/tapset/signal.stp b/tapset/signal.stp
index 8fb6fe57..711ee70f 100644
--- a/tapset/signal.stp
+++ b/tapset/signal.stp
@@ -8,16 +8,17 @@
 // Public License (GPL); either version 2, or (at your option) any
 // later version.
 //
-//   Note : Since there are so many signals sent to processes at any give
-//          point, it's better to filter the information according to the
-//          requirements.  For example, filter only for a particular signal
-//          (if sig==2) or filter only for a particular process
-//          (if pid_name==stap).
 //
-
+// <tapsetdescription>
+//  This family of probe points is used to probe signal activities.
+//  Since there are so many signals sent to processes at any given
+//  point, it is advisable to filter the information according to the
+//  requirements.  For example, filter only for a particular signal
+//  (if sig==2) or for a particular process (if pid_name==stap).
+// </tapsetdescription>
 
 /** 
- * probe signal.send- Fires when a system call or kernel function sends a signal to a process.
+ * probe signal.send - Signal being sent to a process
  * Arguments:
  * @sig: The number of the signal
  * @sig_name: A string representation of the signal
@@ -27,7 +28,8 @@
  * @task: A task handle to the signal recipient
  * @sinfo: The address of <command>siginfo</command> struct
  * @shared: Indicates whether the signal is shared by the thread group
- * @send2queue- Indicates whether the signal is sent to an existing <command>sigqueue</command>
+ * @send2queue: Indicates whether the signal is sent to an existing
+ * <command>sigqueue</command>
  * @name: The name of the function used to send out the signal
  * 
  * Context:
@@ -114,14 +116,14 @@ probe _signal.send.part3 = kernel.function("send_sigqueue")
 }
 
 /**
- * probe signal.send.return - Fires when a signal sent to a process returns.
+ * probe signal.send.return - Signal being sent to a process completed
  * @retstr: The return value to either <command>__group_send_sig_info</command>,
- * <command>specific_send_sig_info</command>, or <command>send_sigqueue</command>. 
- * Refer to the Description of this probe for more information about the return 
- * values of each function call. 
+ * <command>specific_send_sig_info</command>,
+ * or <command>send_sigqueue</command>
  * @shared: Indicates whether the sent signal is shared by the thread group.
- * @send2queue: Indicates whether the sent signal was sent to an existing <command>sigqueue</command>
- * @name: The name of the function used to send out the signal.
+ * @send2queue: Indicates whether the sent signal was sent to an
+ * existing <command>sigqueue</command>
+ * @name: The name of the function used to send out the signal
  * 
  * Context:
  * The signal's sender. <remark>(correct?)</remark>
@@ -129,24 +131,24 @@ probe _signal.send.part3 = kernel.function("send_sigqueue")
  * Possible <command>__group_send_sig_info</command> and 
  * <command>specific_send_sig_info</command> return values are as follows;
  *
- * <command>0</command> - The signal is sucessfully sent to a process,
+ * <command>0</command> -- The signal is sucessfully sent to a process,
  * which means that
  * <1> the signal was ignored by the receiving process,
  * <2> this is a non-RT signal and the system already has one queued, and
  * <3> the signal was successfully added to the <command>sigqueue</command> of the receiving process.
  *
- * <command>-EAGAIN</command> - The <command>sigqueue</command> of the receiving process is 
+ * <command>-EAGAIN</command> -- The <command>sigqueue</command> of the receiving process is 
  * overflowing, the signal was RT, and the signal was sent by a user using something other 
  * than <command>kill()</command> 
  * 
  * Possible <command>send_group_sigqueue</command> and 
  * <command>send_sigqueue</command> return values are as follows;
  * 
- * <command>0</command> - The signal was either sucessfully added into the
+ * <command>0</command> -- The signal was either sucessfully added into the
  * <command>sigqueue</command> of the receiving process, or a <command>SI_TIMER</command> entry is already
  * queued (in which case, the overrun count will be simply incremented).
  *
- * <command>1</command> - The signal was ignored by the receiving process.
+ * <command>1</command> -- The signal was ignored by the receiving process.
  *
  *
  * <command>-1</command> - (<command>send_sigqueue</command> only) The task was marked
@@ -232,7 +234,7 @@ probe _signal.send.part3.return = kernel.function("send_sigqueue").return
 }
 
 /**
- * probe signal.checkperm - Fires when a permission check is performed on a sent signal
+ * probe signal.checkperm - Check being performed on a sent signal
  * @sig: The number of the signal
  * @sig_name: A string representation of the signal
  * @sig_pid: The PID of the process receiving the signal
@@ -240,7 +242,8 @@ probe _signal.send.part3.return = kernel.function("send_sigqueue").return
  * @si_code: Indicates the signal type
  * @task: A task handle to the signal recipient
  * @sinfo: The address of the <command>siginfo</command> structure
- * @name: Name of the probe point; default value is <command>signal.checkperm</command>
+ * @name: Name of the probe point; default value is
+ * <command>signal.checkperm</command>
  */
 probe signal.checkperm = kernel.function("check_kill_permission")
 {
@@ -261,6 +264,12 @@ probe signal.checkperm = kernel.function("check_kill_permission")
         si_code="SI_USER or SI_TIMER or SI_ASYNCIO"
 }
 
+/**
+ * probe signal.checkperm.return - Check performed on a sent signal completed
+ * @name: Name of the probe point; default value is
+ * <command>signal.checkperm</command>
+ * @retstr: Return value as a string
+ */
 probe signal.checkperm.return = kernel.function("check_kill_permission").return
 {
     name = "signal.checkperm"
@@ -269,15 +278,15 @@ probe signal.checkperm.return = kernel.function("check_kill_permission").return
 
 
 /**
- * probe signal.wakeup - Wakes up a sleeping process, making it ready for new active signals
- * @sig_pid: The PID of the process you wish to wake
- * @pid_name: Name of the process you wish to wake
- * @resume: Indicates whether to wake up a task in a <command>STOPPED</command> or
- * <command>TRACED</command> state
+ * probe signal.wakeup - Sleeping process being wakened for signal
+ * @sig_pid: The PID of the process to wake
+ * @pid_name: Name of the process to wake
+ * @resume: Indicates whether to wake up a task in a
+ * <command>STOPPED</command> or <command>TRACED</command> state
  * @state_mask: A string representation indicating the mask
- * of task states you wish to wake. Possible values are <command>TASK_INTERRUPTIBLE</command>, 
- * <command>TASK_STOPPED</command>, <command>TASK_TRACED</command>, 
- * and <command>TASK_INTERRUPTIBLE</command>.
+ * of task states to wake. Possible values are
+ * <command>TASK_INTERRUPTIBLE</command>, <command>TASK_STOPPED</command>,
+ * <command>TASK_TRACED</command>, and <command>TASK_INTERRUPTIBLE</command>.
  */
 probe signal.wakeup = kernel.function("signal_wake_up")
 {
@@ -293,8 +302,7 @@ probe signal.wakeup = kernel.function("signal_wake_up")
 
 
 /**
- * probe signal.check_ignored - Fires when a system call or kernel function checks whether a 
- * signal was ignored or not
+ * probe signal.check_ignored - Checking to see signal is ignored
  * @sig_pid: The PID of the process receiving the signal 
  * @pid_name: Name of the process receiving the signal
  * @sig: The number of the signal
@@ -308,6 +316,12 @@ probe signal.check_ignored = kernel.function("sig_ignored")
     sig_name = _signal_name($sig)
 }
 
+/**
+ * probe signal.check_ignored.return - Check to see signal is ignored completed
+ * @name: Name of the probe point; default value is
+ * <command>signal.checkperm</command>
+ * @retstr: Return value as a string
+ */
 probe signal.check_ignored.return = kernel.function("sig_ignored").return ?
 {
     name = "sig_ignored"
@@ -333,8 +347,7 @@ probe signal.handle_stop = kernel.function("handle_stop_signal")
 
 
 /**
- * probe signal.force_segv - Fires when a system call, kernel function, or process sent a 
- * <command>SIGSEGV</command> as a result of problems it encountered while handling a received signal
+ * probe signal.force_segv - Forcing send of <command>SIGSEGV</command>
  * @sig_pid: The PID of the process receiving the signal
  * @pid_name: Name of the process receiving the signal
  * @sig: The number of the signal
@@ -360,6 +373,12 @@ probe _signal.force_segv.part2 = kernel.function("force_sigsegv_info") ?
     sig_name = _signal_name($sig)
 }
 
+/**
+ * probe signal.force_segv.return - Forcing send of <command>SIGSEGV</command> complete
+ * @name: Name of the probe point; default value is
+ * <command>force_sigsegv</command>
+ * @retstr: Return value as a string
+ */
 probe signal.force_segv.return =
 		kernel.function("force_sigsegv").return,
 		kernel.function("force_sigsegv_info").return ?
@@ -370,9 +389,8 @@ probe signal.force_segv.return =
 
 
 /**
- * probe signal.syskill - Fires when the kernel function <command>sys_kill</command> 
- * sends a kill signal to a process
- * @pid: The PID of the process receiving the kill signal
+ * probe signal.syskill - Sending kill signal to a process
+ * @pid: The PID of the process receiving the signal
  * @sig: The specific signal sent to the process
  */
 probe signal.syskill = syscall.kill
@@ -380,33 +398,43 @@ probe signal.syskill = syscall.kill
     sig_name = _signal_name($sig)
 }
 
+/**
+ * probe signal.syskill.return - Sending kill signal completed
+ */
 probe signal.syskill.return = syscall.kill.return
 {
 }
+
 /** 
- * probe signal.sys_tkill - Fires when <command>tkill</command> sends a kill signal 
- * to a process that is part of a thread group 
+ * probe signal.sys_tkill - Sending a kill signal to a thread
  * @pid: The PID of the process receiving the kill signal
  * @sig: The specific signal sent to the process
+ * @sig_name: The specific signal sent to the process
+ *
  * The <command>tkill</command> call is analogous to <command>kill(2)</command>,
  * except that it also allows a process within a specific thread group to
- * be targetted. Such processes are targetted through their unique thread IDs (TID). 
+ * be targetted. Such processes are targetted through their unique
+ * thread IDs (TID). 
  */
 probe signal.systkill = syscall.tkill
 {
     sig_name = _signal_name($sig)
 }
 
+/**
+ * probe signal.systkill.return - Sending kill signal to a thread completed
+ */
 probe signal.systkill.return = syscall.tkill.return
 {
 }
 
 /**
- * probe signal.sys_tgkill - Fires when the kernel function <command>tgkill</command> 
- * sends a kill signal to a specific thread group
+ * probe signal.sys_tgkill - Sending kill signal to a thread group
  * @pid: The PID of the thread receiving the kill signal
  * @tgid: The thread group ID of the thread receiving the kill signal
  * @sig: The specific kill signal sent to the process
+ * @sig_name: A string representation of the signal
+ *
  * The <command>tgkill</command> call is similar to <command>tkill</command>, 
  * except that it also allows the caller to specify the thread group ID of 
  * the thread to be signalled. This protects against TID reuse. 
@@ -416,12 +444,15 @@ probe signal.systgkill = syscall.tgkill
     sig_name = _signal_name($sig)
 }
 
+/**
+ * probe signal.sys_tgkill.return - Sending kill signal to a thread group completed
+ */
 probe signal.systgkill.return = syscall.tgkill.return
 {
 }
 
 /**
- * probe signal.send_sig_queue - Fires when a signal is queued to a process
+ * probe signal.send_sig_queue - Queuing a signal to a process
  * @sig: The queued signal
  * @sig_name: A string representation of the signal
  * @sig_pid: The PID of the process to which the signal is queued
@@ -439,6 +470,10 @@ probe signal.send_sig_queue =
     sigqueue_addr = $q
 }
 
+/**
+ * probe signal.send_sig_queue.return  - Queuing a signal to a process completed
+ * @retstr: Return value as a string
+ */
 probe signal.send_sig_queue.return =
         kernel.function("send_sigqueue").return,
         kernel.function("send_group_sigqueue").return ?
@@ -448,25 +483,25 @@ probe signal.send_sig_queue.return =
 
 
 /** 
- * probe signal.pending - Fires when the <command>SIGPENDING</command> system call is used;
- * this normally occurs when the <command>do_sigpending</command> kernel function is executed
- * @sigset_add: The address of the user-space signal set (<command>sigset_t</command>)
- * @sigset_size: The size of the user-space signal set.
- * 
- * Synopsis:
- * <programlisting>long do_sigpending(void __user *set, unsigned long sigsetsize)</programlisting>
+ * probe signal.pending - Examining pending signal
+ * @sigset_add: The address of the user-space signal set
+ * (<command>sigset_t</command>)
+ * @sigset_size: The size of the user-space signal set
  * 
  * This probe is used to examine a set of signals pending for delivery 
- * to a specific thread.
+ * to a specific thread. This normally occurs when the 
+ * <command>do_sigpending</command> kernel function is executed.
  */
-// long do_sigpending(void __user *set, unsigned long sigsetsize)
-
 probe signal.pending = kernel.function("do_sigpending")
 {
     sigset_add=$set
     sigset_size=$sigsetsize
 }
 
+/** 
+ * probe signal.pending.return - Examination of pending signal completed
+ * @retstr: Return value as a string
+ */
 probe signal.pending.return = kernel.function("do_sigpending").return
 {
     retstr = returnstr(1)
@@ -474,22 +509,17 @@ probe signal.pending.return = kernel.function("do_sigpending").return
 
 
 /**
- * probe signal.handle - Fires when the signal handler is invoked
+ * probe signal.handle - Signal handler being invoked
  * @sig: The signal number that invoked the signal handler
  * @sinfo: The address of the <command>siginfo</command> table
- * @sig_code: The <command>si_code</command> value of the <command>siginfo</command> signal
- * @ka_addr: The address of the <command>k_sigaction</command> table associated with the signal
+ * @sig_code: The <command>si_code</command> value of the
+ * <command>siginfo</command> signal
+ * @ka_addr: The address of the <command>k_sigaction</command> table
+ * associated with the signal
  * @oldset_addr: The address of the bitmask array of blocked signals 
  * @regs: The address of the kernel-mode stack area
  * @sig_mode: Indicates whether the signal was a user-mode or kernel-mode signal
- * 
- * Synopsis:
- * <programlisting>static int handle_signal(unsigned long sig, siginfo_t *info, struct k_sigaction *ka,
- * sigset_t *oldset, struct pt_regs * regs)</programlisting>
  */
-//static int handle_signal(unsigned long sig, siginfo_t *info, struct k_sigaction *ka,
-//					sigset_t *oldset, struct pt_regs * regs)
-
 probe signal.handle = kernel.function("handle_signal")
 {
     sig = $sig
@@ -508,6 +538,10 @@ probe signal.handle = kernel.function("handle_signal")
         sig_mode = "Kernel Mode Signal"
 }
 
+/**
+ * probe signal.handle.return - Signal handler invocation completed
+ * @retstr: Return value as a string
+ */
 probe signal.handle.return = kernel.function("handle_signal").return ?
 {
     retstr = returnstr(1)
@@ -515,11 +549,12 @@ probe signal.handle.return = kernel.function("handle_signal").return ?
 
 
 /**
- * probe signal.do_action - Initiates a trace when a thread is about to examine 
- * and change a signal action
+ * probe signal.do_action - Examining or changing a signal action
  * @sig: The signal to be examined/changed
- * @sigact_addr: The address of the new <command>sigaction</command> struct associated with the signal
- * @oldsigact_addr: The address of the old <command>sigaction</command> struct associated with the signal
+ * @sigact_addr: The address of the new <command>sigaction</command>
+ * struct associated with the signal
+ * @oldsigact_addr: The address of the old <command>sigaction</command>
+ * struct associated with the signal
  * @sa_handler: The new handler of the signal
  * @sa_mask: The new mask of the signal
  */
@@ -535,6 +570,10 @@ probe signal.do_action = kernel.function("do_sigaction")
     }
 }
 
+/**
+ * probe signal.do_action.return - Examining or changing a signal action completed
+ * @retstr: Return value as a string
+ */
 probe signal.do_action.return = kernel.function("do_sigaction").return
 {
     retstr = returnstr(1)
@@ -554,16 +593,17 @@ function __get_action_mask:long(act:long) %{ /* pure */
 
 
 /**
- * probe signal.procmask - Initiates a trace when a thread is about to examine and change blocked signals
+ * probe signal.procmask - Examining or changing blocked signals
  * @how: Indicates how to change the blocked signals; possible values are 
  * <command>SIG_BLOCK=0</command> (for blocking signals), 
  * <command>SIG_UNBLOCK=1</command> (for unblocking signals), and 
  * <command>SIG_SETMASK=2</command> for setting the signal mask.
- * @sigset_addr: The address of the signal set (<command>sigset_t</command>) to be implemented
- * @oldsigset_addr: The old address of the signal set (<command>sigset_t</command>)
- * @sigset: The actual value to be set for <command>sigset_t</command> <remark>(correct?)</remark>
- * Synopsis:
- * <programlisting>int sigprocmask(int how, sigset_t *set, sigset_t *oldset)</programlisting>
+ * @sigset_addr: The address of the signal set (<command>sigset_t</command>)
+ * to be implemented
+ * @oldsigset_addr: The old address of the signal set
+ * (<command>sigset_t</command>)
+ * @sigset: The actual value to be set for <command>sigset_t</command>
+ * <remark>(correct?)</remark>
  */
 probe signal.procmask = kernel.function("sigprocmask")
 {
@@ -591,16 +631,13 @@ probe signal.procmask.return = kernel.function("sigprocmask").return
 
 
 /**
- * probe signal.flush - Fires when all pending signals for a task are flushed
+ * probe signal.flush - Flusing all pending signals for a task
  * @task: The task handler of the process performing the flush
- * @sig_pid: The PID of the process associated with the task performing the flush
- * @pid_name: The name of the process associated with the task performing the flush 
- * 
- * Synopsis:
- * <programlisting>void flush_signals(struct task_struct *t)</programlisting>
+ * @sig_pid: The PID of the process associated with the task
+ * performing the flush
+ * @pid_name: The name of the process associated with the task
+ * performing the flush 
  */
-//void flush_signals(struct task_struct *t)
-
 probe signal.flush = kernel.function("flush_signals")
 {
     task = $t
diff --git a/tapset/socket.stp b/tapset/socket.stp
index 3271d4f7..93730f9f 100644
--- a/tapset/socket.stp
+++ b/tapset/socket.stp
@@ -5,7 +5,9 @@
 // redistribute it and/or modify it under the terms of the GNU General
 // Public License (GPL); either version 2, or (at your option) any
 // later version.
-
+// <tapsetdescription>
+// This family of probe points is used to probe socket activities.
+// </tapsetdescription>
 %{
 #include <net/sock.h>
 #include <asm/bitops.h>
diff --git a/tapset/tcp.stp b/tapset/tcp.stp
index 995d6abc..1375f115 100644
--- a/tapset/tcp.stp
+++ b/tapset/tcp.stp
@@ -7,7 +7,9 @@
 // redistribute it and/or modify it under the terms of the GNU General
 // Public License (GPL); either version 2, or (at your option) any
 // later version.
-
+// <tapsetdescription>
+// This family of probe points is used to probe events that occur in the TCP layer, 
+// </tapsetdescription>
 %{
 #include <linux/version.h>
 #include <net/sock.h>
diff --git a/tapset/timestamp.stp b/tapset/timestamp.stp
index ce8f7558..0b9d350a 100644
--- a/tapset/timestamp.stp
+++ b/tapset/timestamp.stp
@@ -6,7 +6,11 @@
 // redistribute it and/or modify it under the terms of the GNU General
 // Public License (GPL); either version 2, or (at your option) any
 // later version.
-
+// <tapsetdescription>
+// Each timestamp function returns a value to indicate when a function is executed. These 
+//returned values can then be used to indicate when an event occurred, provide an ordering for events, 
+//or compute the amount of time elapsed between two time stamps.
+// </tapsetdescription>
 /**
  * sfunction get_cycles - Processor cycle count.
  *
diff --git a/tapset/udp.stp b/tapset/udp.stp
index 707cf77d..f2b19a7f 100644
--- a/tapset/udp.stp
+++ b/tapset/udp.stp
@@ -5,7 +5,9 @@
 // redistribute it and/or modify it under the terms of the GNU General
 // Public License (GPL); either version 2, or (at your option) any
 // later version.
-
+// <tapsetdescription>
+// This family of probe points is used to probe events that occur in the UDP layer. 
+// </tapsetdescription>
 %{
 #include <linux/version.h>
 #include <net/sock.h>