переводчик / драйвер скрипта systemtap (systemtap script translator/driver)
PROCESSING
The translator begins pass 1 by parsing the given input script,
and all scripts (files named *.stp) found in a tapset directory.
The directories listed with -I are processed in sequence, each
processed in "guru mode". For each directory, a number of
subdirectories are also searched. These subdirectories are
derived from the selected kernel version (the -R option), in
order to allow more kernel-version-specific scripts to override
less specific ones. For example, for a kernel version
2.6.12-23.FC3 the following patterns would be searched, in
sequence: 2.6.12-23.FC3/*.stp, 2.6.12/*.stp, 2.6/*.stp, and
finally *.stp. Stopping the translator after pass 1 causes it to
print the parse trees.
In pass 2, the translator analyzes the input script to resolve
symbols and types. References to variables, functions, and probe
aliases that are unresolved internally are satisfied by searching
through the parsed tapset script files. If any tapset script
file is selected because it defines an unresolved symbol, then
the entirety of that file is added to the translator's resolution
queue. This process iterates until all symbols are resolved and
a subset of tapset script files is selected.
Next, all probe point descriptions are validated against the wide
variety supported by the translator. Probe points that refer to
code locations ("synchronous probe points") require the
appropriate kernel debugging information to be installed. In the
associated probe handlers, target-side variables (whose names
begin with "$") are found and have their run-time locations
decoded.
Next, all probes and functions are analyzed for optimization
opportunities, in order to remove variables, expressions, and
functions that have no useful value and no side-effect.
Embedded-C functions are assumed to have side-effects unless they
include the magic string /* pure */. Since this optimization can
hide latent code errors such as type mismatches or invalid
$context variables, it sometimes may be useful to disable the
optimizations with the -u option.
Finally, all variable, function, parameter, array, and index
types are inferred from context (literals and operators).
Stopping the translator after pass 2 causes it to list all the
probes, functions, and variables, along with all inferred types.
Any inconsistent or unresolved types cause an error.
In pass 3, the translator writes C code that represents the
actions of all selected script files, and creates a Makefile to
build that into a kernel object. These files are placed into a
temporary directory. Stopping the translator at this point
causes it to print the contents of the C file.
In pass 4, the translator invokes the Linux kernel build system
to create the actual kernel object file. This involves running
make in the temporary directory, and requires a kernel module
build system (headers, config and Makefiles) to be installed in
the usual spot /lib/modules/VERSION/build. Stopping the
translator after pass 4 is the last chance before running the
kernel object. This may be useful if you want to archive the
file.
In pass 5, the translator invokes the systemtap auxiliary program
staprun program for the given kernel object. This program
arranges to load the module then communicates with it, copying
trace data from the kernel into temporary files, until the user
sends an interrupt signal. Any run-time error encountered by the
probe handlers, such as running out of memory, division by zero,
exceeding nesting or runtime limits, results in a soft error
indication. Soft errors in excess of MAXERRORS block of all
subsequent probes (except error-handling probes), and terminate
the session. Finally, staprun unloads the module, and cleans up.
ABNORMAL TERMINATION
One should avoid killing the stap process forcibly, for example
with SIGKILL, because the stapio process (a child process of the
stap process) and the loaded module may be left running on the
system. If this happens, send SIGTERM or SIGINT to any remaining
stapio processes, then use rmmod to unload the systemtap module.
