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 <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
 234         /* End of base ABI. Fields below should be used after checking struct_size. */
 235 };
 236
 237 /*
 238  * Event field description
 239  *
 240  * IMPORTANT: this structure is part of the ABI between the probe and
 241  * UST. Fields need to be only added at the end, never reordered, never
 242  * removed.
 243  *
 244  * The field @struct_size should be used to determine the size of the
 245  * structure. It should be queried before using additional fields added
 246  * at the end of the structure.
 247  */
 248
 249 struct lttng_ust_event_field {
 250         uint32_t struct_size;
 251
 252         const char *name;
 253         const struct lttng_ust_type_common *type;
 254         unsigned int nowrite:1,         /* do not write into trace */
 255                 nofilter:1;             /* do not consider for filter */
 256
 257         /* End of base ABI. Fields below should be used after checking struct_size. */
 258 };
 259
 260 /*
 261  * Tracepoint class description
 262  *
 263  * IMPORTANT: this structure is part of the ABI between the probe and
 264  * UST. Fields need to be only added at the end, never reordered, never
 265  * removed.
 266  *
 267  * The field @struct_size should be used to determine the size of the
 268  * structure. It should be queried before using additional fields added
 269  * at the end of the structure.
 270  */
 271
 272 struct lttng_ust_tracepoint_class {
 273         uint32_t struct_size;
 274
 275         const struct lttng_ust_event_field * const *fields;
 276         size_t nr_fields;
 277         void (*probe_callback)(void);
 278         const char *signature;                          /* Argument types/names received */
 279
 280         /* End of base ABI. Fields below should be used after checking struct_size. */
 281 };
 282
 283 /*
 284  * IMPORTANT: this structure is part of the ABI between the probe and
 285  * UST. Fields need to be only added at the end, never reordered, never
 286  * removed.
 287  *
 288  * The field @struct_size should be used to determine the size of the
 289  * structure. It should be queried before using additional fields added
 290  * at the end of the structure.
 291  */
 292 struct lttng_ust_event_desc {
 293         uint32_t struct_size;                           /* Size of this structure. */
 294
 295         const char *event_name;
 296         const struct lttng_ust_probe_desc *probe_desc;
 297         const struct lttng_ust_tracepoint_class *tp_class;
 298         const int **loglevel;
 299         const char **model_emf_uri;
 300
 301         /* End of base ABI. Fields below should be used after checking struct_size. */
 302 };
 303
 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  * The field @struct_size should be used to determine the size of the
 310  * structure. It should be queried before using additional fields added
 311  * at the end of the structure.
 312  */
 313 struct lttng_ust_probe_desc {
 314         uint32_t struct_size;                   /* Size of this structure. */
 315
 316         const char *provider_name;
 317         const struct lttng_ust_event_desc * const *event_desc;
 318         unsigned int nr_events;
 319         uint32_t major;
 320         uint32_t minor;
 321
 322         /* End of base ABI. Fields below should be used after checking struct_size. */
 323 };
 324
 325 /* Data structures used by the tracer. */
 326
 327 /*
 328  * IMPORTANT: this structure is part of the ABI between the probe and
 329  * UST. Fields need to be only added at the end, never reordered, never
 330  * removed.
 331  *
 332  * The field @struct_size should be used to determine the size of the
 333  * structure. It should be queried before using additional fields added
 334  * at the end of the structure.
 335  *
 336  * The probe_ctx is not const because it may be extended to add future
 337  * fields which could be modified by callbacks.
 338  */
 339 struct lttng_ust_probe_ctx {
 340         uint32_t struct_size;                   /* Size of this structure. */
 341
 342         void *ip;                               /* caller ip address */
 343
 344         /* End of base ABI. Fields below should be used after checking struct_size. */
 345 };
 346
 347 /*
 348  * lttng_event structure is referred to by the tracing fast path. It
 349  * must be kept small.
 350  *
 351  * IMPORTANT: this structure is part of the ABI between the probe and
 352  * UST. Fields need to be only added at the end, never reordered, never
 353  * removed.
 354  */
 355
 356 struct lttng_ust_event_common_private;
 357
 358 enum lttng_ust_event_type {
 359         LTTNG_UST_EVENT_TYPE_RECORDER = 0,
 360         LTTNG_UST_EVENT_TYPE_NOTIFIER = 1,
 361 };
 362
 363 /*
 364  * Result of the run_filter() callback.
 365  */
 366 enum lttng_ust_event_filter_result {
 367         LTTNG_UST_EVENT_FILTER_ACCEPT = 0,
 368         LTTNG_UST_EVENT_FILTER_REJECT = 1,
 369 };
 370
 371 /*
 372  * IMPORTANT: this structure is part of the ABI between the probe and
 373  * UST. Fields need to be only added at the end, never reordered, never
 374  * removed.
 375  *
 376  * struct lttng_ust_event_common is the common ancestor of the various
 377  * public event actions. Inheritance is done by composition: The parent
 378  * has a pointer to its child, and the child has a pointer to its
 379  * parent. Inheritance of those public structures is done by composition
 380  * to ensure both parent and child structures can be extended.
 381  *
 382  * The field @struct_size should be used to determine the size of the
 383  * structure. It should be queried before using additional fields added
 384  * at the end of the structure.
 385  */
 386 struct lttng_ust_event_common {
 387         uint32_t struct_size;                           /* Size of this structure. */
 388
 389         struct lttng_ust_event_common_private *priv;    /* Private event interface */
 390
 391         enum lttng_ust_event_type type;
 392         void *child;                                    /* Pointer to child, for inheritance by aggregation. */
 393
 394         int enabled;
 395         int eval_filter;                                /* Need to evaluate filters */
 396         int (*run_filter)(const struct lttng_ust_event_common *event,
 397                 const char *stack_data,
 398                 struct lttng_ust_probe_ctx *probe_ctx,
 399                 void *filter_ctx);
 400
 401         /* End of base ABI. Fields below should be used after checking struct_size. */
 402 };
 403
 404 struct lttng_ust_event_recorder_private;
 405
 406 /*
 407  * IMPORTANT: this structure is part of the ABI between the probe and
 408  * UST. Fields need to be only added at the end, never reordered, never
 409  * removed.
 410  *
 411  * struct lttng_ust_event_recorder is the action for recording events
 412  * into a ring buffer. It inherits from struct lttng_ust_event_common
 413  * by composition to ensure both parent and child structure are
 414  * extensible.
 415  *
 416  * The field @struct_size should be used to determine the size of the
 417  * structure. It should be queried before using additional fields added
 418  * at the end of the structure.
 419  */
 420 struct lttng_ust_event_recorder {
 421         uint32_t struct_size;                           /* Size of this structure. */
 422
 423         struct lttng_ust_event_common *parent;          /* Inheritance by aggregation. */
 424         struct lttng_ust_event_recorder_private *priv;  /* Private event record interface */
 425
 426         struct lttng_ust_channel_buffer *chan;
 427
 428         /* End of base ABI. Fields below should be used after checking struct_size. */
 429 };
 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  * The field @struct_size should be used to determine the size of the
 437  * structure. It should be queried before using additional fields added
 438  * at the end of the structure.
 439  */
 440 struct lttng_ust_notification_ctx {
 441         uint32_t struct_size;           /* Size of this structure. */
 442         int eval_capture;               /* Capture evaluation available. */
 443         /* End of base ABI. Fields below should be used after checking struct_size. */
 444 };
 445
 446 struct lttng_ust_event_notifier_private;
 447
 448 /*
 449  * IMPORTANT: this structure is part of the ABI between the probe and
 450  * UST. Fields need to be only added at the end, never reordered, never
 451  * removed.
 452  *
 453  * struct lttng_ust_event_notifier is the action for sending
 454  * notifications. It inherits from struct lttng_ust_event_common
 455  * by composition to ensure both parent and child structure are
 456  * extensible.
 457  *
 458  * The field @struct_size should be used to determine the size of the
 459  * structure. It should be queried before using additional fields added
 460  * at the end of the structure.
 461  */
 462 struct lttng_ust_event_notifier {
 463         uint32_t struct_size;                           /* Size of this structure. */
 464
 465         struct lttng_ust_event_common *parent;          /* Inheritance by aggregation. */
 466         struct lttng_ust_event_notifier_private *priv;  /* Private event notifier interface */
 467
 468         int eval_capture;                               /* Need to evaluate capture */
 469         void (*notification_send)(const struct lttng_ust_event_notifier *event_notifier,
 470                 const char *stack_data,
 471                 struct lttng_ust_probe_ctx *probe_ctx,
 472                 struct lttng_ust_notification_ctx *notif_ctx);
 473
 474         /* End of base ABI. Fields below should be used after checking struct_size. */
 475 };
 476
 477 struct lttng_ust_ring_buffer_channel;
 478 struct lttng_ust_channel_buffer_ops_private;
 479
 480 /*
 481  * IMPORTANT: this structure is part of the ABI between the probe and
 482  * UST. Fields need to be only added at the end, never reordered, never
 483  * removed.
 484  *
 485  * The field @struct_size should be used to determine the size of the
 486  * structure. It should be queried before using additional fields added
 487  * at the end of the structure.
 488  */
 489 struct lttng_ust_channel_buffer_ops {
 490         uint32_t struct_size;
 491
 492         struct lttng_ust_channel_buffer_ops_private *priv;      /* Private channel buffer ops interface */
 493
 494         int (*event_reserve)(struct lttng_ust_ring_buffer_ctx *ctx);
 495         void (*event_commit)(struct lttng_ust_ring_buffer_ctx *ctx);
 496         void (*event_write)(struct lttng_ust_ring_buffer_ctx *ctx,
 497                         const void *src, size_t len, size_t alignment);
 498         void (*event_strcpy)(struct lttng_ust_ring_buffer_ctx *ctx,
 499                         const char *src, size_t len);
 500         void (*event_pstrcpy_pad)(struct lttng_ust_ring_buffer_ctx *ctx,
 501                         const char *src, size_t len);
 502
 503         /* End of base ABI. Fields below should be used after checking struct_size. */
 504 };
 505
 506 enum lttng_ust_channel_type {
 507         LTTNG_UST_CHANNEL_TYPE_BUFFER = 0,
 508 };
 509
 510 struct lttng_ust_channel_common_private;
 511
 512 /*
 513  * IMPORTANT: this structure is part of the ABI between the probe and
 514  * UST. Fields need to be only added at the end, never reordered, never
 515  * removed.
 516  *
 517  * The field @struct_size should be used to determine the size of the
 518  * structure. It should be queried before using additional fields added
 519  * at the end of the structure.
 520  */
 521 struct lttng_ust_channel_common {
 522         uint32_t struct_size;                           /* Size of this structure. */
 523
 524         struct lttng_ust_channel_common_private *priv;  /* Private channel interface */
 525
 526         enum lttng_ust_channel_type type;
 527         void *child;                                    /* Pointer to child, for inheritance by aggregation. */
 528
 529         int enabled;
 530         struct lttng_ust_session *session;
 531
 532         /* End of base ABI. Fields below should be used after checking struct_size. */
 533 };
 534
 535 struct lttng_ust_channel_buffer_private;
 536
 537 /*
 538  * IMPORTANT: this structure is part of the ABI between the probe and
 539  * UST. Fields need to be only added at the end, never reordered, never
 540  * removed.
 541  *
 542  * The field @struct_size should be used to determine the size of the
 543  * structure. It should be queried before using additional fields added
 544  * at the end of the structure.
 545  */
 546 struct lttng_ust_channel_buffer {
 547         uint32_t struct_size;                           /* Size of this structure. */
 548
 549         struct lttng_ust_channel_common *parent;        /* Inheritance by aggregation. */
 550         struct lttng_ust_channel_buffer_private *priv;  /* Private channel buffer interface */
 551
 552         struct lttng_ust_channel_buffer_ops *ops;
 553
 554         /* End of base ABI. Fields below should be used after checking struct_size. */
 555 };
 556
 557 /*
 558  * IMPORTANT: this structure is part of the ABI between the probe and
 559  * UST. Fields need to be only added at the end, never reordered, never
 560  * removed.
 561  *
 562  * The field @struct_size should be used to determine the size of the
 563  * structure. It should be queried before using additional fields added
 564  * at the end of the structure.
 565  */
 566 struct lttng_ust_stack_ctx {
 567         uint32_t struct_size;                   /* Size of this structure */
 568
 569         struct lttng_ust_event_recorder *event_recorder;
 570
 571         /* End of base ABI. Fields below should be used after checking struct_size. */
 572 };
 573
 574 struct lttng_ust_session_private;
 575
 576 /*
 577  * IMPORTANT: this structure is part of the ABI between the probe and
 578  * UST. Fields need to be only added at the end, never reordered, never
 579  * removed.
 580  *
 581  * The field @struct_size should be used to determine the size of the
 582  * structure. It should be queried before using additional fields added
 583  * at the end of the structure.
 584  */
 585 struct lttng_ust_session {
 586         uint32_t struct_size;                   /* Size of this structure */
 587
 588         struct lttng_ust_session_private *priv; /* Private session interface */
 589
 590         int active;                             /* Is trace session active ? */
 591
 592         /* End of base ABI. Fields below should be used after checking struct_size. */
 593 };
 594
 595 /*
 596  * On successful registration of a probe, a pointer to an opaque
 597  * structure is returned. This pointer should be passed to
 598  * lttng_ust_probe_unregister for unregistration.
 599  * lttng_ust_probe_register returns NULL on error.
 600  */
 601 struct lttng_ust_registered_probe *lttng_ust_probe_register(const struct lttng_ust_probe_desc *desc);
 602
 603 void lttng_ust_probe_unregister(struct lttng_ust_registered_probe *reg_probe);
 604
 605 /*
 606  * Applications that change their procname and need the new value to be
 607  * reflected in the procname event context have to call this function to clear
 608  * the internally cached value. This should not be called from a signal
 609  * handler.
 610  */
 611 void lttng_ust_context_procname_reset(void);
 612
 613 #ifdef __cplusplus
 614 }
 615 #endif
 616
 617 #endif /* _LTTNG_UST_EVENTS_H */