#error This file serves only as documentation. Do not compile it.
-/**
- * \defgroup assign_pc Assignment Pointcut Functions
- */
-
/** \mainpage The InterAspect Framework
+ *
+ * \section intro Introduction
+ * InterAspect provides a simple framework for writing GCC plug-ins
+ * that provide instrumentation. Instrumentation consists of
+ * <i>advice</i> function calls that can be inserted at various
+ * program point. For example, it is possible to insert an advice
+ * call at every call to <code>malloc</code>, 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 <code>aop_</code> prefix.
*
* \section pc Pointcuts
- * InterAspect defines four types of pointcuts.
+ * An InterAspect-based plug-in finds program points in the target
+ * program by construction a <i>pointcut</i>, which is a set of points
+ * in the program available for instrumentation. These program points
+ * are called <i>join points</i>.
+ *
+ * There are four types of pointcuts available in InterAspect, which
+ * can each be constructed using a match function. Match functions
+ * have the prefix <code>aop_match_</code>.
+ *
* - \ref entry_pc "Function entry" pointcuts.
* - \ref exit_pc "Function exit" pointcuts.
* - \ref call_pc "Function call" pointcuts.
* - \ref assign_pc "Assignment" pointcuts.
+ *
+ * After construction a pointcut, it is possible to refine the set
+ * using filter functions, which have the prefix
+ * <code>aop_filter_</code>. For example, it is possible to define a
+ * pointcut that only matches calls to <code>malloc</code> using
+ * aop_filter_call_pc_by_name().
+ *
+ * \section join_on Join operations
+ * Plug-ins iterate over the join points in a pointcut using a \ref
+ * join "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
+ * <code>aop_capture_</code> 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.
+ *
+ * \section setup Setting it up
+ * Creating and joining on pointcuts are operations that occur within
+ * a <i>pass</i>. 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 <code>aop_main</code>.
+ *
+ * \section memory 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.
+ */
+
+/**
+ * \struct aop_dynval
+ * \brief Representation of a runtime value.
+ *
+ * An aop_dynval serves as a placeholder during compile time for a
+ * value that will not be known until runtime. An aop_dynval gets
+ * returned by a capture function, such as aop_capture_return_value(),
+ * and can be passed to an advice function inserted with
+ * aop_insert_advice().
+ *
+ * Internally, every aop_dynval has its own type, which is determined
+ * by how it was captured. For example, an aop_dynval created with
+ * aop_capture_return_value() will have its type set based on how the
+ * corresponding pointcut was filtered using
+ * aop_filter_call_pc_by_return_type(). (It is an error to capture
+ * the return value of a function call when the corresponding pointcut
+ * was not filtered by type. You must use
+ * aop_capture_return_value_by_type() instead.)
+ *
+ * At runtime, the advice function itself simply gets the captured
+ * value; it will never see the original aop_dynval object.
+ *
+ * Use the #AOP_DYNVAL macro when passing an aop_dynval to
+ * aop_insert_advice().
+ *
+ * All aop_dynval objects are only valid while the aop_joinpoint used
+ * to create them remains valid. Because an aop_dynval represents a
+ * value captured from a join point, all capture functions that return
+ * an aop_dynval take an aop_joinpoint as a parameter. When the
+ * aop_joinpoint becomes invalid (when the current callback finishes),
+ * these aop_dynval objects also become invalid. See the
+ * aop_joinpoint documentation for more information.
+ */
+
+/**
+ * \struct aop_joinpoint
+ * \brief A single program point that is available for
+ * instrumentation.
+ *
+ * The only way to obtain a join point is by joining on an
+ * aop_pointcut using a \ref join "join function". Each join point
+ * will be passed to the specified callback function.
+ *
+ * A join point is only valid during the callback's execution. Once
+ * the callback finishes, the aop_joinpoint is deallocated. You
+ * should never store a pointer to an aop_joinpoint in any global data
+ * structure, in order to avoid any accesses to the join point after
+ * it becomes invalid.
*/
projects / interaspect.git / commitdiff