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

9 files changed, 120 insertions, 130 deletions

diff --git a/tapset/context-symbols.stp b/tapset/context-symbols.stp
index 4a08ec60..a3aae408 100644
--- a/tapset/context-symbols.stp
+++ b/tapset/context-symbols.stp
@@ -18,12 +18,13 @@
 %}
 // weirdness with print_stack, argument appears in build as undescribed
 /**
- * sfunction print_stack - Print out stack from string
+ * sfunction print_stack - Print out stack from string.
  * @stk: String with list of hexidecimal addresses. (FIXME)
  *
  *  Perform a symbolic lookup of the addresses in the given  string,
- *  which  is  assumed  to  be  the  result of a prior call to 
+ *  which is assumed to be the result of a prior call to 
  *  <command>backtrace()</command>.
+ * 
  *  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.
@@ -40,9 +41,7 @@ function print_stack(stk:string) %{
 %}
 
 /**
- * sfunction probefunc - Function probed
- *
- * Return the probe point's function name, if known.
+ * sfunction probefunc - Return the probe point's function name, if known.
  */
 function probefunc:string () %{ /* pure */
 	char *ptr, *start;
@@ -76,9 +75,7 @@ function probefunc:string () %{ /* pure */
 %}
 
 /**
- * sfunction probemod - Module probed
- *
- *  Return the probe point's module name, if known.
+ * sfunction probemod - Return the probe point's module name, if known.
  */
 function probemod:string () %{ /* pure */
 	char *ptr, *start;
diff --git a/tapset/context-unwind.stp b/tapset/context-unwind.stp
index 5c1253b8..90d4e0f4 100644
--- a/tapset/context-unwind.stp
+++ b/tapset/context-unwind.stp
@@ -23,7 +23,7 @@
 /**
  * sfunction print_backtrace - Print stack back trace
  *
- *  Equivalent to <command>print_stack(backtrace())</command>,
+ *  Equivalent to <command>print_stack(backtrace())</command>, 
  *  except that deeper stack nesting may be supported.  Return nothing.
  */
 function print_backtrace () %{
@@ -37,8 +37,8 @@ function print_backtrace () %{
 /**
  * sfunction backtrace - Hex backtrace of current stack
  *
- *  Return a string of hex addresses that are a backtrace of the
- *  stack.  It may be truncated due to maximum string length.
+ *  Return a string of hex addresses that are a backtrace of the 
+ *  stack.  Output may be truncated as per maximum string length.
  */
 function backtrace:string () %{ /* pure */
 	if (CONTEXT->regs)
@@ -50,7 +50,7 @@ function backtrace:string () %{ /* pure */
 /**
  * sfunction caller - Return name and address of calling function
  *
- *  Return the address and name of the calling function.
+ *  Return the address and name of the calling function. 
  *  <emphasis>Works only for return probes at this time.</emphasis>
  */
 function caller:string() %{ /* pure */
@@ -64,7 +64,7 @@ function caller:string() %{ /* pure */
 /**
  * sfunction caller_addr -  Return caller address
  *
- *  Return the address of the calling function.
+ *  Return the address of the calling function. 
  *  <emphasis> Works only for return probes at this time.</emphasis>
  */
 function caller_addr:long () %{ /* pure */
diff --git a/tapset/context.stp b/tapset/context.stp
index f4b0207a..9f4be0e6 100644
--- a/tapset/context.stp
+++ b/tapset/context.stp
@@ -21,37 +21,28 @@ function print_regs () %{
 %}
 
 /**
- * sfunction execname - Execname of current processes
- *
- *  Return the name of the current process.
+ * sfunction execname - Returns the execname of a target process (or group of processes).
  */
 function execname:string () %{ /* pure */
 	strlcpy (THIS->__retvalue, current->comm, MAXSTRINGLEN);
 %}
 
 /**
- * sfunction pid - Process ID of current process
- *
- *
- *  Return the id of the current process.
+ * sfunction pid - Returns the ID of a target process.
  */
 function pid:long () %{ /* pure */
 	THIS->__retvalue = current->tgid;
 %}
 
 /**
- * sfunction tid - Thread ID of current process
- *
- *  Return the id of the current thread.
+ * sfunction tid - Returns the thread ID of a target process.
  */
 function tid:long () %{ /* pure */
 	THIS->__retvalue = current->pid;
 %}
 
 /**
- * sfunction ppid - Parent Process ID of current process
- *
- *  Return the id of the parent process.
+ * sfunction ppid - Returns the process ID of a target process's parent process.
  */
 function ppid:long () %{ /* pure */
 #if defined(STAPCONF_REAL_PARENT)
@@ -62,9 +53,7 @@ function ppid:long () %{ /* pure */
 %}
 
 /**
- * sfunction pexecname - Execname of the parent process.
- *
- *  Return the name of the parent process.
+ * sfunction pexecname - Returns the execname of a target process's parent process.
  */
 function pexecname:string () %{ /* pure */
 #if defined(STAPCONF_REAL_PARENT)
@@ -75,9 +64,7 @@ function pexecname:string () %{ /* pure */
 %}
 
 /**
- * sfunction gid - Group ID of current process
- *
- *  Return the gid of the current process.
+ * sfunction gid - Returns the group ID of a target process.
  */
 function gid:long () %{ /* pure */
 #ifdef STAPCONF_TASK_UID
@@ -88,9 +75,7 @@ function gid:long () %{ /* pure */
 %}
 
 /**
- * sfunction egid - Effective gid of the current process.
- *
- *  Return the effective gid of the current process.
+ * sfunction egid - Returns the effective gid of a target process.
  */
 function egid:long () %{ /* pure */
 #ifdef STAPCONF_TASK_UID
@@ -101,9 +86,7 @@ function egid:long () %{ /* pure */
 %}
 
 /**
- * sfunction uid -User ID of the current process.
- *
- *  Return the uid of the current process.
+ * sfunction uid - Returns the user ID of a target process.
  */
 function uid:long () %{ /* pure */
 #ifdef STAPCONF_TASK_UID
@@ -114,9 +97,7 @@ function uid:long () %{ /* pure */
 %}
 
 /**
- * sfunction euid - Effective User ID of the current process.
- *
- *  Return the effective uid of the current process.
+ * sfunction euid - Return the effective uid of a target process.
  */
 function euid:long () %{ /* pure */
 #ifdef STAPCONF_TASK_UID
@@ -132,26 +113,24 @@ function cpuid:long () %{ /* pure */
 %}
 
 /**
- * sfunction cpu - The current cpu number.
- * 
- *  Return the current cpu number.
+ * sfunction cpu - Returns the current cpu number.
  */
 function cpu:long () %{ /* pure */
 	THIS->__retvalue = smp_processor_id();
 %}
 
 /**
- * sfunction pp - Current probe point
- *
- *  Return the probe point associated with the currently running
- *  probe handler, including alias and wildcard expansion effects.
+ * sfunction pp - Return the probe point associated with the currently running probe handler,
+ * including alias and wildcard expansion effects
+ * Context:
+ * The current probe point. 
  */
 function pp:string () %{ /* pure */
 	strlcpy (THIS->__retvalue, CONTEXT->probe_point, MAXSTRINGLEN);
 %}
 
 /**
- * sfunction registers_valid - Register information valid
+ * sfunction registers_valid - Determines validity of <command>register()</command> and <command>u_register()</command> in current context.
  *
  *  Return 1 if register() and u_register() can be used
  *  in the current context, or 0 otherwise.
@@ -163,7 +142,7 @@ function registers_valid:long () %{ /* pure */
 %}
 
 /**
- * sfunction user_mode - User Mode
+ * sfunction user_mode - Determines if probe point occurs in user-mode.
  *
  * Return 1 if the probe point occurred in user-mode.
  */
@@ -180,7 +159,7 @@ function user_mode:long () %{ /* pure */ /* currently a user-mode address? */
 %}
 
 /**
- * sfunction is_return - Is return probe
+ * sfunction is_return - Determines if probe point is a return probe.
  *
  *  Return 1 if the probe point is a return probe.
  *  <emphasis>Deprecated.</emphasis>
@@ -193,9 +172,7 @@ function is_return:long () %{ /* pure */
 %}
 
 /**
- * sfunction target - Target pid
- *
- *  Return the pid of the target process.
+ * sfunction target - Return the process ID of the target process.
  */
 function target:long () %{ /* pure */
         THIS->__retvalue = _stp_target;
@@ -224,18 +201,16 @@ function stp_pid:long () %{ /* pure */
 %}
 
 /**
- * sfunction stack_size - Size of kernel stack
- *
- *  Return the size of the kernel stack.
+ * sfunction stack_size - Return the size of the kernel stack.
  */
 function stack_size:long () %{ /* pure */
         THIS->__retvalue = THREAD_SIZE;
 %}
 
 /**
- * sfunction stack_used - Current amount of kernel stack used
+ * sfunction stack_used - Returns the amount of kernel stack used.
  *
- *  Return how many bytes are currently used in the kernel stack.
+ * Determines how many bytes are currently used in the kernel stack.
  */
 function stack_used:long () %{ /* pure */
 	char a;
@@ -243,9 +218,9 @@ function stack_used:long () %{ /* pure */
 %}
 
 /**
- * sfunction stack_unused - Amount of kernel stack currently available
+ * sfunction stack_unused - Returns the amount of kernel stack currently available.
  *
- *  Return how many bytes are currently available in the kernel stack.
+ * Determines how many bytes are currently available in the kernel stack.
  */
 function stack_unused:long () %{ /* pure */
 	char a;
diff --git a/tapset/ioscheduler.stp b/tapset/ioscheduler.stp
index 875ccea9..a79ae752 100644
--- a/tapset/ioscheduler.stp
+++ b/tapset/ioscheduler.stp
@@ -60,7 +60,7 @@ probe ioscheduler.elv_next_request.return
 }
 
 /**
- * probe ioscheduler.elv_add_request -A request was added to the request queue
+ * 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
diff --git a/tapset/memory.stp b/tapset/memory.stp
index 9dbe3fba..83875aa4 100644
--- a/tapset/memory.stp
+++ b/tapset/memory.stp
@@ -56,7 +56,7 @@ function vm_fault_contains:long (value:long, test:long)
 /**
  * probe vm.pagefault - Records that a page fault occurred.
  * @address: The address of the faulting memory access; i.e. the address that caused the page fault.
- * @write_access: Indicates whether this was a write or read access; <command>1</command> indicates a write,
+ * @write_access: Indicates whether this was a write or read access; <command>1</command> indicates a write, 
  * while <command>0</command> indicates a read.
  *
  * Context: The process which triggered the fault
@@ -113,8 +113,8 @@ function _IS_ZERO_PAGE:long(from:long, vaddr:long) %{ /* pure */
  * Context:
  *  The context is the process attempting the write.
  *
- *  Fires when a process attempts to write to a shared page.
- *  If a copy is necessary, this will be followed by a
+ *  Fires when a process attempts to write to a shared page. 
+ *  If a copy is necessary, this will be followed by a 
  *  <command>vm.write_shared_copy</command>.
  */
 probe vm.write_shared = kernel.function("do_wp_page") {
@@ -122,7 +122,7 @@ probe vm.write_shared = kernel.function("do_wp_page") {
 }
 
 /**
- * probe vm.write_shared_copy- Page copy for shared page write.
+ * probe vm.write_shared_copy - Page copy for shared page write.
  * @address: The address of the shared write.
  * @zero: Boolean indicating whether it is a zero page
  *         (can do a clear instead of a copy).
diff --git a/tapset/scsi.stp b/tapset/scsi.stp
index 8ff3dcca..e1457739 100644
--- a/tapset/scsi.stp
+++ b/tapset/scsi.stp
@@ -46,9 +46,9 @@ probe scsi.ioentry
  * @lun: The lun number
  * @dev_id: The scsi device id
  * @device_state: The current state of the device.
- * @data_direction: The data_direction specifies whether this command is from/to
- *            the device. 0 (DMA_BIDIRECTIONAL), 1 (DMA_TO_DEVICE),
- *	      2 (DMA_FROM_DEVICE), 3 (DMA_NONE)
+ * @data_direction: The data_direction specifies whether this command is from/to the device.
+ *		0 (DMA_BIDIRECTIONAL), 1 (DMA_TO_DEVICE),
+ *		2 (DMA_FROM_DEVICE), 3 (DMA_NONE)
  * @request_buffer: The request buffer address
  * @req_bufflen: The request buffer length
  */
@@ -81,7 +81,7 @@ probe scsi.iodispatching
  * @dev_id: The scsi device id
  * @device_state: The current state of the device
  * @data_direction: The data_direction specifies whether this command is
- * 		    from/to the device.
+ * 		from/to the device.
  */
 probe scsi.iodone
 	= module("scsi_mod").function("scsi_done@drivers/scsi/scsi.c")?,
@@ -106,7 +106,7 @@ probe scsi.iodone
  * @dev_id: The scsi device id
  * @device_state: The current state of the device
  * @data_direction: The data_direction specifies whether this command is from/to
- *                  the device
+ * 		the device
  * @goodbytes: The bytes completed.
  */
 // mid-layer processes the completed IO
diff --git a/tapset/socket.stp b/tapset/socket.stp
index 93730f9f..0f01b8d4 100644
--- a/tapset/socket.stp
+++ b/tapset/socket.stp
@@ -67,8 +67,8 @@ probe socket.receive = socket.recvmsg.return,
 
 ### FUNCTION SPECIFIC SEND/RECEIVE PROBES ###
 
-/*
- * probe socket.sendmsg - Message being sent on socket
+/**
+ * probe socket.sendmsg - Message is currently being sent on a socket.
  * @name:     Name of this probe
  * @size:     Message size in bytes
  * @protocol: Protocol value
@@ -95,7 +95,7 @@ probe socket.sendmsg = kernel.function ("sock_sendmsg")
 }
 
 /**
- * probe socket.sendmsg.return - Return from Message being sent on socket
+ * probe socket.sendmsg.return - Return from <command>socket.sendmsg</command>.
  * @name:     Name of this probe
  * @size:     Size of message sent (in bytes) or error code if success = 0
  * @protocol: Protocol value
@@ -151,7 +151,7 @@ probe socket.recvmsg = kernel.function ("sock_recvmsg")
 	type = $sock->type
 }
 
-/*
+/**
  * probe socket.recvmsg.return - Return from Message being received on socket
  * @name:     Name of this probe
  * @size:     Size of message received (in bytes) or error code if success = 0
@@ -198,14 +198,14 @@ probe socket.recvmsg.return = kernel.function ("sock_recvmsg").return
  * Fires at the beginning of sending a message on a socket
  * via the sock_aio_write() function
  */
-/*
- * 2.6.9~2.6.15:
- *     static ssize_t sock_aio_write(struct kiocb *iocb, const char __user *ubuf, size_t size, loff_t pos);
- * 2.6.16~2.6.18:
- *     static ssize_t sock_aio_write(struct kiocb *iocb, const char __user *ubuf, size_t count, loff_t pos);
- * 2.6.19~2.6.26:
- *     static ssize_t sock_aio_write(struct kiocb *iocb, const struct iovec *iov, unsigned long nr_segs, loff_t pos);
- */
+//
+// 2.6.9~2.6.15:
+//     static ssize_t sock_aio_write(struct kiocb *iocb, const char __user *ubuf, size_t size, loff_t pos);
+// 2.6.16~2.6.18:
+//     static ssize_t sock_aio_write(struct kiocb *iocb, const char __user *ubuf, size_t count, loff_t pos);
+// 2.6.19~2.6.26:
+//     static ssize_t sock_aio_write(struct kiocb *iocb, const struct iovec *iov, unsigned long nr_segs, loff_t pos);
+
 probe socket.aio_write = kernel.function ("sock_aio_write")
 {
 	name = "socket.aio_write"
@@ -272,14 +272,14 @@ probe socket.aio_write.return = kernel.function ("sock_aio_write").return
  * Fires at the beginning of receiving a message on a socket
  * via the sock_aio_read() function
  */
-/*
- * 2.6.9~2.6.15:
- *     static ssize_t sock_aio_read(struct kiocb *iocb, char __user *ubuf, size_t size, loff_t pos);
- * 2.6.16~2.6.18:
- *     static ssize_t sock_aio_read(struct kiocb *iocb, char __user *ubuf, size_t count, loff_t pos);
- * 2.6.19~2.6.26:
- *     static ssize_t sock_aio_read(struct kiocb *iocb, const struct iovec *iov, unsigned long nr_segs, loff_t pos);
- */
+//
+// 2.6.9~2.6.15:
+//     static ssize_t sock_aio_read(struct kiocb *iocb, char __user *ubuf, size_t size, loff_t pos);
+// 2.6.16~2.6.18:
+//     static ssize_t sock_aio_read(struct kiocb *iocb, char __user *ubuf, size_t count, loff_t pos);
+// 2.6.19~2.6.26:
+//     static ssize_t sock_aio_read(struct kiocb *iocb, const struct iovec *iov, unsigned long nr_segs, loff_t pos);
+
 probe socket.aio_read = kernel.function ("sock_aio_read")
 {
 	name = "socket.aio_read"
@@ -543,18 +543,16 @@ probe socket.close.return = kernel.function ("sock_release").return
 
 ####### PROTOCOL HELPER FUNCTIONS ########
 
-/*
- * sock_prot_num2str
- * Given a protocol number, return a string representation.
+/**
+ * sfunction sock_prot_num2str - Given a protocol number, return a string representation.
  */
 function sock_prot_num2str:string (proto:long)
 {
 	return (proto in _prot_num2str ? _prot_num2str[proto] : "UNDEF")
 }
 
-/*
- * sock_prot_str2num
- * Given a protocol name (string), return the corresponding protocol number.
+/**
+ * sfunction sock_prot_str2num - Given a protocol name (string), return the corresponding protocol number.
  */
 function sock_prot_str2num:long (proto:string)
 {
@@ -563,18 +561,16 @@ function sock_prot_str2num:long (proto:string)
 
 ######### PROTOCOL FAMILY HELPER FUNCTIONS ###########
 
-/*
- * sock_fam_num2str
- * Given a protocol family number, return a string representation.
+/**
+ * sfunction sock_fam_num2str - Given a protocol family number, return a string representation.
  */
 function sock_fam_num2str:string (family:long)
 {
 	return (family in _fam_num2str ? _fam_num2str[family] : "UNDEF")
 }
 
-/*
- * sock_fam_str2num
- * Given a protocol family name (string), return the corresponding
+/**
+ * sfunction sock_fam_str2num - Given a protocol family name (string), return the corresponding
  * protocol family number.
  */
 function sock_fam_str2num:long (family:string)
@@ -584,18 +580,16 @@ function sock_fam_str2num:long (family:string)
 
 ######### SOCKET STATE HELPER FUNCTIONS ##########
 
-/*
- * sock_state_num2str
- * Given a socket state number, return a string representation.
+/**
+ * sfunction sock_state_num2str - Given a socket state number, return a string representation.
  */
 function sock_state_num2str:string (state:long)
 {
 	return (state in _state_num2str ? _state_num2str[state] : "UNDEF")
 }
 
-/*
- * sock_state_str2num
- * Given a socket state string, return the corresponding state number.
+/**
+ * sfunction sock_state_str2num - Given a socket state string, return the corresponding state number.
  */
 function sock_state_str2num:long (state:string)
 {
diff --git a/tapset/task.stp b/tapset/task.stp
index 07337156..f1a10b0a 100644
--- a/tapset/task.stp
+++ b/tapset/task.stp
@@ -63,6 +63,30 @@ function task_pid:long (task:long)
 }
 
 
+// Return the task of the given process id
+function pid2task:long (pid:long) %{ /* pure */
+    struct task_struct *t = NULL;
+    pid_t t_pid  = (pid_t)(long)THIS->pid;
+    rcu_read_lock();
+#if LINUX_VERSION_CODE >= KERNEL_VERSION(2,6,24)
+      t = find_task_by_vpid (t_pid);
+#else
+      t = find_task_by_pid (t_pid);
+#endif
+    rcu_read_unlock();
+    THIS->__retvalue = (long)t;
+    CATCH_DEREF_FAULT();
+%}
+
+// Return the name of the given process id
+function pid2execname:string (pid:long) { 
+    tsk = pid2task(pid)
+    if (tsk)
+	return task_execname(tsk)
+    return ""
+}
+
+
 // Return the thread id of the given task
 function task_tid:long (task:long)
 {
diff --git a/tapset/udp.stp b/tapset/udp.stp
index f2b19a7f..2255074a 100644
--- a/tapset/udp.stp
+++ b/tapset/udp.stp
@@ -17,12 +17,12 @@
 
 /**
   * probe udp.sendmsg - Fires whenever a process sends a UDP message  
-  * @name: Name of this probe
-  * @sock: Network socket 
-  * @size: Number of bytes to send  
+  * @name: The name of this probe
+  * @sock: Network socket used by the process 
+  * @size: Number of bytes sent by the process
   *
   * Context:
-  *   The process which sends a udp message 
+  *   The process which sent a UDP message 
   */
 probe udp.sendmsg = kernel.function("udp_sendmsg") {
 	name = "udp.sendmsg"
@@ -32,11 +32,11 @@ probe udp.sendmsg = kernel.function("udp_sendmsg") {
 
 /**
   * probe udp.sendmsg.return - Fires whenever an attempt to send a UDP message is completed
-  * @name: Name of this probe
-  * @size: Number of bytes sent 
+  * @name: The name of this probe
+  * @size: Number of bytes sent by the process
   *
   * Context:
-  *   The process which sends a udp message
+  *   The process which sent a UDP message
   */
 probe udp.sendmsg.return = kernel.function("udp_sendmsg").return {
 	name = "udp.sendmsg"
@@ -45,12 +45,12 @@ probe udp.sendmsg.return = kernel.function("udp_sendmsg").return {
 
 /**
   * probe udp.recvmsg - Fires whenever a UDP message is received
-  * @name: Name of this probe
-  * @sock: Network socket
-  * @size: Number of bytes received  
+  * @name: The name of this probe
+  * @sock: Network socket used by the process
+  * @size: Number of bytes received by the process
   *
   * Context:
-  *  The process which receives a udp message
+  *  The process which received a UDP message
   */
 probe udp.recvmsg = kernel.function("udp_recvmsg") {
 	name = "udp.recvmsg"
@@ -59,12 +59,12 @@ probe udp.recvmsg = kernel.function("udp_recvmsg") {
 }
 
 /**
-  * probe udp.recvmsg.return - An attempt to receive a UDP message received has been completed
-  * @name: Name of this probe
-  * @size: Number of bytes received
+  * probe udp.recvmsg.return - Fires whenever an attempt to receive a UDP message received is completed
+  * @name: The name of this probe
+  * @size: Number of bytes received by the process
   *
   * Context:
-  *  The process which receives a udp message
+  *  The process which received a UDP message
   */
 probe udp.recvmsg.return = kernel.function("udp_recvmsg").return {
 	name = "udp.recvmsg"
@@ -72,13 +72,13 @@ probe udp.recvmsg.return = kernel.function("udp_recvmsg").return {
 }
 
 /**
-  * probe udp.disconnect - A process requests for UPD to be UDP disconnected 
-  * @name: Name of this probe
-  * @sock: Network socket 
+  * probe udp.disconnect - Fires when a process requests for a UDP disconnection
+  * @name: The name of this probe
+  * @sock: Network socket used by the process
   * @flags: Flags (e.g. FIN, etc)  
   *
   * Context:
-  *  The process which disconnects UDP 
+  *  The process which requests a UDP disconnection 
   */
 probe udp.disconnect = kernel.function("udp_disconnect") {
 	name = "udp.disconnect"
@@ -88,11 +88,11 @@ probe udp.disconnect = kernel.function("udp_disconnect") {
 
 /**
   * probe udp.disconnect.return - UDP has been disconnected successfully
-  * @name: Name of this probe
+  * @name: The name of this probe
   * @ret: Error code (0: no error) 
   *
   * Context:
-  *  The process which disconnects udp 
+  *  The process which requested a UDP disconnection
   */
 probe udp.disconnect.return = kernel.function("udp_disconnect").return {
 	name = "udp.disconnect"