Re: architecture paper draft

[William Cohen <wcohen at redhat dot com>]

Here is a strawman for specifying locations for instrumentation.

-Will
Instrumentation Schemes

One of the needs of the instrumentation is to bridge the gap between
the basic mechanisms used to implement the instrumentation and
collecting specific types of data useful for diagnosing
problems. Having to specify hardcode addresses to place probes is
inconvient and error prone. Related types of instrumentation
techniques and operations are grouped together into instrumentation
schemes in SystemTAP.

Probe body has a probe specifier that describes which instrumentation
scheme to use. The probe specifier also contains additional
information to indicate how and where precisely the probe should be
placed.

The syntax of the probe specifier is fairly simple. There may be
additional restrictions due to the details of the instrumentation
scheme, but the following grammar describes the probe specifier
syntax:

probe specifier : "probe" p_spec_list ;

p_spec_list	: ( p_spec_elements )+ /* one or more */ ;

p_spec_element	: "." name opt_arguments ;

opt_arguments	:
		/* emtpy */
		| "(" string_list ")"
		;

string_list	: STRING ( "," STRING )*
		;

instrumentation_scheme : SYMBOL

/* FIXME work ability to separate declaration of probe specifier and use */

Some possible instrumentation schemes:


probe systemtap.(init | fini)

The "systemtap" instrumentation scheme is the most basic. There are
two possible specifier elements: "init" and "fini". probe specifier
"systemtap.init" specifies a probe point that executes before any
other probe in the instrumentation script fires. probe specifier
"systemtap.fini" instruments a point after the last firing of a probe
in the instrumentation script.

"init" and "fini" could be implemented as part of the module
initialization and finalization code.



probe kernel.function(name_list)(/* implicit entry */| .entry | .return)

For probe specifier above can be used to instrument the entry and
return of functions. If no ".entry" or ".return" are include it is
assumed that the function entry will be instrumented.  The function
probe will have the argument list of the function available to it.

The ".return" instruments the code just before the return to the
function that called the instrumented function. Local variables are
not available in this case because the frame for the function has
already been removed. The return value of the ".return" function will
be available.

/* FIXME details on how arguments and return value accessed */



Use of Kernel Data structures for Probe points

Due to the use of modules and devices drivers there are a number of
common data structures that are used to pass lists of methods to the
kernel. These data structures have well definited methods to implement
actions.  The instrumentation could walk these data structures and
extract the location of functions used to implement various
operations.

Below is a proposed probe specifier for the virtual file system. 

probe vfs.filesystem(name_list).(file|inode|sb).operation(name_list)(/* implicit entry */| .entry | .return

The underlying kprobe mechanism is still instrumenting functions much
like the "kernel" instrumentation scheme for functions. However, the
addresses of the function are obtained by walking the data structures.
The ".operation" indicates which operation or method should be
instrumented.

Like the function boundary instrumentation of the kernel
instrumentation scheme, arguments will be available on function entry
and return values on function return.

/* FIXME flesh out for other data structures in the kernel */

/* FIXME instrumentation schemes for user space */

probe syscall.operation(name_list)(/* implicit entry */| .entry | .return)

This may be built onto of the audit infrastructure.  Arguments may be
an issue here because they are going to be in user space. Return value
should be available on return.


Other variables available at probe locations