include/lttng/ust-events.h

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