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_ust_session;
  45 struct lttng_ust_lib_ring_buffer_ctx;
  46 struct lttng_ust_event_field;
  47
  48 /*
  49  * Data structures used by tracepoint event declarations, and by the
  50  * tracer.
  51  */
  52
  53 /* Type description */
  54
  55 enum lttng_ust_type {
  56         lttng_ust_type_integer,
  57         lttng_ust_type_string,
  58         lttng_ust_type_float,
  59         lttng_ust_type_dynamic,
  60         lttng_ust_type_enum,
  61         lttng_ust_type_array,
  62         lttng_ust_type_sequence,
  63         lttng_ust_type_struct,
  64         NR_LTTNG_UST_TYPE,
  65 };
  66
  67 enum lttng_ust_string_encoding {
  68         lttng_ust_string_encoding_none = 0,
  69         lttng_ust_string_encoding_UTF8 = 1,
  70         lttng_ust_string_encoding_ASCII = 2,
  71         NR_LTTNG_UST_STRING_ENCODING,
  72 };
  73
  74 struct lttng_ust_enum_value {
  75         unsigned long long value;
  76         unsigned int signedness:1;
  77 };
  78
  79 enum lttng_ust_enum_entry_option {
  80         LTTNG_UST_ENUM_ENTRY_OPTION_IS_AUTO = 1U << 0,
  81 };
  82
  83 /*
  84  * Enumeration entry description
  85  *
  86  * IMPORTANT: this structure is part of the ABI between the probe and
  87  * UST. Fields need to be only added at the end, never reordered, never
  88  * removed.
  89  *
  90  * The field @struct_size should be used to determine the size of the
  91  * structure. It should be queried before using additional fields added
  92  * at the end of the structure.
  93  */
  94
  95 struct lttng_ust_enum_entry {
  96         uint32_t struct_size;
  97
  98         struct lttng_ust_enum_value start, end; /* start and end are inclusive */
  99         const char *string;
 100         unsigned int options;
 101
 102         /* End of base ABI. Fields below should be used after checking struct_size. */
 103 };
 104
 105 /*
 106  * struct lttng_ust_type_common is fixed-size. Its children inherits
 107  * from it by embedding struct lttng_ust_type_common as its first field.
 108  */
 109 struct lttng_ust_type_common {
 110         enum lttng_ust_type type;
 111 };
 112
 113 struct lttng_ust_type_integer {
 114         struct lttng_ust_type_common parent;
 115         uint32_t struct_size;
 116         unsigned int size;              /* in bits */
 117         unsigned short alignment;       /* in bits */
 118         unsigned int signedness:1;
 119         unsigned int reverse_byte_order:1;
 120         unsigned int base;              /* 2, 8, 10, 16, for pretty print */
 121 };
 122
 123 #define lttng_ust_type_integer_define(_type, _byte_order, _base)        \
 124         ((struct lttng_ust_type_common *) __LTTNG_COMPOUND_LITERAL(struct lttng_ust_type_integer, { \
 125                 .parent = {                                             \
 126                         .type = lttng_ust_type_integer,                 \
 127                 },                                                      \
 128                 .struct_size = sizeof(struct lttng_ust_type_integer),   \
 129                 .size = sizeof(_type) * CHAR_BIT,                       \
 130                 .alignment = lttng_alignof(_type) * CHAR_BIT,           \
 131                 .signedness = lttng_is_signed_type(_type),              \
 132                 .reverse_byte_order = _byte_order != BYTE_ORDER,        \
 133                 .base = _base,                                          \
 134         }))
 135
 136 struct lttng_ust_type_float {
 137         struct lttng_ust_type_common parent;
 138         uint32_t struct_size;
 139         unsigned int exp_dig;           /* exponent digits, in bits */
 140         unsigned int mant_dig;          /* mantissa digits, in bits */
 141         unsigned short alignment;       /* in bits */
 142         unsigned int reverse_byte_order:1;
 143 };
 144
 145 /*
 146  * Only float and double are supported. long double is not supported at
 147  * the moment.
 148  */
 149 #define lttng_ust_float_mant_dig(_type)                                 \
 150         (sizeof(_type) == sizeof(float) ? FLT_MANT_DIG                  \
 151                 : (sizeof(_type) == sizeof(double) ? DBL_MANT_DIG       \
 152                 : 0))
 153
 154 #define lttng_ust_type_float_define(_type)                              \
 155         ((struct lttng_ust_type_common *) __LTTNG_COMPOUND_LITERAL(struct lttng_ust_type_float, { \
 156                 .parent = {                                             \
 157                         .type = lttng_ust_type_float,                   \
 158                 },                                                      \
 159                 .struct_size = sizeof(struct lttng_ust_type_float),     \
 160                 .exp_dig = sizeof(_type) * CHAR_BIT                     \
 161                         - lttng_ust_float_mant_dig(_type),              \
 162                 .mant_dig = lttng_ust_float_mant_dig(_type),            \
 163                 .alignment = lttng_alignof(_type) * CHAR_BIT,           \
 164                 .reverse_byte_order = BYTE_ORDER != FLOAT_WORD_ORDER,   \
 165         }))
 166
 167
 168 struct lttng_ust_type_string {
 169         struct lttng_ust_type_common parent;
 170         uint32_t struct_size;
 171         enum lttng_ust_string_encoding encoding;
 172 };
 173
 174 struct lttng_ust_type_enum {
 175         struct lttng_ust_type_common parent;
 176         uint32_t struct_size;
 177         struct lttng_ust_enum_desc *desc;       /* Enumeration mapping */
 178         struct lttng_ust_type_common *container_type;
 179 };
 180
 181 struct lttng_ust_type_array {
 182         struct lttng_ust_type_common parent;
 183         uint32_t struct_size;
 184         struct lttng_ust_type_common *elem_type;
 185         unsigned int length;                    /* Num. elems. */
 186         unsigned int alignment;
 187         enum lttng_ust_string_encoding encoding;
 188 };
 189
 190 struct lttng_ust_type_sequence {
 191         struct lttng_ust_type_common parent;
 192         uint32_t struct_size;
 193         const char *length_name;        /* Length field name. */
 194         struct lttng_ust_type_common *elem_type;
 195         unsigned int alignment;         /* Alignment before elements. */
 196         enum lttng_ust_string_encoding encoding;
 197 };
 198
 199 struct lttng_ust_type_struct {
 200         struct lttng_ust_type_common parent;
 201         uint32_t struct_size;
 202         unsigned int nr_fields;
 203         struct lttng_ust_event_field **fields;  /* Array of pointers to fields. */
 204         unsigned int alignment;
 205 };
 206
 207 /*
 208  * Enumeration description
 209  *
 210  * IMPORTANT: this structure is part of the ABI between the probe and
 211  * UST. Fields need to be only added at the end, never reordered, never
 212  * removed.
 213  *
 214  * The field @struct_size should be used to determine the size of the
 215  * structure. It should be queried before using additional fields added
 216  * at the end of the structure.
 217  */
 218
 219 struct lttng_ust_enum_desc {
 220         uint32_t struct_size;
 221
 222         const char *name;
 223         struct lttng_ust_enum_entry **entries;
 224         unsigned int nr_entries;
 225
 226         /* End of base ABI. Fields below should be used after checking struct_size. */
 227 };
 228
 229 /*
 230  * Event field description
 231  *
 232  * IMPORTANT: this structure is part of the ABI between the probe and
 233  * UST. Fields need to be only added at the end, never reordered, never
 234  * removed.
 235  *
 236  * The field @struct_size should be used to determine the size of the
 237  * structure. It should be queried before using additional fields added
 238  * at the end of the structure.
 239  */
 240
 241 struct lttng_ust_event_field {
 242         uint32_t struct_size;
 243
 244         const char *name;
 245         struct lttng_ust_type_common *type;
 246         unsigned int nowrite:1,         /* do not write into trace */
 247                 nofilter:1;             /* do not consider for filter */
 248
 249         /* End of base ABI. Fields below should be used after checking struct_size. */
 250 };
 251
 252
 253 /*
 254  * IMPORTANT: this structure is part of the ABI between the probe and
 255  * UST. Fields need to be only added at the end, never reordered, never
 256  * removed.
 257  *
 258  * The field @struct_size should be used to determine the size of the
 259  * structure. It should be queried before using additional fields added
 260  * at the end of the structure.
 261  */
 262 struct lttng_ust_event_desc {
 263         uint32_t struct_size;                   /* Size of this structure. */
 264
 265         const char *name;
 266         void (*probe_callback)(void);
 267         struct lttng_event_ctx *ctx;            /* context */
 268         struct lttng_ust_event_field **fields;  /* event payload */
 269         unsigned int nr_fields;
 270         const int **loglevel;
 271         const char *signature;                  /* Argument types/names received */
 272         const char **model_emf_uri;
 273
 274         /* End of base ABI. Fields below should be used after checking struct_size. */
 275 };
 276
 277 /*
 278  * IMPORTANT: this structure is part of the ABI between the probe and
 279  * UST. Fields need to be only added at the end, never reordered, never
 280  * removed.
 281  *
 282  * The field @struct_size should be used to determine the size of the
 283  * structure. It should be queried before using additional fields added
 284  * at the end of the structure.
 285  */
 286 struct lttng_ust_probe_desc {
 287         uint32_t struct_size;                   /* Size of this structure. */
 288
 289         const char *provider;
 290         struct lttng_ust_event_desc **event_desc;
 291         unsigned int nr_events;
 292         struct cds_list_head head;              /* chain registered probes */
 293         struct cds_list_head lazy_init_head;
 294         int lazy;                               /* lazy registration */
 295         uint32_t major;
 296         uint32_t minor;
 297
 298         /* End of base ABI. Fields below should be used after checking struct_size. */
 299 };
 300
 301 /* Data structures used by the tracer. */
 302
 303 /*
 304  * Bytecode interpreter return value masks.
 305  */
 306 enum lttng_bytecode_interpreter_ret {
 307         LTTNG_INTERPRETER_DISCARD = 0,
 308         LTTNG_INTERPRETER_RECORD_FLAG = (1ULL << 0),
 309         /* Other bits are kept for future use. */
 310 };
 311
 312 struct lttng_interpreter_output;
 313 struct lttng_ust_bytecode_runtime_private;
 314
 315 /*
 316  * IMPORTANT: this structure is part of the ABI between the probe and
 317  * UST. Fields need to be only added at the end, never reordered, never
 318  * removed.
 319  *
 320  * The field @struct_size should be used to determine the size of the
 321  * structure. It should be queried before using additional fields added
 322  * at the end of the structure.
 323  */
 324 struct lttng_ust_bytecode_runtime {
 325         uint32_t struct_size;                   /* Size of this structure. */
 326
 327         struct lttng_ust_bytecode_runtime_private *priv;
 328         /* Associated bytecode */
 329         union {
 330                 uint64_t (*filter)(void *interpreter_data,
 331                                 const char *interpreter_stack_data);
 332                 uint64_t (*capture)(void *interpreter_data,
 333                                 const char *interpreter_stack_data,
 334                                 struct lttng_interpreter_output *interpreter_output);
 335         } interpreter_funcs;
 336         struct cds_list_head node;      /* list of bytecode runtime in event */
 337
 338         /* End of base ABI. Fields below should be used after checking struct_size. */
 339 };
 340
 341 /*
 342  * lttng_event structure is referred to by the tracing fast path. It
 343  * must be kept small.
 344  *
 345  * IMPORTANT: this structure is part of the ABI between the probe and
 346  * UST. Fields need to be only added at the end, never reordered, never
 347  * removed.
 348  */
 349
 350 struct lttng_ust_ctx;
 351 struct lttng_ust_event_common_private;
 352
 353 enum lttng_ust_event_type {
 354         LTTNG_UST_EVENT_TYPE_RECORDER = 0,
 355         LTTNG_UST_EVENT_TYPE_NOTIFIER = 1,
 356 };
 357
 358 /*
 359  * IMPORTANT: this structure is part of the ABI between the probe and
 360  * UST. Fields need to be only added at the end, never reordered, never
 361  * removed.
 362  *
 363  * struct lttng_ust_event_common is the common ancestor of the various
 364  * public event actions. Inheritance is done by composition: The parent
 365  * has a pointer to its child, and the child has a pointer to its
 366  * parent. Inheritance of those public structures is done by composition
 367  * to ensure both parent and child structures can be extended.
 368  *
 369  * The field @struct_size should be used to determine the size of the
 370  * structure. It should be queried before using additional fields added
 371  * at the end of the structure.
 372  */
 373 struct lttng_ust_event_common {
 374         uint32_t struct_size;                           /* Size of this structure. */
 375
 376         struct lttng_ust_event_common_private *priv;    /* Private event interface */
 377
 378         enum lttng_ust_event_type type;
 379         void *child;                                    /* Pointer to child, for inheritance by aggregation. */
 380
 381         int enabled;
 382         int has_enablers_without_bytecode;
 383         /* list of struct lttng_ust_bytecode_runtime, sorted by seqnum */
 384         struct cds_list_head filter_bytecode_runtime_head;
 385
 386         /* End of base ABI. Fields below should be used after checking struct_size. */
 387 };
 388
 389 struct lttng_ust_event_recorder_private;
 390
 391 /*
 392  * IMPORTANT: this structure is part of the ABI between the probe and
 393  * UST. Fields need to be only added at the end, never reordered, never
 394  * removed.
 395  *
 396  * struct lttng_ust_event_recorder is the action for recording events
 397  * into a ring buffer. It inherits from struct lttng_ust_event_common
 398  * by composition to ensure both parent and child structure are
 399  * extensible.
 400  *
 401  * The field @struct_size should be used to determine the size of the
 402  * structure. It should be queried before using additional fields added
 403  * at the end of the structure.
 404  */
 405 struct lttng_ust_event_recorder {
 406         uint32_t struct_size;                           /* Size of this structure. */
 407
 408         struct lttng_ust_event_common *parent;          /* Inheritance by aggregation. */
 409         struct lttng_ust_event_recorder_private *priv;  /* Private event record interface */
 410
 411         unsigned int id;
 412         struct lttng_channel *chan;
 413         struct lttng_ust_ctx *ctx;
 414
 415         /* End of base ABI. Fields below should be used after checking struct_size. */
 416 };
 417
 418 struct lttng_ust_event_notifier_private;
 419
 420 /*
 421  * IMPORTANT: this structure is part of the ABI between the probe and
 422  * UST. Fields need to be only added at the end, never reordered, never
 423  * removed.
 424  *
 425  * struct lttng_ust_event_notifier is the action for sending
 426  * notifications. It inherits from struct lttng_ust_event_common
 427  * by composition to ensure both parent and child structure are
 428  * extensible.
 429  *
 430  * The field @struct_size should be used to determine the size of the
 431  * structure. It should be queried before using additional fields added
 432  * at the end of the structure.
 433  */
 434 struct lttng_ust_event_notifier {
 435         uint32_t struct_size;                           /* Size of this structure. */
 436
 437         struct lttng_ust_event_common *parent;          /* Inheritance by aggregation. */
 438         struct lttng_ust_event_notifier_private *priv;  /* Private event notifier interface */
 439
 440         void (*notification_send)(struct lttng_ust_event_notifier *event_notifier,
 441                 const char *stack_data);
 442         struct cds_list_head capture_bytecode_runtime_head;
 443
 444         /* End of base ABI. Fields below should be used after checking struct_size. */
 445 };
 446
 447 struct lttng_ust_lib_ring_buffer_channel;
 448 struct lttng_ust_shm_handle;
 449 struct lttng_ust_channel_ops_private;
 450
 451 /*
 452  * IMPORTANT: this structure is part of the ABI between the probe and
 453  * UST. Fields need to be only added at the end, never reordered, never
 454  * removed.
 455  *
 456  * The field @struct_size should be used to determine the size of the
 457  * structure. It should be queried before using additional fields added
 458  * at the end of the structure.
 459  */
 460 struct lttng_ust_channel_ops {
 461         uint32_t struct_size;
 462
 463         struct lttng_ust_channel_ops_private *priv;     /* Private channel ops interface */
 464
 465         int (*event_reserve)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
 466                              uint32_t event_id);
 467         void (*event_commit)(struct lttng_ust_lib_ring_buffer_ctx *ctx);
 468         void (*event_write)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
 469                         const void *src, size_t len);
 470         void (*event_strcpy)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
 471                         const char *src, size_t len);
 472
 473         /* End of base ABI. Fields below should be used after checking struct_size. */
 474 };
 475
 476 /*
 477  * IMPORTANT: this structure is part of the ABI between the probe and
 478  * UST. Fields need to be only added at the end, never reordered, never
 479  * removed.
 480  */
 481 struct lttng_channel {
 482         /*
 483          * The pointers located in this private data are NOT safe to be
 484          * dereferenced by the consumer. The only operations the
 485          * consumer process is designed to be allowed to do is to read
 486          * and perform subbuffer flush.
 487          */
 488         struct lttng_ust_lib_ring_buffer_channel *chan; /* Channel buffers */
 489         int enabled;
 490         struct lttng_ust_ctx *ctx;
 491         /* Event ID management */
 492         struct lttng_ust_session *session;
 493         int objd;                       /* Object associated to channel */
 494         struct cds_list_head node;      /* Channel list in session */
 495         struct lttng_ust_channel_ops *ops;
 496         int header_type;                /* 0: unset, 1: compact, 2: large */
 497         struct lttng_ust_shm_handle *handle;    /* shared-memory handle */
 498
 499         /* Channel ID */
 500         unsigned int id;
 501         enum lttng_ust_abi_chan_type type;
 502         unsigned char uuid[LTTNG_UST_UUID_LEN]; /* Trace session unique ID */
 503         int tstate:1;                   /* Transient enable state */
 504 };
 505
 506 /*
 507  * IMPORTANT: this structure is part of the ABI between the probe and
 508  * UST. Fields need to be only added at the end, never reordered, never
 509  * removed.
 510  *
 511  * The field @struct_size should be used to determine the size of the
 512  * structure. It should be queried before using additional fields added
 513  * at the end of the structure.
 514  */
 515 struct lttng_ust_stack_ctx {
 516         uint32_t struct_size;                   /* Size of this structure */
 517
 518         struct lttng_ust_event_recorder *event_recorder;
 519         struct lttng_ust_ctx *chan_ctx; /* RCU dereferenced. */
 520         struct lttng_ust_ctx *event_ctx;        /* RCU dereferenced. */
 521
 522         /* End of base ABI. Fields below should be used after checking struct_size. */
 523 };
 524
 525 struct lttng_ust_session_private;
 526
 527 /*
 528  * IMPORTANT: this structure is part of the ABI between the probe and
 529  * UST. Fields need to be only added at the end, never reordered, never
 530  * removed.
 531  *
 532  * The field @struct_size should be used to determine the size of the
 533  * structure. It should be queried before using additional fields added
 534  * at the end of the structure.
 535  */
 536 struct lttng_ust_session {
 537         uint32_t struct_size;                   /* Size of this structure */
 538
 539         struct lttng_ust_session_private *priv; /* Private session interface */
 540
 541         int active;                             /* Is trace session active ? */
 542
 543         /* End of base ABI. Fields below should be used after checking struct_size. */
 544 };
 545
 546 int lttng_ust_probe_register(struct lttng_ust_probe_desc *desc);
 547 void lttng_ust_probe_unregister(struct lttng_ust_probe_desc *desc);
 548
 549 /*
 550  * Applications that change their procname and need the new value to be
 551  * reflected in the procname event context have to call this function to clear
 552  * the internally cached value. This should not be called from a signal
 553  * handler.
 554  */
 555 void lttng_ust_context_procname_reset(void);
 556
 557 #ifdef __cplusplus
 558 }
 559 #endif
 560
 561 #endif /* _LTTNG_UST_EVENTS_H */