Red Hat Training

A Red Hat training course is available for Red Hat Enterprise Linux

4.2. Built-in probe point types (DWARF probes)

This family of probe points uses symbolic debugging information for the target kernel or module, as may be found in executables that have not been stripped, or in the separate debuginfo packages. They allow logical placement of probes into the execution path of the target by specifying a set of points in the source or object code. When a matching statement executes on any processor, the probe handler is run in that context.
Points in a kernel are identified by module, source file, line number, function name or some combination of these.
Here is a list of probe point specifications currently supported: 
kernel.function(PATTERN)
kernel.function(PATTERN).call
kernel.function(PATTERN).return
kernel.function(PATTERN).return.maxactive(VALUE)
kernel.function(PATTERN).inline
kernel.function(PATTERN).label(LPATTERN)
module(MPATTERN).function(PATTERN)
module(MPATTERN).function(PATTERN).call
module(MPATTERN).function(PATTERN).return.maxactive(VALUE)
module(MPATTERN).function(PATTERN).inline
kernel.statement(PATTERN)
kernel.statement(ADDRESS).absolute
module(MPATTERN).statement(PATTERN)
The .function variant places a probe near the beginning of the named function, so that parameters are available as context variables.
The .return variant places a probe at the moment of return from the named function, so the return value is available as the $return context variable. The entry parameters are also available, though the function may have changed their values. Return probes may be further qualified with .maxactive, which specifies how many instances of the specified function can be probed simultaneously. You can leave off .maxactive in most cases, as the default should be sufficient. However, if you notice an excessive number of skipped probes, try setting .maxactive to incrementally higher values to see if the number of skipped probes decreases.
The .inline modifier for .function filters the results to include only instances of inlined functions. The .call modifier selects the opposite subset. Inline functions do not have an identifiable return point, so .return is not supported on .inline probes.
The .statement variant places a probe at the exact spot, exposing those local variables that are visible there.
In the above probe descriptions, MPATTERN stands for a string literal that identifies the loaded kernel module of interest and LPATTERN stands for a source program label. Both MPATTERN and LPATTERN may include asterisk (*), square brackets "[]", and question mark (?) wildcards.
PATTERN stands for a string literal that identifies a point in the program. It is composed of three parts:
  1. The first part is the name of a function, as would appear in the nm program's output. This part may use the asterisk and question mark wildcard operators to match multiple names.
  2. The second part is optional, and begins with the ampersand (@) character. It is followed by the path to the source file containing the function, which may include a wildcard pattern, such as mm/slab*. In most cases, the path should be relative to the top of the linux source directory, although an absolute path may be necessary for some kernels. If a relative pathname doesn't work, try absolute.
  3. The third part is optional if the file name part was given. It identifies the line number in the source file, preceded by a “:” or “+”. The line number is assumed to be an absolute line number if preceded by a “:”, or relative to the entry of the function if preceded by a “+”. All the lines in the function can be matched with “:*”. A range of lines x through y can be matched with “:x-y”.
Alternately, specify PATTERN as a numeric constant to indicate a relative module address or an absolute kernel address.
Some of the source-level variables, such as function parameters, locals, or globals visible in the compilation unit, are visible to probe handlers. Refer to these variables by prefixing their name with a dollar sign within the scripts. In addition, a special syntax allows limited traversal of structures, pointers, and arrays.
$var refers to an in-scope variable var. If it is a type similar to an integer, it will be cast to a 64-bit integer for script use. Pointers similar to a string (char *) are copied to SystemTap string values by the kernel_string() or user_string() functions.
$var->field traverses a structure's field. The indirection operator may be repeated to follow additional levels of pointers.
$var[N] indexes into an array. The index is given with a literal number.
$$vars expands to a character string that is equivalent to sprintf("parm1=%x ... parmN=%x var1=%x ... varN=%x", $parm1, ..., $parmN, $var1, ..., $varN)
$$locals expands to a character string that is equivalent to sprintf("var1=%x ... varN=%x", $var1, ..., $varN)
$$parms expands to a character string that is equivalent to sprintf("parm1=%x ... parmN=%x", $parm1, ..., $parmN)

4.2.1. kernel.function, module().function

The .function variant places a probe near the beginning of the named function, so that parameters are available as context variables.
General syntax: 
kernel.function("func[@file]"
module("modname").function("func[@file]"
Examples: 
# Refers to all kernel functions with "init" or "exit"
# in the name:
kernel.function("*init*"), kernel.function("*exit*")

# Refers to any functions within the "kernel/sched.c"
# file that span line 240:
kernel.function("*@kernel/sched.c:240")

# Refers to all functions in the ext3 module:
module("ext3").function("*")

4.2.2. kernel.statement, module().statement

The .statement variant places a probe at the exact spot, exposing those local variables that are visible there.
General syntax: 
kernel.statement("func@file:linenumber")
module("modname").statement("func@file:linenumber")
Example: 
# Refers to the statement at line 2917 within the
# kernel/sched.c file:
kernel.statement("*@kernel/sched.c:2917")
# Refers to the statement at line bio_init+3 within the fs/bio.c file:
kernel.statement("bio_init@fs/bio.c+3")