Merge commit 'origin/master' into pr7043

Conflicts:
	runtime/print.c
	runtime/transport/transport.c
	runtime/transport/transport_msgs.h

1 files changed, 679 insertions, 0 deletions

diff --git a/stapfuncs.3stap.in b/stapfuncs.3stap.in
new file mode 100644
index 00000000..b9326fde
--- /dev/null
+++ b/stapfuncs.3stap.in
@@ -0,0 +1,679 @@
+.\" -*- nroff -*-
+.TH STAPFUNCS 3stap @DATE@ "Red Hat"
+.SH NAME
+stapfuncs \- systemtap functions
+
+.SH DESCRIPTION
+The following sections enumerate the public functions provided by
+standard tapsets installed under @prefix@/share/systemtap/tapset.  Each
+function is described with a signature, and its behavior/restrictions.
+The signature line includes the name of the function, the type of
+its return value (if any), and the names and types of all parameters.
+The syntax is the same as printed with the 
+.IR stap " option " \-p2 .
+Examples:
+
+.TP
+example1:long (v:string, k:long)
+In function "example1", do something with the given string and integer.
+Return some integer.
+
+.TP
+example2:unknown ()
+In function "example2", do something.  There is no explicit return value
+and take no parameters.
+
+.SS PRINTING
+
+.TP
+log:unknown (msg:string)
+Writes the given string to the common trace buffer.  Append an implicit
+end-of-line. Deprecated.  Please use the faster print functions.
+
+.TP
+warn:unknown (msg:string)
+Write the given string to the warning stream.  Append an implicit end-of-line.
+.I staprun
+prepends the string "WARNING:". 
+
+.TP
+error:unknown (msg:string)
+An error has occurred.  Write the given string to the error stream.
+Append an implicit end-of-line.
+.I staprun
+prepends the string "ERROR:".
+Block any further execution of statements in this probe.  If the number
+of errors so far exceeds the MAXERRORS parameter, also trigger an 
+.IR exit() .
+
+.TP
+exit:unknown ()
+Enqueue a request to shut down the systemtap session.  This does
+.B not
+unwind the current probe handler, nor block new probe handlers.
+.I staprun
+will shortly respond to the request and initiate an orderly shutdown.
+
+.SS CONVERSIONS
+.PP
+These functions access kernel or user-space data.  They try to validate the
+supplied addresses, and can thus result in errors if the pointers are invalid,
+or if a user-space access would cause a fault.
+.TP
+kernel_string:string (addr:long)
+Copy a 0-terminated string from kernel space at given address.
+.TP
+kernel_string_n:string (addr:long, n:long)
+Similar with kernel_string, except that not more than n bytes are copied.
+Thus, if there are null bytes among the first n bytes, it is same as
+kernel_string(addr). If not, n bytes will be copied and a null byte will
+be padded to the end.
+.TP
+kernel_long:long (addr:long)
+Copy a long from kernel space at given address.
+.TP
+kernel_int:long (addr:long)
+Copy an int from kernel space at given address.
+.TP
+kernel_short:long (addr:long)
+Copy a short from kernel space at given address.
+.TP
+kernel_char:long (addr:long)
+Copy a char from kernel space at given address.
+.TP
+user_string:string (addr:long)
+Copy a string from user space at given address.  If the access would
+fault, return "<unknown>" and signal no errors.
+.TP
+user_string2:string (addr:long, err_msg:string)
+Copy a string from user space at given address.  If the access would
+fault, return instead the err_msg value.
+.TP
+user_string_warn:string (addr:long)
+Copy a string from user space at given address.  If the access would
+fault, signal a warning and return "<unknown>".
+.TP
+user_string_quoted:string (addr:long)
+Copy a string from user space at given address. Any ASCII characters
+that are not printable are replaced by the corresponding escape
+sequence in the returned string.
+.TP
+user_string_n:string (addr:long, n:long)
+Copy a string of n bytes from user space at given address. If the access
+would fault, return "<unknown>".
+.TP
+user_string_n2:string (addr:long, n:long, err_msg:string)
+Copy a string of n bytes from user space at given address. If the access
+would fault, return the err_msg value.
+.TP
+user_string_n_warn:string (addr:long, n:long)
+Copy a string of n bytes from user space at given address. If the access
+would fault, signal a warning and return "<unknown>".
+.TP
+user_string_n_quoted:string (addr:long, n:long)
+Copy a string of n bytes from user space at given address. Any ASCII
+characters that are not printable are replaced by the corresponding escape
+sequence in the returned string. If the access would fault, return "<unknown>".
+.TP
+user_short:long (addr:long)
+Copy a short from user space at given address. If the access would fault,
+return 0.
+.TP
+user_short_warn:long (addr:long)
+Copy a short from user space at given address. If the access would fault,
+signal a warning and return 0.
+.TP
+user_int:long (addr:long)
+Copy an int from user space at given address. If the access would fault,
+return 0.
+.TP
+user_int_warn:long (addr:long)
+Copy an int from user space at given address. If the access would fault,
+signal a warning and return 0.
+.TP
+user_long:long (addr:long)
+Copy a long from user space at given address. If the access would fault,
+return 0.
+.TP
+user_long_warn:long (addr:long)
+Copy a long from user space at given address. If the access would fault,
+signal a warning and return 0.
+.TP
+user_char:long (addr:long)
+Copy a char from user space at given address. If the access would fault,
+return 0.
+.TP
+user_char_warn:long (addr:long)
+Copy a char from user space at given address. If the access would fault,
+signal a warning and return 0.
+.SS STRING
+.TP
+strlen:long (str:string)
+Return the number of characters in str.
+.TP
+substr:string (str:string,start:long, stop:long)
+Return the substring of str starting from character start and ending at character stop.
+.TP
+stringat:string (str:string,pos:long)
+Return the character in given position of string.
+.TP
+isinstr:long (s1:string, s2:string)
+Return 1 if string s1 contains string s2, returns 0 otherwise.
+.TP
+strtol:long (str:string, base:long)
+Convert the string representation of a number to a long using the numbering system
+specified by base.  For example, strtol("1000", 16) returns 4096.  Returns 0 if the
+string cannot be converted.
+.TP
+tokenize:string (str:string, delim:string)
+Return the next token in the given str string, where the tokens are delimited
+by one of the characters in the delim string.  If the str string is not blank,
+it returns the first token.  If the str string is blank, it returns the next
+token in the string passed in the previous call to tokenize. If no delimiter
+is found, the entire remaining str string is returned.  Returns blank when 
+no more tokens are left.
+
+.SS TIMESTAMP
+.TP
+get_cycles:long ()
+Return the processor cycle counter value, or 0 if unavailable.
+.TP
+gettimeofday_ns:long ()
+Return the number of nanoseconds since the UNIX epoch.
+.TP
+gettimeofday_us:long ()
+Return the number of microseconds since the UNIX epoch.
+.TP
+gettimeofday_ms:long ()
+Return the number of milliseconds since the UNIX epoch.
+.TP
+gettimeofday_s:long ()
+Return the number of seconds since the UNIX epoch.
+
+.SS CONTEXT INFO
+.TP
+cpu:long ()
+Return the current cpu number.
+.TP
+execname:string ()
+Return the name of the current process.
+.TP
+pexecname:string()
+Return the name of the parent process.
+.TP
+tid:long ()
+Return the id of the current thread.
+.TP
+pid:long ()
+Return the id of the current process.
+.TP
+ppid:long ()
+Return the id of the parent process.
+.TP
+uid:long ()
+Return the uid of the current process.
+.TP
+euid:long ()
+Return the effective uid of the current process.
+.TP
+gid:long ()
+Return the gid of the current process.
+.TP
+egid:long ()
+Return the effective gid of the current process.
+.TP
+print_regs:unknown ()
+Print a register dump.
+.TP
+backtrace:string ()
+Return a string of hex addresses that are a backtrace of the stack.
+It may be truncated due to maximum string length.
+.TP
+print_stack:unknown (bt:string)
+Perform a symbolic lookup of the addresses in the given string,
+which is assumed to be the result of a prior call to
+.IR 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.
+.TP
+print_backtrace:unknown ()
+Equivalent to
+.IR print_stack(backtrace()) ,
+except that deeper stack nesting may be supported.  Return nothing.
+.TP
+pp:string ()
+Return the probe point associated with the currently running probe handler,
+including alias and wildcard expansion effects.
+.TP
+probefunc:string ()
+Return the probe point's function name, if known.
+.TP
+probemod:string ()
+Return the probe point's module name, if known.
+.TP
+target:long ()
+Return the pid of the target process.
+.TP
+user_mode:long ()
+Return 1 if the probe point occurred in user-mode.
+.TP
+is_return:long ()
+Return 1 if the probe point is a return probe.  Deprecated.
+
+.SS TARGET_SET
+.TP
+target_set_pid:long (tid:long)
+Return whether the given process-id is within the "target set", that is whether
+it is a descendent of the top-level target() process.
+.TP
+target_set_report:unknown ()
+Print a report about the target set, and their ancestry. 
+
+.SS ERRNO
+.TP
+errno_str:string (e:long)
+Return the symbolic string associated with the given error code, like
+"ENOENT" for the number 2, or "E#3333" for an out-of-range value like 3333.
+
+.SS TASK
+.PP
+These functions return data about a task.  They all require
+a task handle as input, such as the value return by task_current() or the variables
+prev_task and next_task in the scheduler.ctxswitch probe alias.
+
+.TP
+task_current:long()
+Return the task_struct of the current process.
+
+.TP
+task_parent:long(task:long)
+Return the parent task_struct of the given task.
+.TP
+task_state:long(task:long)
+Return the state of the given task, which can be one of the following:
+
+   TASK_RUNNING           0
+   TASK_INTERRUPTIBLE     1
+   TASK_UNINTERRUPTIBLE   2
+   TASK_STOPPED           4
+   TASK_TRACED            8
+   EXIT_ZOMBIE           16
+   EXIT_DEAD             32
+
+.TP
+task_execname:string(task:long)
+Return the name of the given task.
+
+.TP
+task_pid:long(task:long)
+Return the process id of the given task.
+
+.TP
+task_tid:long(task:long)
+Return the thread id of the given task.
+
+.TP
+task_gid:long(task:long)
+Return the group id of the given task.
+
+.TP
+task_egid:long(task:long)
+Return the effective group id of the given task.
+
+.TP
+task_uid:long(task:long)
+Return the user id of the given task.
+
+.TP
+task_euid:long(task:long)
+Return the effective user id of the given task.
+
+.TP
+task_prio:long(task:long)
+Return the priority of the given task.
+
+.TP
+task_nice:long(task:long)
+Return the nice value of the given task.
+
+.TP
+task_cpu:long(task:long)
+Return the scheduled cpu for the given task.
+
+.TP
+task_open_file_handles:long(task:long)
+Return the number of open file handles for the given task.
+
+.TP
+task_max_file_handles:long(task:long)
+Return the maximum number of file handles for the given task.
+
+.TP
+pid2task:long(pid:long)
+Return the task of the given process id.
+
+.TP
+pid2execname:string(pid:long)
+Return the name of the given process id.
+
+.SS CPU REGISTERS
+.TP
+registers_valid:long ()
+Return 1 if register() and u_register() can be used
+in the current context, or 0 otherwise.
+For example, registers_valid() returns 0 when called from a begin or end probe.
+.TP
+register:long (name:string)
+Return the value of the named CPU register,
+as it was saved when the current probe point was hit.
+If the register is 32 bits, it is sign-extended to 64 bits.
+
+For the i386 architecture, the following names are recognized.
+(name1/name2 indicates that name1 and name2 are alternative names
+for the same register.)
+eax/ax, ebp/bp, ebx/bx, ecx/cx, edi/di, edx/dx, eflags/flags,
+eip/ip, esi/si, esp/sp, orig_eax/orig_ax,
+xcs/cs, xds/ds, xes/es, xfs/fs, xss/ss.
+
+For the x86_64 architecture, the following names are recognized:
+64-bit registers:
+r8, r9, r10, r11, r12, r13, r14, r15,
+rax/ax, rbp/bp, rbx/bx, rcx/cx, rdi/di, rdx/dx,
+rip/ip, rsi/si, rsp/sp;
+32-bit registers:
+eax, ebp, ebx, ecx, edx, edi, edx, eip, esi, esp, flags/eflags, orig_eax;
+segment registers: xcs/cs, xss/ss.
+
+For powerpc, the following names are recognized:
+r0, r1, ... r31, nip, msr, orig_gpr3, ctr, link, xer, ccr, softe, trap,
+dar, dsisr, result.
+
+For s390x, the following names are recognized:
+r0, r1, ... r15, args, psw.mask, psw.addr, orig_gpr2, ilc, trap.
+
+.TP
+u_register:long (name:string)
+Same as register(name), except that
+if the register is 32 bits, it is zero-extended to 64 bits.
+
+.SS NUMBERED FUNCTION ARGUMENTS
+The functions in this section provide the values of a probed function's
+arguments.
+They can be called when you have hit
+a probe point at the entry to a function.
+Arguments are referred to by number, starting at 1.
+Ordinarily, you can access arguments by name as well,
+but you may find these functions useful if the code you are probing
+was built without debugging information.
+
+On 32-bit architectures
+\(em and when probing 32-bit applications on 64-bit architectures \(em
+a 64-bit argument occupies two "arg slots."
+For example, if you are probing the following function
+
+   void f(int a, long long b, char *c)
+
+you would refer to a, b, and c as int_arg(1), longlong_arg(2), and
+pointer_arg(3), respectively, on a 64-bit architecture;
+but on a 32-bit architecture, you would refer to c as pointer_arg(4)
+(since b occupies slots 2 and 3).
+
+If the function you are probing doesn't follow the default rules
+for argument passing, you need to call one of the following functions
+(which see) in your handler before calling any *_arg function:
+asmlinkage(), fastcall(), or regparm().
+(This isn't necessary when referring to arguments only by name.)
+.TP
+int_arg:long (n:long)
+Return the value of argument n as a signed int
+(i.e., a 32-bit integer sign-extended to 64 bits).
+.TP
+uint_arg:long (n:long)
+Return the value of argument n as an unsigned int
+(i.e., a 32-bit integer zero-extended to 64 bits).
+.TP
+long_arg:long (n:long)
+Return the value of argument n as a signed long.
+On architectures where a long is 32 bits, the value is sign-extended to 64 bits.
+.TP
+ulong_arg:long (n:long)
+Return the value of argument n as an unsigned long.
+On architectures where a long is 32 bits, the value is zero-extended to 64 bits.
+.TP
+longlong_arg:long (n:long)
+Return the value of argument n as a 64-bit value.
+.TP
+ulonglong_arg:long (n:long)
+Same as longlong_arg(n).
+.TP
+pointer_arg:long (n:long)
+Same as ulong_arg(n).
+Use with any type of pointer.
+.TP
+s32_arg:long (n:long)
+Same as int_arg(n).
+.TP
+u32_arg:long (n:long)
+Same as uint_arg(n).
+.TP
+s64_arg:long (n:long)
+Same as longlong_arg(n).
+.TP
+u64_arg:long (n:long)
+Same as [u]longlong_arg(n).
+.TP
+asmlinkage:unknown ()
+The probed kernel function is declared asmlinkage in the source.
+.TP
+fastcall:unknown ()
+The probed kernel function is declared fastcall in the source.
+.TP
+regparm:unknown (n:long)
+The probed function was built with the gcc \-mregparm=n option.
+(The i386 kernel is built with \-mregparm=3, so systemtap considers
+regparm(3) the default for kernel functions on that architecture.)
+
+For some architectures, the *_arg functions may reject unusually high
+values of n.
+
+.SS QUEUE_STATS
+.PP
+The queue_stats tapset provides functions that, given notifications of
+elementary queuing events (wait, run, done), tracks averages such as
+queue length, service and wait times, utilization.  The following
+three functions should be called from appropriate probes, in sequence.
+.TP
+qs_wait:unknown (qname:string)
+Record that a new request was enqueued for the given queue name.
+.TP
+qs_run:unknown (qname:string)
+Record that a previously enqueued request was removed from the given
+wait queue and is now being serviced.
+.TP
+qs_done:unknown (qname:string)
+Record that a request originally from the given queue has completed
+being serviced.
+.\" XXX: qs_time
+.PP
+Functions with the prefix 
+.BR qsq_
+are for querying the statistics averaged since the first queue operation
+(or when
+.BR qsq_start
+was called). Since statistics are often fractional, a scale parameter
+is multiplies the result to a more useful scale.  For some fractions,
+a scale of 100 will usefully return percentage numbers.
+.TP
+qsq_start:unknown (qname:string)
+Reset the statistics counters for the given queue, and start tracking
+anew from this moment.
+.TP
+qsq_print:unknown (qname:string)
+Print a line containing a selection of the given queue's statistics.
+.TP
+qsq_utilization:long (qname:string, scale:long)
+Return the fraction of elapsed time when the resource was utilized.
+.TP
+qsq_blocked:long (qname:string, scale:long)
+Return the fraction of elapsed time when the wait queue was used.
+.TP
+qsq_wait_queue_length:long (qname:string, scale:long)
+Return the average length of the wait queue.
+.TP
+qsq_service_time:long (qname:string, scale:long)
+Return the average time required to service a request.
+.TP
+qsq_wait_time:long (qname:string, scale:long)
+Return the average time a request took from being enqueued to completed.
+.TP
+qsq_throughput:long (qname:string, scale:long)
+Return the average rate of requests per scale units of time.
+
+.SS INDENT
+.PP
+The indent tapset provides functions to generate indented lines for
+nested kinds of trace messages.  Each line contains a relative
+timestamp, and the process name / pid.
+.TP
+thread_indent:string (delta:long)
+Return a string with an appropriate indentation for this thread.
+Call it with a small positive or matching negative delta.
+If this is the outermost, initial level of indentation, reset the
+relative timestamp base to zero.
+.TP
+thread_timestamp:long ()
+Return an absolute timestamp value for use by the indentation function.
+The default function uses 
+.IR gettimeofday_us
+
+.SS SYSTEM
+.TP
+system (cmd:string)
+Runs a command on the system. The command will run in the background
+when the current probe completes.
+
+.SS NUMA
+.TP
+addr_to_node:long (addr:long)
+Return which node the given address belongs to in a NUMA system.
+
+.SS CTIME
+.TP
+ctime:string (seconds:long)
+Return a simple textual rendering (e.g., "Wed\ Jun\ 30\ 21:49:008\ 1993")
+of the given number of seconds since the epoch, as perhaps returned by
+.IR gettimeofday_s() .
+
+.SS PERFMON
+.TP
+read_counter:long (handle:long)
+Returns the value for the processor's performance counter for the associated
+handle. The body of the a perfmon probe should set record
+the handle being used for that event.
+
+.SS SOCKETS
+These functions convert arguments in the socket tapset back and
+forth between their numeric and string representations.
+See 
+.IR stapprobes.socket (3stap)
+for details.
+
+.TP
+sock_prot_num2str:string (proto:long)
+Returns the string representation of the given protocol value.
+.TP
+sock_prot_str2num:long (proto:string)
+Returns the numeric value associated with the given protocol string.
+.TP
+sock_fam_num2str:string (family:long)
+Returns the string representation of the given protocol family value.
+.TP
+sock_fam_str2num:long (family:string)
+Returns the numeric value associated with the given protocol family string.
+.TP
+sock_state_num2str:string (state:long)
+Returns the string representation of the given socket state value.
+.TP
+sock_state_str2num:long (state:string)
+Returns the numeric value associated with the given socket state string.
+.TP
+sock_type_num2str:string (type:long)
+Returns the string representation of the given socket type value.
+.TP
+sock_type_str2num:long (type:string)
+Returns the numeric value associated with the given socket type string.
+.TP
+sock_flags_num2str:string (flags:long)
+Returns the string representation of the given socket flags value.
+.TP
+msg_flags_num2str:string (flags:long)
+Returns the string representation of the given message flags bit map.
+
+.SS INET
+These functions convert between network (big-endian) and host byte order, like their
+namesake C functions.
+.TP
+ntohll:long (x:long)
+Convert from network to host byte order, 64-bit.
+.TP
+ntohl:long (x:long)
+Convert from network to host byte order, 32-bit.
+.TP
+ntohs:long (x:long)
+Convert from network to host byte order, 16-bit.
+.TP
+htonll:long (x:long)
+Convert from host to network byte order, 64-bit.
+.TP
+htonl:long (x:long)
+Convert from host to network byte order, 32-bit.
+.TP
+htons:long (x:long)
+Convert from host to network byte order, 16-bit.
+
+.SS SIGNAL
+.TP
+get_sa_flags:long (act:long)
+Returns the numeric value of sa_flags.
+.TP
+get_sa_handler:long (act:long)
+Returns the numeric value of sa_handler.
+.TP
+sigset_mask_str:string (mask:long)
+Returns the string representation of the sigset sa_mask.
+.TP
+is_sig_blocked:long (task:long, sig:long)
+Returns 1 if the signal is currently blocked, or 0 if it is not.
+.TP
+sa_flags_str:string (sa_flags:long)
+Returns the string representation of sa_flags.
+.TP
+sa_handler_str(handler)
+Returns the string representation of sa_handler. If it is not SIG_DFL, SIG_IGN
+or SIG_ERR, it will return the address of the handler.
+.TP
+signal_str(num)
+Returns the string representation of the given signal number.
+
+.SS DEVICE
+.TP
+MAJOR:long(dev:long)
+Extracts the major device number from a kernel device number (kdev_t).
+.TP
+MINOR:long(dev:long)
+Extracts the minor device number from a kernel device number (kdev_t).
+.TP
+MKDEV:long(major:long, minor:long)
+Creates a value that can be compared to a kernel device number (kdev_t).
+.TP
+usrdev2kerndev:long(dev:long)
+Converts a user-space device number into the format used in the kernel.
+
+.SH FILES
+.nh
+.IR @prefix@/share/systemtap/tapset
+.hy
+
+.SH SEE ALSO
+.IR stap (1)