The InterAspect Framework

Introduction

InterAspect provides a simple framework for writing GCC plug-ins that provide instrumentation. Instrumentation consists of advice function calls that can be inserted at various program points. For example, it is possible to insert an advice call at every call to malloc, passing the allocated size and the address of the allocated region to the advice function.

Though plug-ins built with the InterAspect framework run in GCC, they depend only on InterAspect files. An InterAspect-based plug-in just needs to include the main InterAspect header file, aop.h, and link with the InterAspect static library.

All InterAspect functions begin with the aop_ prefix.

Pointcuts

An InterAspect-based plug-in finds program points in the target program by constructing a pointcut, which is a set of points in the program available for instrumentation. These program points are called join points.

There are four types of pointcuts available in InterAspect, which can each be constructed using a match function. Match functions have the prefix aop_match_.

After constructing a pointcut, it is possible to refine the set using filter functions, which have the prefix aop_filter_. For example, it is possible to define a pointcut that only matches calls to malloc using aop_filter_call_pc_by_name().

Join operations

Plug-ins iterate over the join points in a pointcut using a join operation. The plug-in provides a callback to the join which gets called once for each join point.

The callback can use capture functions (with an aop_capture_ prefix) to get information about the join point. Some capture functions return an aop_dynval, which represents a value that will not be known until the join point executes.

The callback can also insert an advice call using aop_insert_advice(). It is possible to pass arbitrary parameters to an advice function, including dynval values.

Setting it up

Creating and joining on pointcuts are operations that occur within a pass. In GCC, a pass is a function that executes once for each compiled function, transforming the compiled function in some way. InterAspect passes transform compiled functions by adding instrumentation.

A plug-in adds one or more passes by calling aop_register_pass() from its main function, which must be named aop_main.

See the Hello World sample plug-in for a simple example of setting up a pass.

Advice function type safety

When inserting a call to an advice function, InterAspect cannot directly check that the arguments passed to the advice match the actual advice function's prototype. To avoid type mismatches, it is possible to use aop_write_c_header() to generate a header file that specifies the prototypes that InterAspect expects for each advice function. You can include this header file in the file that implements your advice functions to ensure that the types match.

See the advice_header sample plug-in for an example of automatically generating an advice header.

Memory management

InterAspect functions return various data structures that are dynamically allocated, but you are not responsible for managing or freeing any of them. InterAspect uses GCC's internal garbage collector to free all of its data.

Beware, however, that once a data structure's lifetime is over, that structure may be deallocated while your plug-in still holds a pointer to it. Attempting to use one of these pointers will have undefined results. Make sure not to hold a reference to an object past its lifetime. The lifetime for each struct is listed in its documentation.

Noinstrument

InterAspect adds a noinstrument attribute that you can use to disable instrumentation for a specific function in the target program. Any pass that you register with aop_register_pass() will skip over functions marked noinstrument.

You can mark a function with this attribute using GCC's attribute syntax:

 __attribute__((noinstrument)) void foo() {

The noinstrument attribute is especially useful for ensuring that advice functions and the functions they call do not themselves get instrumented (which can cause unbounded recursion and other problems).

Tracecut Extension

New to InterAspect 1.1 is the InterAspect Tracecut extension. Tracecuts let you specify program monitors as regular expressions over program events. See the Tracecut Functions function documentation and the fclose_tracecut sample plug-in.

Generated on Tue Jul 31 21:46:42 2012 for InterAspect by doxygen 1.6.1