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