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. --- .../en-US/Tapset_Reference.xml | 2 + doc/SystemTap_Tapset_Reference/en-US/context.xml | 233 ++++++++++++++++++++ .../en-US/networking.xml | 100 +++++++++ tapset/context.stp | 239 ++++++++++++++++++++- tapset/networking.stp | 97 +++++++++ 5 files changed, 664 insertions(+), 7 deletions(-) create mode 100644 doc/SystemTap_Tapset_Reference/en-US/context.xml create mode 100644 doc/SystemTap_Tapset_Reference/en-US/networking.xml diff --git a/doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.xml b/doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.xml index 4603b238..f10159b8 100644 --- a/doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.xml +++ b/doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.xml @@ -7,6 +7,8 @@ + + diff --git a/doc/SystemTap_Tapset_Reference/en-US/context.xml b/doc/SystemTap_Tapset_Reference/en-US/context.xml new file mode 100644 index 00000000..df271d0f --- /dev/null +++ b/doc/SystemTap_Tapset_Reference/en-US/context.xml @@ -0,0 +1,233 @@ + + + + + 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. + + + + print_backtrace() + print_backtrace + + Equivalent to print_stack(backtrace()), + except that deeper stack nesting may be supported. Return nothing. + + + + 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. + + + + execname:string() + execname + + Return the name of the current process. + + + + pid:long () + pid + + Return the id of the current process. + + + + tid:long() + tid + + Return the id of the current thread. + + + + ppid:long() + ppid + + Return the id of the parent process. + + + + pexecname:string() + pexecname + + Return the name of the parent process. + + + + gid:long() + gid + + Return the gid of the current process. + + + + egid:long() + egid + + Return the effective gid of the current process. + + + + uid:long() + uid + + Return the uid of the current process. + + + + euid:long() + euid + + Return the effective uid of the current process. + + + + cpuid:long() + cpuid + + Return the current cpu number. + + + + cpu:long() + cpu + + Return the current cpu number. + + + + 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. + + + + pp:string() + pp + + Return the probe point associated with the currently running + probe handler, including alias and wildcard expansion effects. + + + + probefunc:string() + probefunc + + Return the probe point's function name, if known. + + + + probemod:string() + probemod + + Return the probe point's module name, if known. + + + + 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. + + + + user_mode:long() + user_mode + + Return 1 if the probe point occurred in user-mode. + + + + is_return:long() + is_return + + Return 1 if the probe point is a return probe. + Deprecated. + + + + target:long() + target + + Return the pid of the target process. + + + + module_name:string() + module_name + + FIXME: need description. + + + + stp_pid:long() + stp_pid + + FIXME: need description. + + + + stack_size:long() + stack_size + + Return the size of the kernel stack. + + + + stack_used:long () + stack_used + + Return how many bytes are currently used in the kernel stack. + + + + stack_unused:long() + stack_unused + + Return how many bytes are currently available in the kernel stack. + + + + caller_addr:long() + caller_addr + + Return the address 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. + + + diff --git a/doc/SystemTap_Tapset_Reference/en-US/networking.xml b/doc/SystemTap_Tapset_Reference/en-US/networking.xml new file mode 100644 index 00000000..ce93739b --- /dev/null +++ b/doc/SystemTap_Tapset_Reference/en-US/networking.xml @@ -0,0 +1,100 @@ + + + + + Networking Tapset + + This family of probe points is used to probe the activities of + network device. + + + netdev.receive + netdev.receive + Fires when data arrives on network device. + + + Arguments: + dev_name + + The name of the device. e.g: eth0, ath1 + + + + length + + The length of the receiving buffer + + + + protocol + The possible values of protocol could be: + Protocol Values + + + + + ValueProtocol + + + 0800IP + 8100802.1Q VLAN + 0001802.3 + 0002AX.25 + 0004802.2 + 8035RARP + 0005SNAP + 0805X.25 + 0806ARP + 8137IPX + 0009Localtalk + 86DDIPv6 + + +
+ + + + truesize + + The size of the received data. + + + + + + + netdev.transmit + netdev.transmit + Fires when the network device wants to transmit a buffer. + + + Arguments: + dev_name + + The name of the device. e.g: eth0, ath1 + + + + length + + The length of the transmit buffer + + + + protocol + + The protocol of this packet. + + + + truesize + + The size of the the data to be transmitted. + + + + + + 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); %} + +/// diff --git a/tapset/networking.stp b/tapset/networking.stp index f32953fd..9bd742da 100644 --- a/tapset/networking.stp +++ b/tapset/networking.stp @@ -6,10 +6,72 @@ // Public License (GPL); either version 2, or (at your option) any // later version. +/// +/// Networking Tapset +/// +/// This family of probe points is used to probe the activities of +/// network device. +/// + %{ #include %} +/// +/// netdev.receive +/// netdev.receive +/// Fires when data arrives on network device. +/// +/// +/// Arguments: +/// dev_name +/// +/// The name of the device. e.g: eth0, ath1 +/// +/// +/// +/// length +/// +/// The length of the receiving buffer +/// +/// +/// +/// protocol +/// The possible values of protocol could be: +/// Protocol Values +/// +/// +/// +/// +/// ValueProtocol +/// +/// +/// 0800IP +/// 8100802.1Q VLAN +/// 0001802.3 +/// 0002AX.25 +/// 0004802.2 +/// 8035RARP +/// 0005SNAP +/// 0805X.25 +/// 0806ARP +/// 8137IPX +/// 0009Localtalk +/// 86DDIPv6 +/// +/// +///
+/// +/// +/// +/// truesize +/// +/// The size of the received data. +/// +/// +/// +/// +/// /* Main device receive routine, be called when packet arrives on network device */ probe netdev.receive = kernel.function("netif_receive_skb") @@ -20,6 +82,39 @@ probe netdev.receive truesize = $skb->truesize } +/// +/// netdev.transmit +/// netdev.transmit +/// Fires when the network device wants to transmit a buffer. +/// +/// +/// Arguments: +/// dev_name +/// +/// The name of the device. e.g: eth0, ath1 +/// +/// +/// +/// length +/// +/// The length of the transmit buffer +/// +/// +/// +/// protocol +/// +/// The protocol of this packet. +/// +/// +/// +/// truesize +/// +/// The size of the the data to be transmitted. +/// +/// +/// +/// +/// /* Queue a buffer for transmission to a network device */ probe netdev.transmit = kernel.function("dev_queue_xmit") @@ -29,3 +124,5 @@ probe netdev.transmit protocol = $skb->protocol truesize = $skb->truesize } + +/// -- cgit