From 6032e2ce2a5554d4a74956c397242743daf17698 Mon Sep 17 00:00:00 2001 From: "Frank Ch. Eigler" Date: Wed, 21 May 2014 09:20:28 -0400 Subject: [PATCH] stapprobes.3stap: highlight obsolete nature of kernel.mark probes --- man/stapprobes.3stap | 80 +++++++++++++++++++++++--------------------- 1 file changed, 41 insertions(+), 39 deletions(-) diff --git a/man/stapprobes.3stap b/man/stapprobes.3stap index 36f059282..c1cf061ea 100644 --- a/man/stapprobes.3stap +++ b/man/stapprobes.3stap @@ -1113,40 +1113,7 @@ probes defined in export the lowercase names of the verdict constants (e.g. NF_DROP becomes nf_drop) as local variables. -.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 . -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 -and/or module was compiled. Optionally, you can specify -.BR format("format") . -Specifying the marker format string allows differentiation between two -markers with the same name but different marker format strings. - -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. - -The marker format string associated with a marker is available in -.BR $format . -And also the marker name string is available in -.BR $name . - -.SS TRACEPOINTS +.SS KERNEL TRACEPOINTS This family of probe points hooks up to static probing tracepoints inserted into the kernel or modules. As with markers, these @@ -1156,10 +1123,8 @@ and DWARF debugging information is not required to probe tracepoints. Tracepoints have an extra advantage of more strongly-typed parameters than markers. -Tracepoint probes begin with -.BR kernel . -The next part names the tracepoint itself: -.BR trace("name") . +Tracepoint probes look like: +.BR kernel.trace("name") . The tracepoint name string, which may contain the usual wildcard characters, is matched against the names defined by the kernel developers in the tracepoint header files. @@ -1182,6 +1147,39 @@ and a string of name=value pairs for all parameters of the tracepoint is available in .BR $$vars " or " $$parms . +.SS KERNEL MARKERS (OBSOLETE) + +This family of probe points hooks up to an older style of static +probing markers inserted into older kernels or modules. These markers +are special STAP_MARK 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 . +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 +and/or module was compiled. Optionally, you can specify +.BR format("format") . +Specifying the marker format string allows differentiation between two +markers with the same name but different marker format strings. + +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. + +The marker format string associated with a marker is available in +.BR $format . +And also the marker name string is available in +.BR $name . + .SS HARDWARE BREAKPOINTS This family of probes is used to set hardware watchpoints for a given (global) kernel symbol. The probes take three components as inputs : @@ -1298,8 +1296,12 @@ a probe at the statement at that line number. Use the kernel.statement probe instead. .TP +kernel.trace("sched_*") +refers to all scheduler-related (really, prefixed) tracepoints in +the kernel. +.TP kernel.mark("getuid") -refers to an STAP_MARK(getuid, ...) macro call in the kernel. +refers to an obsolete 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 -- 2.43.5