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