include/side/trace.h

   1 // SPDX-License-Identifier: MIT
   2 /*
   3  * Copyright 2022 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
   4  */
   5
   6 #ifndef _SIDE_TRACE_H
   7 #define _SIDE_TRACE_H
   8
   9 #include <stdint.h>
  10 #include <inttypes.h>
  11 #include <stdlib.h>
  12 #include <stdio.h>
  13 #include <math.h>
  14 #include <stdbool.h>
  15 #include <stddef.h>
  16 #include <side/macros.h>
  17 #include <side/endian.h>
  18
  19 /*
  20  * SIDE stands for "Software Instrumentation Dynamically Enabled"
  21  *
  22  * This is an instrumentation ABI for Linux user-space, which exposes an
  23  * instrumentation type system and facilities allowing a kernel or
  24  * user-space tracer to consume user-space instrumentation.
  25  *
  26  * The extensibility scheme for the SIDE ABI for event state is as
  27  * follows:
  28  *
  29  * * If the semantic of the "struct side_event_state_N" fields change,
  30  *   the SIDE_EVENT_STATE_ABI_VERSION should be increased. The
  31  *   "struct side_event_state_N" is not extensible and must have its
  32  *   ABI version increased whenever it is changed. Note that increasing
  33  *   the version of SIDE_EVENT_DESCRIPTION_ABI_VERSION is not necessary
  34  *   when changing the layout of "struct side_event_state_N".
  35  */
  36
  37 #define SIDE_EVENT_STATE_ABI_VERSION            0
  38
  39 #include <side/abi/event-description.h>
  40 #include <side/abi/type-argument.h>
  41 #include <side/instrumentation-c-api.h>
  42
  43 enum side_error {
  44         SIDE_ERROR_OK = 0,
  45         SIDE_ERROR_INVAL = 1,
  46         SIDE_ERROR_EXIST = 2,
  47         SIDE_ERROR_NOMEM = 3,
  48         SIDE_ERROR_NOENT = 4,
  49         SIDE_ERROR_EXITING = 5,
  50 };
  51
  52 /*
  53  * This structure is _not_ packed to allow atomic operations on its
  54  * fields. Changes to this structure must bump the "Event state ABI
  55  * version" and tracers _must_ learn how to deal with this ABI,
  56  * otherwise they should reject the event.
  57  */
  58
  59 struct side_event_state {
  60         uint32_t version;       /* Event state ABI version. */
  61 };
  62
  63 struct side_event_state_0 {
  64         struct side_event_state p;      /* Required first field. */
  65         uint32_t enabled;
  66         side_ptr_t(const struct side_callback) callbacks;
  67         side_ptr_t(struct side_event_description) desc;
  68 };
  69
  70 #ifdef __cplusplus
  71 extern "C" {
  72 #endif
  73
  74 struct side_callback {
  75         union {
  76                 void (*call)(const struct side_event_description *desc,
  77                         const struct side_arg_vec *side_arg_vec,
  78                         void *priv);
  79                 void (*call_variadic)(const struct side_event_description *desc,
  80                         const struct side_arg_vec *side_arg_vec,
  81                         const struct side_arg_dynamic_struct *var_struct,
  82                         void *priv);
  83         } SIDE_PACKED u;
  84         void *priv;
  85 } SIDE_PACKED;
  86
  87 extern const struct side_callback side_empty_callback;
  88
  89 void side_call(const struct side_event_state *state,
  90         const struct side_arg_vec *side_arg_vec);
  91 void side_call_variadic(const struct side_event_state *state,
  92         const struct side_arg_vec *side_arg_vec,
  93         const struct side_arg_dynamic_struct *var_struct);
  94
  95 struct side_events_register_handle *side_events_register(struct side_event_description **events,
  96                 uint32_t nr_events);
  97 void side_events_unregister(struct side_events_register_handle *handle);
  98
  99 /*
 100  * Userspace tracer registration API. This allows userspace tracers to
 101  * register event notification callbacks to be notified of the currently
 102  * registered instrumentation, and to register their callbacks to
 103  * specific events.
 104  */
 105 typedef void (*side_tracer_callback_func)(const struct side_event_description *desc,
 106                         const struct side_arg_vec *side_arg_vec,
 107                         void *priv);
 108 typedef void (*side_tracer_callback_variadic_func)(const struct side_event_description *desc,
 109                         const struct side_arg_vec *side_arg_vec,
 110                         const struct side_arg_dynamic_struct *var_struct,
 111                         void *priv);
 112
 113 int side_tracer_callback_register(struct side_event_description *desc,
 114                 side_tracer_callback_func call,
 115                 void *priv);
 116 int side_tracer_callback_variadic_register(struct side_event_description *desc,
 117                 side_tracer_callback_variadic_func call_variadic,
 118                 void *priv);
 119 int side_tracer_callback_unregister(struct side_event_description *desc,
 120                 side_tracer_callback_func call,
 121                 void *priv);
 122 int side_tracer_callback_variadic_unregister(struct side_event_description *desc,
 123                 side_tracer_callback_variadic_func call_variadic,
 124                 void *priv);
 125
 126 enum side_tracer_notification {
 127         SIDE_TRACER_NOTIFICATION_INSERT_EVENTS,
 128         SIDE_TRACER_NOTIFICATION_REMOVE_EVENTS,
 129 };
 130
 131 /* Callback is invoked with side library internal lock held. */
 132 struct side_tracer_handle *side_tracer_event_notification_register(
 133                 void (*cb)(enum side_tracer_notification notif,
 134                         struct side_event_description **events, uint32_t nr_events, void *priv),
 135                 void *priv);
 136 void side_tracer_event_notification_unregister(struct side_tracer_handle *handle);
 137
 138 /*
 139  * Explicit hooks to initialize/finalize the side instrumentation
 140  * library. Those are also library constructor/destructor.
 141  */
 142 void side_init(void) __attribute__((constructor));
 143 void side_exit(void) __attribute__((destructor));
 144
 145 /*
 146  * The following constructors/destructors perform automatic registration
 147  * of the declared side events. Those may have to be called explicitly
 148  * in a statically linked library.
 149  */
 150
 151 /*
 152  * These weak symbols, the constructor, and destructor take care of
 153  * registering only _one_ instance of the side instrumentation per
 154  * shared-ojbect (or for the whole main program).
 155  */
 156 extern struct side_event_description * __start_side_event_description_ptr[]
 157         __attribute__((weak, visibility("hidden")));
 158 extern struct side_event_description * __stop_side_event_description_ptr[]
 159         __attribute__((weak, visibility("hidden")));
 160 int side_event_description_ptr_registered
 161         __attribute__((weak, visibility("hidden")));
 162 struct side_events_register_handle *side_events_handle
 163         __attribute__((weak, visibility("hidden")));
 164
 165 static void
 166 side_event_description_ptr_init(void)
 167         __attribute__((no_instrument_function))
 168         __attribute__((constructor));
 169 static void
 170 side_event_description_ptr_init(void)
 171 {
 172         if (side_event_description_ptr_registered++)
 173                 return;
 174         side_events_handle = side_events_register(__start_side_event_description_ptr,
 175                 __stop_side_event_description_ptr - __start_side_event_description_ptr);
 176 }
 177
 178 static void
 179 side_event_description_ptr_exit(void)
 180         __attribute__((no_instrument_function))
 181         __attribute__((destructor));
 182 static void
 183 side_event_description_ptr_exit(void)
 184 {
 185         if (--side_event_description_ptr_registered)
 186                 return;
 187         side_events_unregister(side_events_handle);
 188         side_events_handle = NULL;
 189 }
 190
 191 #ifdef __cplusplus
 192 }
 193 #endif
 194
 195 #endif /* _SIDE_TRACE_H */