From 0166f61e34a34ef1138e1de7a7068bf602741a0c Mon Sep 17 00:00:00 2001 From: William Cohen Date: Tue, 25 Nov 2008 11:03:28 -0500 Subject: Add context, timestamp, memory, and networking tapsets. --- tapset/ChangeLog | 7 + tapset/context.stp | 351 +++++++++++++++++++++----------------------------- tapset/memory.stp | 267 ++++++++------------------------------ tapset/networking.stp | 76 +++-------- tapset/timestamp.stp | 72 ++++------- 5 files changed, 242 insertions(+), 531 deletions(-) (limited to 'tapset') diff --git a/tapset/ChangeLog b/tapset/ChangeLog index b63b1acb..20b564ca 100644 --- a/tapset/ChangeLog +++ b/tapset/ChangeLog @@ -1,3 +1,10 @@ +2008-11-24 Will Cohen + + * context.stp: + * memory.stp: + * networking.stp: + * timestamp.stp: Change to use kernel-doc notation. + 2008-11-19 Jim Keniston * s390x/registers.stp: Fixed typo. diff --git a/tapset/context.stp b/tapset/context.stp index 3c87d1b8..7505c607 100644 --- a/tapset/context.stp +++ b/tapset/context.stp @@ -7,37 +7,22 @@ // 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. -/// These 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. -/// -/// +/** + * sfunction 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. -/// -/// +/** + * sfunction print_backtrace - Print stack back trace + * + * 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); @@ -46,14 +31,12 @@ 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. -/// -/// +/** + * 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. + */ function backtrace:string () %{ /* pure */ if (CONTEXT->regs) _stp_stack_snprint (THIS->__retvalue, MAXSTRINGLEN, CONTEXT->regs, 0, CONTEXT->pi, MAXTRACE); @@ -61,46 +44,39 @@ function backtrace:string () %{ /* pure */ strlcpy (THIS->__retvalue, "", MAXSTRINGLEN); %} -/// -/// execname:string() -/// execname -/// -/// Return the name of the current process. -/// -/// +/** + * sfunction execname - Execname of current processes + * + * 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. -/// -/// +/** + * sfunction pid - Process ID of current process + * + * + * 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. -/// -/// +/** + * sfunction tid - Thread ID of current process + * + * 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. -/// -/// +/** + * sfunction ppid - Parent Process ID of current process + * + * Return the id of the parent process. + */ function ppid:long () %{ /* pure */ #if defined(STAPCONF_REAL_PARENT) THIS->__retvalue = current->real_parent->tgid; @@ -109,13 +85,11 @@ function ppid:long () %{ /* pure */ #endif %} -/// -/// pexecname:string() -/// pexecname -/// -/// Return the name of the parent process. -/// -/// +/** + * sfunction pexecname - Execname of the parent process. + * + * Return the name of the parent process. + */ function pexecname:string () %{ /* pure */ #if defined(STAPCONF_REAL_PARENT) strlcpy (THIS->__retvalue, current->real_parent->comm, MAXSTRINGLEN); @@ -124,46 +98,38 @@ function pexecname:string () %{ /* pure */ #endif %} -/// -/// gid:long() -/// gid -/// -/// Return the gid of the current process. -/// -/// +/** + * sfunction gid - Group ID of current process + * + * 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. -/// -/// +/** + * sfunction egid - Effective gid of the current process. + * + * 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. -/// -/// +/** + * sfunction uid -User ID of the current process. + * + * 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. -/// -/// +/** + * sfunction euid - Effective User ID of the current process. + * + * Return the effective uid of the current process. + */ function euid:long () %{ /* pure */ THIS->__retvalue = current->euid; %} @@ -173,29 +139,26 @@ function cpuid:long () %{ /* pure */ THIS->__retvalue = smp_processor_id(); %} -/// -/// cpu:long() -/// cpu -/// -/// Return the current cpu number. -/// -/// +/** + * sfunction cpu - The current cpu number. + * + * Return the current cpu number. + */ 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. -/// -/// +/** + * 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 + * 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. + */ function print_stack(stk:string) %{ char *ptr = THIS->stk; char *tok = strsep(&ptr, " "); @@ -207,25 +170,21 @@ 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. -/// -/// +/** + * sfunction pp - Current probe point + * + * 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. -/// -/// +/** + * sfunction probefunc - Function probed + * + * Return the probe point's function name, if known. + */ function probefunc:string () %{ /* pure */ char *ptr, *start; @@ -257,13 +216,11 @@ function probefunc:string () %{ /* pure */ } %} -/// -/// probemod:string() -/// probemod -/// -/// Return the probe point's module name, if known. -/// -/// +/** + * sfunction probemod - Module probed + * + * Return the probe point's module name, if known. + */ function probemod:string () %{ /* pure */ char *ptr, *start; @@ -282,27 +239,23 @@ 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. -/// -/// +/** + * sfunction registers_valid - Register information 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. -/// -/// +/** + * sfunction user_mode - 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__) @@ -315,14 +268,12 @@ 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. -/// -/// +/** + * sfunction is_return - Is return probe + * + * Return 1 if the probe point is a return probe. + * Deprecated. + */ function is_return:long () %{ /* pure */ if (CONTEXT->pi) THIS->__retvalue = 1; @@ -330,13 +281,11 @@ function is_return:long () %{ /* pure */ THIS->__retvalue = 0; %} -/// -/// target:long() -/// target -/// -/// Return the pid of the target process. -/// -/// +/** + * sfunction target - Target pid + * + * Return the pid of the target process. + */ function target:long () %{ /* pure */ THIS->__retvalue = _stp_target; %} @@ -363,50 +312,41 @@ function stp_pid:long () %{ /* pure */ THIS->__retvalue = _stp_pid; %} -/// -/// stack_size:long() -/// stack_size -/// -/// Return the size of the kernel stack. -/// -/// +/** + * sfunction stack_size - Size of kernel stack + * + * Return the size of the kernel stack. + */ function stack_size:long () %{ /* pure */ THIS->__retvalue = THREAD_SIZE; %} -/// -/// stack_used:long () -/// stack_used -/// -/// Return how many bytes are currently used in the kernel stack. -/// -/// +/** + * sfunction stack_used - Current amount of kernel 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)); %} -/// -/// stack_unused:long() -/// stack_unused -/// -/// Return how many bytes are currently available in the kernel stack. -/// -/// +/** + * sfunction stack_unused - Amount of kernel stack currently available + * + * 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); %} -/// -/// caller_addr:long() -/// caller_addr -/// -/// Return the address of the calling function. -/// Works only for return probes at this time. -/// -/// -/// +/** + * sfunction caller_addr - Return caller address + * + * 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); @@ -414,14 +354,12 @@ function caller_addr:long () %{ /* pure */ THIS->__retvalue = 0; %} -/// -/// caller:string() -/// caller -/// -/// Return the address and name of the calling function. -/// Works only for return probes at this time. -/// -/// +/** + * sfunction caller - Return name and address of calling function + * + * 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, @@ -430,4 +368,3 @@ function caller:string() %{ /* pure */ strlcpy(THIS->__retvalue,"unknown",MAXSTRINGLEN); %} -/// diff --git a/tapset/memory.stp b/tapset/memory.stp index 03568ad0..9370073b 100644 --- a/tapset/memory.stp +++ b/tapset/memory.stp @@ -7,34 +7,14 @@ // Public License (GPL); either version 2, or (at your option) any // later version. -/// -/// Memory Tapset -/// -/// This family of probe points is used to probe page fault events. -/// It contains the following probe points: -/// - -/// -/// vm.pagefault -/// vm.pagefault -/// -/// Records that a page fault occurred. -/// The context is the process which triggered the fault. -/// -/// -/// Arguments: -/// address -/// -/// The address of the faulting memory access. -/// -/// -/// write_access -/// -/// Indicates whether this was a write. -/// -/// -/// -/// +/** + * probe vm.pagefault - Records that a page fault occurred. + * @address: The address of the faulting memory access. + * @write_access: Indicates whether this was a write. + * + * Context: The process which triggered the fault + * + */ probe vm.pagefault = kernel.function("__handle_mm_fault@mm/memory.c") ?, kernel.function("handle_mm_fault@mm/memory.c") ? { @@ -42,61 +22,22 @@ probe vm.pagefault = kernel.function("__handle_mm_fault@mm/memory.c") ?, address = $address } -/// -/// vm.pagefault.return -/// vm.pagefault.return -/// -/// Records type of fault that occurred. -/// The context is the process which triggered the fault. -/// -/// -/// -/// Arguments: -/// fault_type -/// The possible values of fault_type are: -/// Fault values -/// -/// -/// -/// -/// -/// DefineValueReason -/// -/// -/// -/// VM_FAULT_OOM -/// 0 -/// out of memory -/// -/// -/// VM_FAULT_SIGBUS -/// 1 -/// if not oom, minor, or major fault, this val -/// -/// -/// VM_FAULT_MINOR -/// 2 -/// no blocking operation to handle fault -/// -/// -/// VM_FAULT_MAJOR -/// 3 -/// required blocking operation to handle fault -/// -/// -/// -///
-/// -/// -/// -/// +/** + * probe vm.pagefault.return - Records type of fault that occurred. + * @fault_type: 0 (VM_FAULT_OOM), 1 (VM_FAULT_SIGBUS), + * 2 (VM_FAULT_MINOR), and 3 (VM_FAULT_MAJOR) + */ probe vm.pagefault.return = kernel.function("__handle_mm_fault@mm/memory.c").return ?, kernel.function("handle_mm_fault@mm/memory.c").return ? { fault_type = $return } -/* Return which node the given address belongs to in a NUMA system */ +/** + * sfunction addr_to_node - Returns which NUMA node has the given address. + * @addr: The address of the faulting memory access. + * + */ function addr_to_node:long(addr:long) %{ /* pure */ int nid; int pfn = __pa(THIS->addr) >> PAGE_SHIFT; @@ -116,64 +57,32 @@ function _IS_ZERO_PAGE:long(from:long, vaddr:long) %{ /* pure */ %} -/// -/// vm.write_shared -/// vm.write_shared -/// -/// Fires when a process attempts to write to a shared page. -/// If a copy is necessary, this will be followed by a -/// . -/// The context is the process attempting the write. -/// -/// -/// -/// Arguments: -/// address -/// The address of the shared write. -/// -/// -/// +/** + * probe vm.write_shared - Write to shared page. + * @address: The address of the shared write. + * + * 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 + * vm.write_shared_copy. + */ probe vm.write_shared = kernel.function("do_wp_page") { address = $address } - -/// -/// vm.write_shared_copy -/// vm.write_shared_copy -/// -/// Fires when a write to a shared page requires a page copy. -/// This is always preceded by a . -/// The context is the process attempting the write. -/// -/// -/// -/// Arguments: -/// address -/// -/// The address of the shared write. -/// -/// -/// zero -/// -/// Boolean indicating whether it is a zero page -/// (can do a clear instead of a copy). -/// -/// -/// -/// -/* probe vm.write_shared_copy - * - * Fires when a write to a shared page requires a page copy. This is - * always preceded by a vm.shared_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). * * Context: * The process attempting the write. * - * Arguments: - * address - the address of the shared write. - * zero - boolean indicating whether it is a zero page - * (can do a clear instead of a copy). + * Fires when a write to a shared page requires a page copy. This is + * always preceded by a vm.shared_write. */ probe vm.write_shared_copy = kernel.function("copy_cow_page")? { address = $address @@ -181,34 +90,13 @@ probe vm.write_shared_copy = kernel.function("copy_cow_page")? { } -/// -/// vm.mmap -/// vm.mmap -/// -/// Fires when an mmap is requested. -/// The context is the process calling mmap. -/// -/// -/// -/// Arguments: -/// address -/// The requested address. -/// -/// length -/// The length of the memory segment. -/// -/// -/// -/* probe vm.mmap - * - * Fires when an mmap is requested. +/** + * probe vm.mmap - Fires when an mmap is requested. + * @address: the requested address + * @length: the length of the memory segment * * Context: * The process calling mmap. - * - * Arguments: - * address - the requested address - * length - the length of the memory segment */ probe vm.mmap = kernel.function("do_mmap"), kernel.function("do_mmap2")? { address = $addr @@ -216,93 +104,40 @@ probe vm.mmap = kernel.function("do_mmap"), kernel.function("do_mmap2")? { } -/// -/// vm.munmap -/// vm.munmap -/// Fires when an munmap is requested. -/// -/// -/// Arguments: -/// address -/// The requested address. -/// -/// length -/// The length of the memory segment. -/// -/// -/// -/* probe vm.munmap - * - * Fires when an munmap is requested. +/** + * probe vm.munmap - Fires when an munmap is requested. + * @address: the requested address + * @length: the length of the memory segment * * Context: * The process calling munmap. - * - * Arguments: - * address - the requested address - * length - the length of the memory segment */ probe vm.munmap = kernel.function("do_munmap") { address = $start length = $len } -/// -/// vm.brk -/// vm.brk -/// Fires when a brk is requested (resizing a heap). -/// -/// -/// Arguments: -/// address -/// The requested address. -/// -/// length -/// The length of the memory segment. -/// -/// -/// -/* probe vm.brk - * - * Fires when a brk is requested (resizing a heap). +/** + * probe vm.brk -Fires when a brk is requested (resizing a heap). + * @address - the requested address + * @length - the length of the memory segment * * Context: * The process calling brk. - * - * Arguments: - * address - the requested address - * length - the length of the memory segment */ probe vm.brk = kernel.function("do_brk") { address = $addr length = $len } -/// -/// vm.oom_kill -/// vm.oom_kill -/// Fires when a thread is targetted by the OOM killer. -/// -/// -/// Arguments: -/// task -/// The task being killed. -/// -/// -/// -/* probe vm.oom_kill - * - * Fires when a thread is targetted by the OOM killer. +/** + * probe vm.oom_kill - Fires when a thread is targetted by the OOM killer. + * @task: the task being killed * * Context: * The process that tried to consume more memory, and thus * triggered the OOM. (correct?) - * - * Arguments: - * task - the task being killed */ probe vm.oom_kill = kernel.function("__oom_kill_task") { task = $p } - -/// diff --git a/tapset/networking.stp b/tapset/networking.stp index decd62a7..d6e90259 100644 --- a/tapset/networking.stp +++ b/tapset/networking.stp @@ -6,36 +6,17 @@ // 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 -/// -/// -/// +/** + * probe netdev.receive - Data recieved from network device. + * @dev_name: The name of the device. e.g: eth0, ath1. + * @length: The length of the receiving buffer. + * @protocol: Protocol of recieved packet. + * + */ /// protocol /// The possible values of protocol could be: /// Protocol Values @@ -82,39 +63,14 @@ 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. -/// -/// -/// -/// -/// +/** + * probe netdev.transmit - Network device transmitting buffer + * @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") @@ -124,5 +80,3 @@ probe netdev.transmit protocol = $skb->protocol truesize = $skb->truesize } - -/// diff --git a/tapset/timestamp.stp b/tapset/timestamp.stp index 4c8592a8..29763cb9 100644 --- a/tapset/timestamp.stp +++ b/tapset/timestamp.stp @@ -7,79 +7,57 @@ // Public License (GPL); either version 2, or (at your option) any // later version. -/// -/// Timestamp Functions -/// -/// Each timestamp function returns a value to indicate when -/// the function is executed. -/// Thus, these returned values can be used to indicate -/// when an event occurs, provide an ordering for events, or compute -/// the amount of time elapsed between to time stamps. -/// - %{ #include %} -/// -/// get_cycles:long() -/// get_cycles -/// -/// Return the processor cycle counter value, or 0 if unavailable. -/// -/// +/** + * sfunction get_cycles - Processor cycle count. + * + * Return the processor cycle counter value, or 0 if unavailable. + */ function get_cycles:long () %{ /* pure */ cycles_t c = get_cycles(); THIS->__retvalue = (int64_t) c; %} -/// -/// gettimeofday_ns:long () -/// gettimeofday_ns -/// -/// Return the number of nanoseconds since the UNIX epoch. -/// -/// +/** + * sfunction gettimeofday_ns - Number of nanoseconds since UNIX epoch. + * + * Return the number of nanoseconds since the UNIX epoch. + */ function gettimeofday_ns:long () %{ /* pure */ /* NOTE: we can't use do_gettimeofday because we could be called from a * context where xtime_lock is already held. See bug #2525. */ THIS->__retvalue = _stp_gettimeofday_ns(); %} -/// -/// gettimeofday_us:long () -/// gettimeofday_us -/// -/// Return the number of microseconds since the UNIX epoch. -/// -/// +/** + * sfunction gettimeofday_us - Number of microseconds since UNIX epoch. + * + * Return the number of microseconds since the UNIX epoch. + */ function gettimeofday_us:long () { return gettimeofday_ns() / 1000; } -/// -/// gettimeofday_ms:long () -/// gettimeofday_ms -/// -/// Return the number of milliseconds since the UNIX epoch. -/// -/// +/** + * sfunction gettimeofday_ms - Number of milliseconds since UNIX epoch. + * + * Return the number of milliseconds since the UNIX epoch. + */ function gettimeofday_ms:long () { return gettimeofday_ns() / 1000000; } -/// -/// gettimeofday_s:long () -/// gettimeofday_s -/// -/// Return the number of seconds since the UNIX epoch. -/// -/// +/** + * sfunction gettimeofday_s - Number of seconds since UNIX epoch. + * + * Return the number of seconds since the UNIX epoch. + */ function gettimeofday_s:long () { return gettimeofday_ns() / 1000000000; } // likewise jiffies, monotonic_clock ... - -/// -- cgit