#include <side/abi/type-value.h>
+/*
+ * SIDE ABI for description of event and type attributes.
+ * Event and type attributes are an optional array of { key, value }
+ * pairs which can be associated with either an event or a type.
+ *
+ * The extensibility scheme for the SIDE ABI for description of event
+ * and type attributes is as follows:
+ *
+ * * Existing attribute types are never changed nor extended. Attribute
+ * types can be added to the ABI by reserving a label within
+ * enum side_attr_type.
+ * * Each union part of the ABI has an explicit size defined by a
+ * side_padding() member. Each structure and union have a static
+ * assert validating its size.
+ * * Changing the semantic of the existing attribute type fields is a
+ * breaking ABI change.
+ *
+ * Handling of unknown attribute types by the tracers:
+ *
+ * * A tracer may choose to support only a subset of the types supported
+ * by libside. When encountering an unknown or unsupported attribute
+ * type, the tracer has the option to either disallow the entire
+ * event, skip over the field containing the unknown attribute, or
+ * skip over the unknown attribute, both at event registration and
+ * when receiving the side_call arguments.
+ */
+
enum side_attr_type {
SIDE_ATTR_TYPE_NULL,
SIDE_ATTR_TYPE_BOOL,
#include <side/macros.h>
#include <side/endian.h>
+/*
+ * SIDE ABI event description.
+ *
+ * The extensibility scheme for the SIDE ABI event description is as
+ * follows:
+ *
+ * * Changing the semantic of the existing event description fields is a
+ * breaking ABI change: the SIDE_EVENT_DESCRIPTION_ABI_VERSION should
+ * be increased to reflect this.
+ *
+ * * Event descriptions can be extended by adding fields at the end of
+ * the structure. The "struct side_event_description" is a structure
+ * with flexible size which must not be used within arrays.
+ */
+
#define SIDE_EVENT_DESCRIPTION_ABI_VERSION 0
enum side_event_flags {
#include <side/abi/type-description.h>
#include <side/abi/visitor.h>
+/*
+ * SIDE ABI for arguments passed to instrumentation call site.
+ *
+ * The extensibility scheme for the SIDE ABI for call site arguments is
+ * as follows:
+ *
+ * * Existing argument types are never changed nor extended. Argument
+ * types can be added to the ABI by reserving a label within
+ * enum side_type_label.
+ * * Each union part of the ABI has an explicit size defined by a
+ * side_padding() member. Each structure and union have a static
+ * assert validating its size.
+ * * Changing the semantic of the existing argument type fields is a
+ * breaking ABI change.
+ *
+ * Handling of unknown argument types by the tracers:
+ *
+ * * A tracer may choose to support only a subset of the types supported
+ * by libside. When encountering an unknown or unsupported type, the
+ * tracer has the option to either disallow the entire event or skip
+ * over the unknown type, both at event registration and when
+ * receiving the side_call arguments.
+ */
+
#if (SIDE_BYTE_ORDER == SIDE_LITTLE_ENDIAN)
# define SIDE_TYPE_BYTE_ORDER_HOST SIDE_TYPE_BYTE_ORDER_LE
#else
#include <side/abi/attribute.h>
#include <side/abi/visitor.h>
+/*
+ * SIDE ABI for type description.
+ *
+ * This instrumentation ABI exposes 3 type systems:
+ *
+ * * Stack-copy type system: This is the core type system which can
+ * represent all supported types and into which all other type systems
+ * can be nested. This type system requires that every type is
+ * statically or dynamically declared and then registered, thus giving
+ * tracers a complete description of the events and their associated
+ * fields before the associated instrumentation is invoked. The
+ * application needs to copy each argument (side_arg_...()) onto the
+ * stack when calling the instrumentation.
+ *
+ * This is the most expressive of the 3 type systems, althrough not the
+ * fastest due to the extra copy of the arguments.
+ *
+ * * Data-gathering type system: This type system requires every type to
+ * be statically or dynamically declared and registered, but does not
+ * require the application to copy its arguments onto the stack.
+ * Instead, the type description contains all the required information
+ * to fetch the data from the application memory. The only argument
+ * required from the instrumentation is the base pointer from which
+ * the data should be fetched.
+ *
+ * This type system can be used as an event field, or nested within
+ * the stack-copy type system. Nesting of gather-vla within
+ * gather-array and gather-vla types is not allowed.
+ *
+ * This type system is has the least overhead of the 3 type systems.
+ *
+ * * Dynamic type system: This type system receives both type
+ * description and actual data onto the stack at runtime. It has more
+ * overhead that the 2 other type systems, but does not require a
+ * prior registration of event field description. This makes it useful
+ * for seldom used types which are not performance critical, but for
+ * which registering each individual events would needlessly grow the
+ * number of events to declare and register.
+ *
+ * Another use-case for this type system is for use by dynamically
+ * typed language runtimes, where the field type is only known when
+ * the instrumentation is called.
+ *
+ * Those dynamic types can be either used as arguments to a variadic
+ * field list, or as on-stack instrumentation argument for a static
+ * type SIDE_TYPE_DYNAMIC place holder in the stack-copy type system.
+ *
+ * The extensibility scheme for the SIDE ABI for type description is as
+ * follows:
+ *
+ * * Existing field types are never changed nor extended. Field types
+ * can be added to the ABI by reserving a label within
+ * enum side_type_label.
+ * * Each union part of the ABI has an explicit size defined by a
+ * side_padding() member. Each structure and union have a static
+ * assert validating its size.
+ * * Changing the semantic of the existing type fields is a breaking
+ * ABI change.
+ *
+ * Handling of unknown types by the tracers:
+ *
+ * * A tracer may choose to support only a subset of the types supported
+ * by libside. When encountering an unknown or unsupported type, the
+ * tracer has the option to either disallow the entire event or skip
+ * over the unknown type, both at event registration and when
+ * receiving the side_call arguments.
+ */
+
enum side_type_label {
/* Stack-copy basic types */
SIDE_TYPE_NULL,
#include <side/macros.h>
#include <side/endian.h>
+/*
+ * SIDE ABI for type values.
+ *
+ * The extensibility scheme for the SIDE ABI for type values is as
+ * follows:
+ *
+ * * Existing type values are never changed nor extended. Type values
+ * can be added to the ABI by reserving a label within enum
+ * side_type_label.
+ * * Each union part of the ABI has an explicit size defined by a
+ * side_padding() member. Each structure and union have a static
+ * assert validating its size.
+ * * Changing the semantic of the existing type value fields is a
+ * breaking ABI change.
+ *
+ * Handling of unknown type values by the tracers:
+ *
+ * * A tracer may choose to support only a subset of the type values
+ * supported by libside. When encountering an unknown or unsupported
+ * type value, the tracer has the option to either disallow the entire
+ * event or skip over the unknown type, both at event registration and
+ * when receiving the side_call arguments.
+ */
+
enum side_type_label_byte_order {
SIDE_TYPE_BYTE_ORDER_LE = 0,
SIDE_TYPE_BYTE_ORDER_BE = 1,
#include <side/macros.h>
#include <side/endian.h>
+/*
+ * SIDE ABI for visitor pattern.
+ *
+ * The visitor pattern is a double-dispatch visitor. Changing this ABI
+ * is a breaking ABI change.
+ *
+ * This ABI is a contract between the instrumented application and
+ * user-space tracers. Kernel tracers are not expected to interact with
+ * visitors directly: a proxy in libside should execute visitors to
+ * convert their output to other types which can be read by the kernel
+ * tracers.
+ */
+
struct side_arg;
struct side_arg_dynamic_field;
struct side_tracer_visitor_ctx;
struct side_tracer_dynamic_struct_visitor_ctx;
-/* The visitor pattern is a double-dispatch visitor. */
typedef enum side_visitor_status (*side_write_elem_func)(
const struct side_tracer_visitor_ctx *tracer_ctx,
* instrumentation type system and facilities allowing a kernel or
* user-space tracer to consume user-space instrumentation.
*
- * This instrumentation ABI exposes 3 type systems:
+ * The extensibility scheme for the SIDE ABI for event state is as
+ * follows:
*
- * * Stack-copy type system: This is the core type system which can
- * represent all supported types and into which all other type systems
- * can be nested. This type system requires that every type is
- * statically or dynamically declared and then registered, thus giving
- * tracers a complete description of the events and their associated
- * fields before the associated instrumentation is invoked. The
- * application needs to copy each argument (side_arg_...()) onto the
- * stack when calling the instrumentation.
- *
- * This is the most expressive of the 3 type systems, althrough not the
- * fastest due to the extra copy of the arguments.
- *
- * * Data-gathering type system: This type system requires every type to
- * be statically or dynamically declared and registered, but does not
- * require the application to copy its arguments onto the stack.
- * Instead, the type description contains all the required information
- * to fetch the data from the application memory. The only argument
- * required from the instrumentation is the base pointer from which
- * the data should be fetched.
- *
- * This type system can be used as an event field, or nested within
- * the stack-copy type system. Nesting of gather-vla within
- * gather-array and gather-vla types is not allowed.
- *
- * This type system is has the least overhead of the 3 type systems.
- *
- * * Dynamic type system: This type system receives both type
- * description and actual data onto the stack at runtime. It has more
- * overhead that the 2 other type systems, but does not require a
- * prior registration of event field description. This makes it useful
- * for seldom used types which are not performance critical, but for
- * which registering each individual events would needlessly grow the
- * number of events to declare and register.
- *
- * Another use-case for this type system is for use by dynamically
- * typed language runtimes, where the field type is only known when
- * the instrumentation is called.
- *
- * Those dynamic types can be either used as arguments to a variadic
- * field list, or as on-stack instrumentation argument for a static
- * type SIDE_TYPE_DYNAMIC place holder in the stack-copy type system.
- *
- * The extensibility scheme for the SIDE ABI is as follows:
- *
- * * Existing field types are never changed nor extended. Field types
- * can be added to the ABI by reserving a label within
- * enum side_type_label.
- * * Existing attribute types are never changed nor extended. Attribute
- * types can be added to the ABI by reserving a label within
- * enum side_attr_type.
- * * Each union part of the ABI has an explicit size defined by a
- * side_padding() member. Each structure and union have a static
- * assert validating its size.
- * * If the semantic of the existing event description or type fields
- * change, the SIDE_EVENT_DESCRIPTION_ABI_VERSION should be increased.
* * If the semantic of the "struct side_event_state_N" fields change,
* the SIDE_EVENT_STATE_ABI_VERSION should be increased. The
* "struct side_event_state_N" is not extensible and must have its
* ABI version increased whenever it is changed. Note that increasing
* the version of SIDE_EVENT_DESCRIPTION_ABI_VERSION is not necessary
* when changing the layout of "struct side_event_state_N".
- *
- * Handling of unknown types by the tracers:
- *
- * * A tracer may choose to support only a subset of the types supported
- * by libside. When encountering an unknown or unsupported type, the
- * tracer has the option to either disallow the entire event or skip
- * over the unknown type, both at event registration and when
- * receiving the side_call arguments.
- *
- * * Event descriptions can be extended by adding fields at the end of
- * the structure. The "struct side_event_description" is a structure
- * with flexible size which must not be used within arrays.
*/
#define SIDE_EVENT_STATE_ABI_VERSION 0
projects / libside.git / commitdiff
