include/lttng/ust-events.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2010-2012 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
   5  *
   6  * Holds LTTng per-session event registry.
   7  */
   8
   9 #ifndef _LTTNG_UST_EVENTS_H
  10 #define _LTTNG_UST_EVENTS_H
  11
  12 #include <urcu/list.h>
  13 #include <urcu/hlist.h>
  14 #include <stddef.h>
  15 #include <stdint.h>
  16 #include <lttng/ust-abi.h>
  17 #include <lttng/ust-tracer.h>
  18 #include <lttng/ust-endian.h>
  19 #include <float.h>
  20 #include <errno.h>
  21 #include <urcu/ref.h>
  22 #include <pthread.h>
  23
  24 #ifndef LTTNG_PACKED
  25 #error "LTTNG_PACKED should be defined"
  26 #endif
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 #define LTTNG_UST_UUID_LEN              16
  33
  34 /*
  35  * Tracepoint provider version. Compatibility based on the major number.
  36  * Older tracepoint providers can always register to newer lttng-ust
  37  * library, but the opposite is rejected: a newer tracepoint provider is
  38  * rejected by an older lttng-ust library.
  39  */
  40 #define LTTNG_UST_PROVIDER_MAJOR        2
  41 #define LTTNG_UST_PROVIDER_MINOR        0
  42
  43 struct lttng_channel;
  44 struct lttng_session;
  45 struct lttng_ust_lib_ring_buffer_ctx;
  46 struct lttng_event_field;
  47 struct lttng_event_notifier;
  48 struct lttng_event_notifier_group;
  49
  50 /*
  51  * Data structures used by tracepoint event declarations, and by the
  52  * tracer. Those structures have padding for future extension.
  53  */
  54
  55 /* Type description */
  56
  57 /* Update the astract_types name table in lttng-types.c along with this enum */
  58 enum lttng_abstract_types {
  59         atype_integer,
  60         atype_string,
  61         atype_float,
  62         atype_dynamic,
  63         atype_enum_nestable,
  64         atype_array_nestable,
  65         atype_sequence_nestable,
  66         atype_struct_nestable,
  67         NR_ABSTRACT_TYPES,
  68 };
  69
  70 /* Update the string_encodings name table in lttng-types.c along with this enum */
  71 enum lttng_string_encodings {
  72         lttng_encode_none = 0,
  73         lttng_encode_UTF8 = 1,
  74         lttng_encode_ASCII = 2,
  75         NR_STRING_ENCODINGS,
  76 };
  77
  78 struct lttng_enum_value {
  79         unsigned long long value;
  80         unsigned int signedness:1;
  81 };
  82
  83 enum lttng_enum_entry_options {
  84         LTTNG_ENUM_ENTRY_OPTION_IS_AUTO = 1U << 0,
  85 };
  86
  87 #define LTTNG_UST_ENUM_ENTRY_PADDING    16
  88 struct lttng_enum_entry {
  89         struct lttng_enum_value start, end; /* start and end are inclusive */
  90         const char *string;
  91         union {
  92                 struct {
  93                         unsigned int options;
  94                 } LTTNG_PACKED extra;
  95                 char padding[LTTNG_UST_ENUM_ENTRY_PADDING];
  96         } u;
  97 };
  98
  99 #define __type_integer(_type, _byte_order, _base, _encoding)    \
 100         {                                                       \
 101           .atype = atype_integer,                               \
 102           .u =                                                  \
 103                 {                                               \
 104                   .integer =                                    \
 105                         {                                       \
 106                           .size = sizeof(_type) * CHAR_BIT,     \
 107                           .alignment = lttng_alignof(_type) * CHAR_BIT, \
 108                           .signedness = lttng_is_signed_type(_type), \
 109                           .reverse_byte_order = _byte_order != BYTE_ORDER, \
 110                           .base = _base,                        \
 111                           .encoding = lttng_encode_##_encoding, \
 112                         }                                       \
 113                 },                                              \
 114         }                                                       \
 115
 116 #define LTTNG_UST_INTEGER_TYPE_PADDING  24
 117 struct lttng_integer_type {
 118         unsigned int size;              /* in bits */
 119         unsigned short alignment;       /* in bits */
 120         unsigned int signedness:1;
 121         unsigned int reverse_byte_order:1;
 122         unsigned int base;              /* 2, 8, 10, 16, for pretty print */
 123         enum lttng_string_encodings encoding;
 124         char padding[LTTNG_UST_INTEGER_TYPE_PADDING];
 125 };
 126
 127 /*
 128  * Only float and double are supported. long double is not supported at
 129  * the moment.
 130  */
 131 #define _float_mant_dig(_type)                                          \
 132         (sizeof(_type) == sizeof(float) ? FLT_MANT_DIG                  \
 133                 : (sizeof(_type) == sizeof(double) ? DBL_MANT_DIG       \
 134                 : 0))
 135
 136 #define __type_float(_type)                                     \
 137         {                                                       \
 138           .atype = atype_float,                                 \
 139           .u =                                                  \
 140                 {                                               \
 141                   ._float =                                     \
 142                         {                                       \
 143                           .exp_dig = sizeof(_type) * CHAR_BIT   \
 144                                           - _float_mant_dig(_type), \
 145                           .mant_dig = _float_mant_dig(_type),   \
 146                           .alignment = lttng_alignof(_type) * CHAR_BIT, \
 147                           .reverse_byte_order = BYTE_ORDER != FLOAT_WORD_ORDER, \
 148                         }                                       \
 149                 }                                               \
 150         }                                                       \
 151
 152 #define LTTNG_UST_FLOAT_TYPE_PADDING    24
 153 struct lttng_float_type {
 154         unsigned int exp_dig;           /* exponent digits, in bits */
 155         unsigned int mant_dig;          /* mantissa digits, in bits */
 156         unsigned short alignment;       /* in bits */
 157         unsigned int reverse_byte_order:1;
 158         char padding[LTTNG_UST_FLOAT_TYPE_PADDING];
 159 };
 160
 161 #define LTTNG_UST_TYPE_PADDING  128
 162 struct lttng_type {
 163         enum lttng_abstract_types atype;
 164         union {
 165                 /* provider ABI 2.0 */
 166                 struct lttng_integer_type integer;
 167                 struct lttng_float_type _float;
 168                 struct {
 169                         enum lttng_string_encodings encoding;
 170                 } string;
 171                 struct {
 172                         const struct lttng_enum_desc *desc;     /* Enumeration mapping */
 173                         struct lttng_type *container_type;
 174                 } enum_nestable;
 175                 struct {
 176                         const struct lttng_type *elem_type;
 177                         unsigned int length;                    /* Num. elems. */
 178                         unsigned int alignment;
 179                 } array_nestable;
 180                 struct {
 181                         const char *length_name;                /* Length field name. */
 182                         const struct lttng_type *elem_type;
 183                         unsigned int alignment;                 /* Alignment before elements. */
 184                 } sequence_nestable;
 185                 struct {
 186                         unsigned int nr_fields;
 187                         const struct lttng_event_field *fields; /* Array of fields. */
 188                         unsigned int alignment;
 189                 } struct_nestable;
 190
 191                 char padding[LTTNG_UST_TYPE_PADDING];
 192         } u;
 193 };
 194
 195 #define LTTNG_UST_ENUM_TYPE_PADDING     24
 196 struct lttng_enum_desc {
 197         const char *name;
 198         const struct lttng_enum_entry *entries;
 199         unsigned int nr_entries;
 200         char padding[LTTNG_UST_ENUM_TYPE_PADDING];
 201 };
 202
 203 /*
 204  * Event field description
 205  *
 206  * IMPORTANT: this structure is part of the ABI between the probe and
 207  * UST. Fields need to be only added at the end, never reordered, never
 208  * removed.
 209  */
 210
 211 #define LTTNG_UST_EVENT_FIELD_PADDING   28
 212 struct lttng_event_field {
 213         const char *name;
 214         struct lttng_type type;
 215         unsigned int nowrite;   /* do not write into trace */
 216         union {
 217                 struct {
 218                         unsigned int nofilter:1;        /* do not consider for filter */
 219                 } ext;
 220                 char padding[LTTNG_UST_EVENT_FIELD_PADDING];
 221         } u;
 222 };
 223
 224 enum lttng_ust_dynamic_type {
 225         LTTNG_UST_DYNAMIC_TYPE_NONE,
 226         LTTNG_UST_DYNAMIC_TYPE_S8,
 227         LTTNG_UST_DYNAMIC_TYPE_S16,
 228         LTTNG_UST_DYNAMIC_TYPE_S32,
 229         LTTNG_UST_DYNAMIC_TYPE_S64,
 230         LTTNG_UST_DYNAMIC_TYPE_U8,
 231         LTTNG_UST_DYNAMIC_TYPE_U16,
 232         LTTNG_UST_DYNAMIC_TYPE_U32,
 233         LTTNG_UST_DYNAMIC_TYPE_U64,
 234         LTTNG_UST_DYNAMIC_TYPE_FLOAT,
 235         LTTNG_UST_DYNAMIC_TYPE_DOUBLE,
 236         LTTNG_UST_DYNAMIC_TYPE_STRING,
 237         _NR_LTTNG_UST_DYNAMIC_TYPES,
 238 };
 239
 240 struct lttng_ctx_value {
 241         enum lttng_ust_dynamic_type sel;
 242         union {
 243                 int64_t s64;
 244                 uint64_t u64;
 245                 const char *str;
 246                 double d;
 247         } u;
 248 };
 249
 250 struct lttng_perf_counter_field;
 251
 252 #define LTTNG_UST_CTX_FIELD_PADDING     40
 253 struct lttng_ctx_field {
 254         struct lttng_event_field event_field;
 255         size_t (*get_size)(struct lttng_ctx_field *field, size_t offset);
 256         void (*record)(struct lttng_ctx_field *field,
 257                        struct lttng_ust_lib_ring_buffer_ctx *ctx,
 258                        struct lttng_channel *chan);
 259         void (*get_value)(struct lttng_ctx_field *field,
 260                          struct lttng_ctx_value *value);
 261         union {
 262                 struct lttng_perf_counter_field *perf_counter;
 263                 char padding[LTTNG_UST_CTX_FIELD_PADDING];
 264         } u;
 265         void (*destroy)(struct lttng_ctx_field *field);
 266         char *field_name;       /* Has ownership, dynamically allocated. */
 267 };
 268
 269 #define LTTNG_UST_CTX_PADDING   20
 270 struct lttng_ctx {
 271         struct lttng_ctx_field *fields;
 272         unsigned int nr_fields;
 273         unsigned int allocated_fields;
 274         unsigned int largest_align;
 275         char padding[LTTNG_UST_CTX_PADDING];
 276 };
 277
 278 #define LTTNG_UST_EVENT_DESC_PADDING    40
 279 struct lttng_event_desc {
 280         const char *name;
 281         void (*probe_callback)(void);
 282         const struct lttng_event_ctx *ctx;      /* context */
 283         const struct lttng_event_field *fields; /* event payload */
 284         unsigned int nr_fields;
 285         const int **loglevel;
 286         const char *signature;  /* Argument types/names received */
 287         union {
 288                 struct {
 289                         const char **model_emf_uri;
 290                         void (*event_notifier_callback)(void);
 291                 } ext;
 292                 char padding[LTTNG_UST_EVENT_DESC_PADDING];
 293         } u;
 294 };
 295
 296 #define LTTNG_UST_PROBE_DESC_PADDING    12
 297 struct lttng_probe_desc {
 298         const char *provider;
 299         const struct lttng_event_desc **event_desc;
 300         unsigned int nr_events;
 301         struct cds_list_head head;              /* chain registered probes */
 302         struct cds_list_head lazy_init_head;
 303         int lazy;                               /* lazy registration */
 304         uint32_t major;
 305         uint32_t minor;
 306         char padding[LTTNG_UST_PROBE_DESC_PADDING];
 307 };
 308
 309 /* Data structures used by the tracer. */
 310
 311 /*
 312  * Bytecode interpreter return value masks.
 313  */
 314 enum lttng_bytecode_interpreter_ret {
 315         LTTNG_INTERPRETER_DISCARD = 0,
 316         LTTNG_INTERPRETER_RECORD_FLAG = (1ULL << 0),
 317         /* Other bits are kept for future use. */
 318 };
 319
 320 struct lttng_interpreter_output;
 321 struct lttng_ust_bytecode_runtime_private;
 322
 323 /*
 324  * This structure is used in the probes. More specifically, the
 325  * `interpreter_funcs` and `node` fields are explicity used in the
 326  * probes. When modifying this structure we must not change the layout
 327  * of these two fields as it is considered ABI.
 328  */
 329 struct lttng_bytecode_runtime {
 330         struct lttng_ust_bytecode_runtime_private *priv;
 331
 332         /* Associated bytecode */
 333         union {
 334                 uint64_t (*filter)(void *interpreter_data,
 335                                 const char *interpreter_stack_data);
 336                 uint64_t (*capture)(void *interpreter_data,
 337                                 const char *interpreter_stack_data,
 338                                 struct lttng_interpreter_output *interpreter_output);
 339         } interpreter_funcs;
 340         struct cds_list_head node;      /* list of bytecode runtime in event */
 341 };
 342
 343 /*
 344  * lttng_event structure is referred to by the tracing fast path. It
 345  * must be kept small.
 346  *
 347  * IMPORTANT: this structure is part of the ABI between the probe and
 348  * UST. Fields need to be only added at the end, never reordered, never
 349  * removed.
 350  */
 351
 352 struct lttng_ust_event_common_private;
 353
 354 struct lttng_event_common {
 355         uint32_t struct_size;                           /* Size of this structure. */
 356         struct lttng_ust_event_common_private *priv;    /* Private event interface */
 357
 358         int enabled;
 359         int has_enablers_without_bytecode;
 360         /* list of struct lttng_bytecode_runtime, sorted by seqnum */
 361         struct cds_list_head filter_bytecode_runtime_head;
 362 };
 363
 364 struct lttng_ust_event_private;
 365
 366 struct lttng_event {
 367         uint32_t struct_size;                   /* Size of this structure. */
 368         struct lttng_event_common *parent;
 369         struct lttng_ust_event_private *priv;   /* Private event interface */
 370
 371         unsigned int id;
 372         struct lttng_channel *chan;
 373         struct lttng_ctx *ctx;
 374 };
 375
 376 struct lttng_event_notifier {
 377         uint64_t user_token;
 378         uint64_t error_counter_index;
 379         int enabled;
 380         int registered;                 /* has reg'd tracepoint probe */
 381         size_t num_captures;            /* Needed to allocate the msgpack array. */
 382         void (*notification_send)(struct lttng_event_notifier *event_notifier,
 383                 const char *stack_data);
 384         struct cds_list_head filter_bytecode_runtime_head;
 385         struct cds_list_head capture_bytecode_runtime_head;
 386         int has_enablers_without_bytecode;
 387         struct cds_list_head enablers_ref_head;
 388         const struct lttng_event_desc *desc;
 389         struct cds_hlist_node hlist;    /* hashtable of event_notifiers */
 390         struct cds_list_head node;      /* event_notifier list in session */
 391         struct lttng_event_notifier_group *group; /* weak ref */
 392 };
 393
 394 struct lttng_enum {
 395         const struct lttng_enum_desc *desc;
 396         struct lttng_session *session;
 397         struct cds_list_head node;      /* Enum list in session */
 398         struct cds_hlist_node hlist;    /* Session ht of enums */
 399         uint64_t id;                    /* Enumeration ID in sessiond */
 400 };
 401
 402 struct channel;
 403 struct lttng_ust_shm_handle;
 404
 405 /*
 406  * IMPORTANT: this structure is part of the ABI between the probe and
 407  * UST. Fields need to be only added at the end, never reordered, never
 408  * removed.
 409  */
 410 struct lttng_channel_ops {
 411         struct lttng_channel *(*channel_create)(const char *name,
 412                         void *buf_addr,
 413                         size_t subbuf_size, size_t num_subbuf,
 414                         unsigned int switch_timer_interval,
 415                         unsigned int read_timer_interval,
 416                         unsigned char *uuid,
 417                         uint32_t chan_id,
 418                         const int *stream_fds, int nr_stream_fds,
 419                         int64_t blocking_timeout);
 420         void (*channel_destroy)(struct lttng_channel *chan);
 421         int (*event_reserve)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
 422                              uint32_t event_id);
 423         void (*event_commit)(struct lttng_ust_lib_ring_buffer_ctx *ctx);
 424         void (*event_write)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
 425                         const void *src, size_t len);
 426         /*
 427          * packet_avail_size returns the available size in the current
 428          * packet. Note that the size returned is only a hint, since it
 429          * may change due to concurrent writes.
 430          */
 431         size_t (*packet_avail_size)(struct channel *chan,
 432                                     struct lttng_ust_shm_handle *handle);
 433         int (*is_finalized)(struct channel *chan);
 434         int (*is_disabled)(struct channel *chan);
 435         int (*flush_buffer)(struct channel *chan, struct lttng_ust_shm_handle *handle);
 436         void (*event_strcpy)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
 437                         const char *src, size_t len);
 438 };
 439
 440 /*
 441  * IMPORTANT: this structure is part of the ABI between the probe and
 442  * UST. Fields need to be only added at the end, never reordered, never
 443  * removed.
 444  */
 445 struct lttng_channel {
 446         /*
 447          * The pointers located in this private data are NOT safe to be
 448          * dereferenced by the consumer. The only operations the
 449          * consumer process is designed to be allowed to do is to read
 450          * and perform subbuffer flush.
 451          */
 452         struct channel *chan;           /* Channel buffers */
 453         int enabled;
 454         struct lttng_ctx *ctx;
 455         /* Event ID management */
 456         struct lttng_session *session;
 457         int objd;                       /* Object associated to channel */
 458         struct cds_list_head node;      /* Channel list in session */
 459         const struct lttng_channel_ops *ops;
 460         int header_type;                /* 0: unset, 1: compact, 2: large */
 461         struct lttng_ust_shm_handle *handle;    /* shared-memory handle */
 462
 463         /* Channel ID */
 464         unsigned int id;
 465         enum lttng_ust_chan_type type;
 466         unsigned char uuid[LTTNG_UST_UUID_LEN]; /* Trace session unique ID */
 467         int tstate:1;                   /* Transient enable state */
 468 };
 469
 470 struct lttng_counter_dimension;
 471
 472 struct lttng_counter_ops {
 473         struct lib_counter *(*counter_create)(size_t nr_dimensions,
 474                         const struct lttng_counter_dimension *dimensions,
 475                         int64_t global_sum_step,
 476                         int global_counter_fd,
 477                         int nr_counter_cpu_fds,
 478                         const int *counter_cpu_fds,
 479                         bool is_daemon);
 480         void (*counter_destroy)(struct lib_counter *counter);
 481         int (*counter_add)(struct lib_counter *counter,
 482                         const size_t *dimension_indexes, int64_t v);
 483         int (*counter_read)(struct lib_counter *counter,
 484                         const size_t *dimension_indexes, int cpu,
 485                         int64_t *value, bool *overflow, bool *underflow);
 486         int (*counter_aggregate)(struct lib_counter *counter,
 487                         const size_t *dimension_indexes, int64_t *value,
 488                         bool *overflow, bool *underflow);
 489         int (*counter_clear)(struct lib_counter *counter, const size_t *dimension_indexes);
 490 };
 491
 492 #define LTTNG_UST_STACK_CTX_PADDING     32
 493 struct lttng_stack_ctx {
 494         struct lttng_event *event;
 495         struct lttng_ctx *chan_ctx;     /* RCU dereferenced. */
 496         struct lttng_ctx *event_ctx;    /* RCU dereferenced. */
 497         char padding[LTTNG_UST_STACK_CTX_PADDING];
 498 };
 499
 500 #define LTTNG_UST_EVENT_HT_BITS         12
 501 #define LTTNG_UST_EVENT_HT_SIZE         (1U << LTTNG_UST_EVENT_HT_BITS)
 502
 503 struct lttng_ust_event_ht {
 504         struct cds_hlist_head table[LTTNG_UST_EVENT_HT_SIZE];
 505 };
 506
 507 #define LTTNG_UST_EVENT_NOTIFIER_HT_BITS                12
 508 #define LTTNG_UST_EVENT_NOTIFIER_HT_SIZE                (1U << LTTNG_UST_EVENT_NOTIFIER_HT_BITS)
 509 struct lttng_ust_event_notifier_ht {
 510         struct cds_hlist_head table[LTTNG_UST_EVENT_NOTIFIER_HT_SIZE];
 511 };
 512
 513 #define LTTNG_UST_ENUM_HT_BITS          12
 514 #define LTTNG_UST_ENUM_HT_SIZE          (1U << LTTNG_UST_ENUM_HT_BITS)
 515
 516 struct lttng_ust_enum_ht {
 517         struct cds_hlist_head table[LTTNG_UST_ENUM_HT_SIZE];
 518 };
 519
 520 struct lttng_ust_session_private;
 521
 522 /*
 523  * IMPORTANT: this structure is part of the ABI between the probe and
 524  * UST. Fields need to be only added at the end, never reordered, never
 525  * removed.
 526  */
 527 struct lttng_session {
 528         uint32_t struct_size;                   /* Size of this structure */
 529         struct lttng_ust_session_private *priv; /* Private session interface */
 530
 531         int active;                             /* Is trace session active ? */
 532 };
 533
 534 int lttng_probe_register(struct lttng_probe_desc *desc);
 535 void lttng_probe_unregister(struct lttng_probe_desc *desc);
 536
 537 /*
 538  * Can be used by applications that change their procname to clear the ust cached value.
 539  */
 540 void lttng_context_procname_reset(void);
 541
 542 struct lttng_transport *lttng_transport_find(const char *name);
 543
 544 int lttng_session_active(void);
 545
 546 void lttng_ust_dl_update(void *ip);
 547
 548 #ifdef __cplusplus
 549 }
 550 #endif
 551
 552 #endif /* _LTTNG_UST_EVENTS_H */