diff options
| -rw-r--r-- | stapprobes.5.in | 59 |
1 files changed, 47 insertions, 12 deletions
diff --git a/stapprobes.5.in b/stapprobes.5.in index ba642a06..ab1f0197 100644 --- a/stapprobes.5.in +++ b/stapprobes.5.in @@ -36,6 +36,18 @@ end kernel.syscall.* .ESAMPLE +Probes may be broadly classified into "synchronous" and +"asynchronous". A "synchronous" event is deemed to occur when any +processor executes an instruction matched by the specification. This +gives these probes a reference point (instruction address) from which +more contextual data may be available. Other families of probe points +refer to "asynchronous" events such as timers/counters rolling over, +where there is no fixed reference point that is related. Each probe +point specification may match multiple locations (for example, using +wildcards or aliases), and all them are then probed. A probe +declaration may also contain several comma-separated specifications, +all of which are probed. + .SS BEGIN/END The probe points @@ -102,14 +114,7 @@ processor, the probe handler is run in that context. .PP Points in a kernel, which are identified by module, source file, line number, function name, C label name, or some -combination of these. This kind of "synchronous" event is deemed to -occur when any processor executes an instruction matched by the -specification. Other families of probe points refer to "asynchronous" -events such as timers/counters rolling over, where there is no fixed -execution point that is related. Each probe point specification may -match multiple physical locations, all of which are then probed. A -probe declaration may also contain several comma-separated -specifications, all of which are probed. +combination of these. .PP Here is a list of probe point families currently supported. The .B .function @@ -149,10 +154,11 @@ kernel.statement(PATTERN) module(MPATTERN).statement(PATTERN) .ESAMPLE In the above list, MPATTERN stands for a string literal that aims to -identify the loaded kernel module of interest. It may include "*" and -"?" wildcards. PATTERN stands for a string literal that aims to -identify a point in the program. It is made up of three parts. The -first part is the name of a function, as would appear in the +identify the loaded kernel module of interest. It may include "*", "[]", +and "?" wildcards. PATTERN stands for a string literal that +aims to identify a point in the program. It is made up of three +parts. The first part is the name of a function, as would appear in +the .I nm program's output. This part may use the "*" and "?" wildcarding operators to match multiple names. The second part is optional, and @@ -185,6 +191,32 @@ $var[N] indexes into an array. The index is given with a literal number. +.SS MARKERS + +This family of probe points hooks up to static probing markers +inserted into the kernel or modules. These markers are special macro +calls inserted by kernel developers to make probing faster and more +reliable than with DWARF-based probes. Further, DWARF debugging +information is +.I not +required to probe markers. + +Marker probe points begin with +.BR kernel " or " module("name") , +just like DWARF probes. This identifies the source of symbol table +used for finding markers. The next part names the marker itself: +.BR mark("name") . +The marker name string, which may contain the usual wildcard characters, +is matched against the names given to the marker macros when the kernel +or module was compiled. + +The handler associated with a marker-based probe may read the +optional parameters specified at the macro call site. These are +named +.BR $arg1 " through " $argNN , +where NN is the number of parameters supplied by the macro. Number +and string parameters are passed in a type-safe manner. + .SH EXAMPLES .PP Here are some example probe points, defining the associated events. @@ -204,6 +236,9 @@ kernel.function("*@kernel/sched.c:240") refers to any functions within the "kernel/sched.c" file that span line 240. .TP +kernel.mark("getuid") +refers to an STAP_MARK(getuid, ...) macro call in the kernel. +.TP module("usb*").function("*sync*").return refers to the moment of return from all functions with "sync" in the name in any of the USB drivers. |