From 011987b8162b56b4932bae558364e82b8d76f7a1 Mon Sep 17 00:00:00 2001 From: William Cohen Date: Tue, 11 Nov 2008 17:28:00 -0500 Subject: Add documentation for context.stp and networking.stp. --- tapset/context.stp | 239 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 232 insertions(+), 7 deletions(-) (limited to 'tapset/context.stp') 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. +/// +/// Context Functions +/// +/// 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. +/// + +/// +/// print_regs() +/// print_regs +/// +/// Print a register dump. +/// +/// function print_regs () %{ if (CONTEXT->regs) { _stp_print_regs (CONTEXT->regs); } %} +/// +/// print_backtrace() +/// print_backtrace +/// +/// Equivalent to print_stack(backtrace()), +/// except that deeper stack nesting may be supported. Return nothing. +/// +/// function print_backtrace () %{ if (CONTEXT->regs) { _stp_stack_print(CONTEXT->regs, 1, CONTEXT->pi, MAXTRACE); @@ -21,6 +46,14 @@ function print_backtrace () %{ } %} +/// +/// backtrace:string() +/// backtrace +/// +/// Return a string of hex addresses that are a backtrace of the +/// stack. It may be truncated due to maximum string length. +/// +/// 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); %} +/// +/// execname:string() +/// execname +/// +/// Return the name of the current process. +/// +/// function execname:string () %{ /* pure */ strlcpy (THIS->__retvalue, current->comm, MAXSTRINGLEN); %} +/// +/// pid:long () +/// pid +/// +/// Return the id of the current process. +/// +/// function pid:long () %{ /* pure */ THIS->__retvalue = current->tgid; %} +/// +/// tid:long() +/// tid +/// +/// Return the id of the current thread. +/// +/// function tid:long () %{ /* pure */ THIS->__retvalue = current->pid; %} +/// +/// ppid:long() +/// ppid +/// +/// Return the id of the parent process. +/// +/// function ppid:long () %{ /* pure */ #if defined(STAPCONF_REAL_PARENT) THIS->__retvalue = current->real_parent->tgid; @@ -48,6 +109,13 @@ function ppid:long () %{ /* pure */ #endif %} +/// +/// pexecname:string() +/// pexecname +/// +/// Return the name of the parent process. +/// +/// 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 %} +/// +/// gid:long() +/// gid +/// +/// Return the gid of the current process. +/// +/// function gid:long () %{ /* pure */ THIS->__retvalue = current->gid; %} +/// +/// egid:long() +/// egid +/// +/// Return the effective gid of the current process. +/// +/// function egid:long () %{ /* pure */ THIS->__retvalue = current->egid; %} +/// +/// uid:long() +/// uid +/// +/// Return the uid of the current process. +/// +/// function uid:long () %{ /* pure */ THIS->__retvalue = current->uid; %} +/// +/// euid:long() +/// euid +/// +/// Return the effective uid of the current process. +/// +/// function euid:long () %{ /* pure */ THIS->__retvalue = current->euid; %} +/// +/// cpuid:long() +/// cpuid +/// +/// Return the current cpu number. +/// +/// +// FIXME is cpuid() or cpu() depricated? function cpuid:long () %{ /* pure */ THIS->__retvalue = smp_processor_id(); %} +/// +/// cpu:long() +/// cpu +/// +/// Return the current cpu number. +/// +/// +// FIXME is cpuid() or cpu() depricated? function cpu:long () %{ /* pure */ THIS->__retvalue = smp_processor_id(); %} +/// +/// print_stack(stk:string) +/// print_stack +/// +/// Perform a symbolic lookup of the addresses in the given string, +/// which is assumed to be the result of a prior call to +/// . +/// 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. +/// +/// function print_stack(stk:string) %{ char *ptr = THIS->stk; char *tok = strsep(&ptr, " "); @@ -91,10 +215,25 @@ function print_stack(stk:string) %{ } %} +/// +/// pp:string() +/// pp +/// +/// Return the probe point associated with the currently running +/// probe handler, including alias and wildcard expansion effects. +/// +/// function pp:string () %{ /* pure */ strlcpy (THIS->__retvalue, CONTEXT->probe_point, MAXSTRINGLEN); %} +/// +/// probefunc:string() +/// probefunc +/// +/// Return the probe point's function name, if known. +/// +/// function probefunc:string () %{ /* pure */ char *ptr, *start; @@ -126,6 +265,13 @@ function probefunc:string () %{ /* pure */ } %} +/// +/// probemod:string() +/// probemod +/// +/// Return the probe point's module name, if known. +/// +/// function probemod:string () %{ /* pure */ char *ptr, *start; @@ -144,10 +290,27 @@ function probemod:string () %{ /* pure */ } %} +/// +/// registers_valid:long() +/// registers_valid +/// +/// 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. +/// +/// function registers_valid:long () %{ /* pure */ THIS->__retvalue = (CONTEXT->regs != NULL); %} +/// +/// user_mode:long() +/// user_mode +/// +/// Return 1 if the probe point occurred in user-mode. +/// +/// 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? */ } %} +/// +/// is_return:long() +/// is_return +/// +/// Return 1 if the probe point is a return probe. +/// Deprecated. +/// +/// function is_return:long () %{ /* pure */ if (CONTEXT->pi) THIS->__retvalue = 1; @@ -167,37 +338,83 @@ function is_return:long () %{ /* pure */ THIS->__retvalue = 0; %} +/// +/// target:long() +/// target +/// +/// Return the pid of the target process. +/// +/// function target:long () %{ /* pure */ THIS->__retvalue = _stp_target; %} +/// +/// module_name:string() +/// module_name +/// +/// FIXME: need description. +/// +/// function module_name:string () %{ /* pure */ strlcpy(THIS->__retvalue, THIS_MODULE->name, MAXSTRINGLEN); %} +/// +/// stp_pid:long() +/// stp_pid +/// +/// FIXME: need description. +/// +/// function stp_pid:long () %{ /* pure */ THIS->__retvalue = _stp_pid; %} -# return the size of the stack +/// +/// stack_size:long() +/// stack_size +/// +/// Return the size of the kernel stack. +/// +/// function stack_size:long () %{ /* pure */ THIS->__retvalue = THREAD_SIZE; %} -# return how many bytes are currently used in the stack +/// +/// stack_used:long () +/// stack_used +/// +/// Return how many bytes are currently used in the kernel stack. +/// +/// 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 +/// +/// stack_unused:long() +/// stack_unused +/// +/// Return how many bytes are currently available in the kernel stack. +/// +/// 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. +/// +/// caller_addr:long() +/// caller_addr +/// +/// Return the address of the calling function. +/// Works only for return probes at this time. +/// +/// +/// 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. +/// +/// caller:string() +/// caller +/// +/// Return the address and name of the calling function. +/// Works only for return probes at this time. +/// +/// 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); %} + +/// -- cgit