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 #define LTTNG_UST_PROVIDER_MAJOR        2
  36 #define LTTNG_UST_PROVIDER_MINOR        0
  37
  38 struct lttng_ust_channel_buffer;
  39 struct lttng_ust_session;
  40 struct lttng_ust_ring_buffer_ctx;
  41 struct lttng_ust_event_field;
  42 struct lttng_ust_registered_probe;
  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_UST_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_ust_rb_alignof(_type) * CHAR_BIT,    \
 127                 .signedness = lttng_ust_is_signed_type(_type),          \
 128                 .reverse_byte_order = _byte_order != LTTNG_UST_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_UST_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_ust_rb_alignof(_type) * CHAR_BIT,    \
 160                 .reverse_byte_order = LTTNG_UST_BYTE_ORDER != LTTNG_UST_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         const struct lttng_ust_enum_desc *desc; /* Enumeration mapping */
 174         const struct lttng_ust_type_common *container_type;
 175 };
 176
 177 /*
 178  * The alignment field in structure, array, and sequence types is a
 179  * minimum alignment requirement. The actual alignment of a type may be
 180  * larger than this explicit alignment value if its nested types have a
 181  * larger alignment.
 182  */
 183
 184 struct lttng_ust_type_array {
 185         struct lttng_ust_type_common parent;
 186         uint32_t struct_size;
 187         const struct lttng_ust_type_common *elem_type;
 188         unsigned int length;            /* Num. elems. */
 189         unsigned int alignment;         /* Minimum alignment for this type. */
 190         enum lttng_ust_string_encoding encoding;
 191 };
 192
 193 struct lttng_ust_type_sequence {
 194         struct lttng_ust_type_common parent;
 195         uint32_t struct_size;
 196         const char *length_name;        /* Length field name. */
 197         const struct lttng_ust_type_common *elem_type;
 198         unsigned int alignment;         /* Minimum alignment before elements. */
 199         enum lttng_ust_string_encoding encoding;
 200 };
 201
 202 struct lttng_ust_type_struct {
 203         struct lttng_ust_type_common parent;
 204         uint32_t struct_size;
 205         unsigned int nr_fields;
 206         const struct lttng_ust_event_field * const *fields;     /* Array of pointers to fields. */
 207         unsigned int alignment;                                 /* Minimum alignment for this type. */
 208 };
 209
 210 /*
 211  * Enumeration description
 212  *
 213  * IMPORTANT: this structure is part of the ABI between the probe and
 214  * UST. Fields need to be only added at the end, never reordered, never
 215  * removed.
 216  *
 217  * The field @struct_size should be used to determine the size of the
 218  * structure. It should be queried before using additional fields added
 219  * at the end of the structure.
 220  */
 221
 222 struct lttng_ust_enum_desc {
 223         uint32_t struct_size;
 224
 225         const char *name;
 226         const struct lttng_ust_enum_entry * const *entries;
 227         unsigned int nr_entries;
 228
 229         /* End of base ABI. Fields below should be used after checking struct_size. */
 230 };
 231
 232 /*
 233  * Event field description
 234  *
 235  * IMPORTANT: this structure is part of the ABI between the probe and
 236  * UST. Fields need to be only added at the end, never reordered, never
 237  * removed.
 238  *
 239  * The field @struct_size should be used to determine the size of the
 240  * structure. It should be queried before using additional fields added
 241  * at the end of the structure.
 242  */
 243
 244 struct lttng_ust_event_field {
 245         uint32_t struct_size;
 246
 247         const char *name;
 248         const struct lttng_ust_type_common *type;
 249         unsigned int nowrite:1,         /* do not write into trace */
 250                 nofilter:1;             /* do not consider for filter */
 251
 252         /* End of base ABI. Fields below should be used after checking struct_size. */
 253 };
 254
 255
 256 /*
 257  * IMPORTANT: this structure is part of the ABI between the probe and
 258  * UST. Fields need to be only added at the end, never reordered, never
 259  * removed.
 260  *
 261  * The field @struct_size should be used to determine the size of the
 262  * structure. It should be queried before using additional fields added
 263  * at the end of the structure.
 264  */
 265 struct lttng_ust_event_desc {
 266         uint32_t struct_size;                           /* Size of this structure. */
 267
 268         const char *event_name;
 269         const struct lttng_ust_probe_desc *probe_desc;
 270         void (*probe_callback)(void);
 271         const struct lttng_ust_event_field * const *fields;     /* event payload */
 272         unsigned int nr_fields;
 273         const int **loglevel;
 274         const char *signature;                          /* Argument types/names received */
 275         const char **model_emf_uri;
 276
 277         /* End of base ABI. Fields below should be used after checking struct_size. */
 278 };
 279
 280 /*
 281  * IMPORTANT: this structure is part of the ABI between the probe and
 282  * UST. Fields need to be only added at the end, never reordered, never
 283  * removed.
 284  *
 285  * The field @struct_size should be used to determine the size of the
 286  * structure. It should be queried before using additional fields added
 287  * at the end of the structure.
 288  */
 289 struct lttng_ust_probe_desc {
 290         uint32_t struct_size;                   /* Size of this structure. */
 291
 292         const char *provider_name;
 293         const struct lttng_ust_event_desc * const *event_desc;
 294         unsigned int nr_events;
 295         uint32_t major;
 296         uint32_t minor;
 297
 298         /* End of base ABI. Fields below should be used after checking struct_size. */
 299 };
 300
 301 /* Data structures used by the tracer. */
 302
 303 /*
 304  * IMPORTANT: this structure is part of the ABI between the probe and
 305  * UST. Fields need to be only added at the end, never reordered, never
 306  * removed.
 307  *
 308  * The field @struct_size should be used to determine the size of the
 309  * structure. It should be queried before using additional fields added
 310  * at the end of the structure.
 311  *
 312  * The probe_ctx is not const because it may be extended to add future
 313  * fields which could be modified by callbacks.
 314  */
 315 struct lttng_ust_probe_ctx {
 316         uint32_t struct_size;                   /* Size of this structure. */
 317
 318         void *ip;                               /* caller ip address */
 319
 320         /* End of base ABI. Fields below should be used after checking struct_size. */
 321 };
 322
 323 /*
 324  * lttng_event structure is referred to by the tracing fast path. It
 325  * must be kept small.
 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
 332 struct lttng_ust_event_common_private;
 333
 334 enum lttng_ust_event_type {
 335         LTTNG_UST_EVENT_TYPE_RECORDER = 0,
 336         LTTNG_UST_EVENT_TYPE_NOTIFIER = 1,
 337 };
 338
 339 /*
 340  * Result of the run_filter() callback.
 341  */
 342 enum lttng_ust_event_filter_result {
 343         LTTNG_UST_EVENT_FILTER_ACCEPT = 0,
 344         LTTNG_UST_EVENT_FILTER_REJECT = 1,
 345 };
 346
 347 /*
 348  * IMPORTANT: this structure is part of the ABI between the probe and
 349  * UST. Fields need to be only added at the end, never reordered, never
 350  * removed.
 351  *
 352  * struct lttng_ust_event_common is the common ancestor of the various
 353  * public event actions. Inheritance is done by composition: The parent
 354  * has a pointer to its child, and the child has a pointer to its
 355  * parent. Inheritance of those public structures is done by composition
 356  * to ensure both parent and child structures can be extended.
 357  *
 358  * The field @struct_size should be used to determine the size of the
 359  * structure. It should be queried before using additional fields added
 360  * at the end of the structure.
 361  */
 362 struct lttng_ust_event_common {
 363         uint32_t struct_size;                           /* Size of this structure. */
 364
 365         struct lttng_ust_event_common_private *priv;    /* Private event interface */
 366
 367         enum lttng_ust_event_type type;
 368         void *child;                                    /* Pointer to child, for inheritance by aggregation. */
 369
 370         int enabled;
 371         int eval_filter;                                /* Need to evaluate filters */
 372         int (*run_filter)(const struct lttng_ust_event_common *event,
 373                 const char *stack_data,
 374                 struct lttng_ust_probe_ctx *probe_ctx,
 375                 void *filter_ctx);
 376
 377         /* End of base ABI. Fields below should be used after checking struct_size. */
 378 };
 379
 380 struct lttng_ust_event_recorder_private;
 381
 382 /*
 383  * IMPORTANT: this structure is part of the ABI between the probe and
 384  * UST. Fields need to be only added at the end, never reordered, never
 385  * removed.
 386  *
 387  * struct lttng_ust_event_recorder is the action for recording events
 388  * into a ring buffer. It inherits from struct lttng_ust_event_common
 389  * by composition to ensure both parent and child structure are
 390  * extensible.
 391  *
 392  * The field @struct_size should be used to determine the size of the
 393  * structure. It should be queried before using additional fields added
 394  * at the end of the structure.
 395  */
 396 struct lttng_ust_event_recorder {
 397         uint32_t struct_size;                           /* Size of this structure. */
 398
 399         struct lttng_ust_event_common *parent;          /* Inheritance by aggregation. */
 400         struct lttng_ust_event_recorder_private *priv;  /* Private event record interface */
 401
 402         struct lttng_ust_channel_buffer *chan;
 403
 404         /* End of base ABI. Fields below should be used after checking struct_size. */
 405 };
 406
 407 /*
 408  * IMPORTANT: this structure is part of the ABI between the probe and
 409  * UST. Fields need to be only added at the end, never reordered, never
 410  * removed.
 411  *
 412  * The field @struct_size should be used to determine the size of the
 413  * structure. It should be queried before using additional fields added
 414  * at the end of the structure.
 415  */
 416 struct lttng_ust_notification_ctx {
 417         uint32_t struct_size;           /* Size of this structure. */
 418         int eval_capture;               /* Capture evaluation available. */
 419         /* End of base ABI. Fields below should be used after checking struct_size. */
 420 };
 421
 422 struct lttng_ust_event_notifier_private;
 423
 424 /*
 425  * IMPORTANT: this structure is part of the ABI between the probe and
 426  * UST. Fields need to be only added at the end, never reordered, never
 427  * removed.
 428  *
 429  * struct lttng_ust_event_notifier is the action for sending
 430  * notifications. It inherits from struct lttng_ust_event_common
 431  * by composition to ensure both parent and child structure are
 432  * extensible.
 433  *
 434  * The field @struct_size should be used to determine the size of the
 435  * structure. It should be queried before using additional fields added
 436  * at the end of the structure.
 437  */
 438 struct lttng_ust_event_notifier {
 439         uint32_t struct_size;                           /* Size of this structure. */
 440
 441         struct lttng_ust_event_common *parent;          /* Inheritance by aggregation. */
 442         struct lttng_ust_event_notifier_private *priv;  /* Private event notifier interface */
 443
 444         int eval_capture;                               /* Need to evaluate capture */
 445         void (*notification_send)(const struct lttng_ust_event_notifier *event_notifier,
 446                 const char *stack_data,
 447                 struct lttng_ust_probe_ctx *probe_ctx,
 448                 struct lttng_ust_notification_ctx *notif_ctx);
 449
 450         /* End of base ABI. Fields below should be used after checking struct_size. */
 451 };
 452
 453 struct lttng_ust_ring_buffer_channel;
 454 struct lttng_ust_channel_buffer_ops_private;
 455
 456 /*
 457  * IMPORTANT: this structure is part of the ABI between the probe and
 458  * UST. Fields need to be only added at the end, never reordered, never
 459  * removed.
 460  *
 461  * The field @struct_size should be used to determine the size of the
 462  * structure. It should be queried before using additional fields added
 463  * at the end of the structure.
 464  */
 465 struct lttng_ust_channel_buffer_ops {
 466         uint32_t struct_size;
 467
 468         struct lttng_ust_channel_buffer_ops_private *priv;      /* Private channel buffer ops interface */
 469
 470         int (*event_reserve)(struct lttng_ust_ring_buffer_ctx *ctx);
 471         void (*event_commit)(struct lttng_ust_ring_buffer_ctx *ctx);
 472         void (*event_write)(struct lttng_ust_ring_buffer_ctx *ctx,
 473                         const void *src, size_t len, size_t alignment);
 474         void (*event_strcpy)(struct lttng_ust_ring_buffer_ctx *ctx,
 475                         const char *src, size_t len);
 476         void (*event_pstrcpy_pad)(struct lttng_ust_ring_buffer_ctx *ctx,
 477                         const char *src, size_t len);
 478
 479         /* End of base ABI. Fields below should be used after checking struct_size. */
 480 };
 481
 482 enum lttng_ust_channel_type {
 483         LTTNG_UST_CHANNEL_TYPE_BUFFER = 0,
 484 };
 485
 486 struct lttng_ust_channel_common_private;
 487
 488 /*
 489  * IMPORTANT: this structure is part of the ABI between the probe and
 490  * UST. Fields need to be only added at the end, never reordered, never
 491  * removed.
 492  *
 493  * The field @struct_size should be used to determine the size of the
 494  * structure. It should be queried before using additional fields added
 495  * at the end of the structure.
 496  */
 497 struct lttng_ust_channel_common {
 498         uint32_t struct_size;                           /* Size of this structure. */
 499
 500         struct lttng_ust_channel_common_private *priv;  /* Private channel interface */
 501
 502         enum lttng_ust_channel_type type;
 503         void *child;                                    /* Pointer to child, for inheritance by aggregation. */
 504
 505         int enabled;
 506         struct lttng_ust_session *session;
 507
 508         /* End of base ABI. Fields below should be used after checking struct_size. */
 509 };
 510
 511 struct lttng_ust_channel_buffer_private;
 512
 513 /*
 514  * IMPORTANT: this structure is part of the ABI between the probe and
 515  * UST. Fields need to be only added at the end, never reordered, never
 516  * removed.
 517  *
 518  * The field @struct_size should be used to determine the size of the
 519  * structure. It should be queried before using additional fields added
 520  * at the end of the structure.
 521  */
 522 struct lttng_ust_channel_buffer {
 523         uint32_t struct_size;                           /* Size of this structure. */
 524
 525         struct lttng_ust_channel_common *parent;        /* Inheritance by aggregation. */
 526         struct lttng_ust_channel_buffer_private *priv;  /* Private channel buffer interface */
 527
 528         struct lttng_ust_channel_buffer_ops *ops;
 529
 530         /* End of base ABI. Fields below should be used after checking struct_size. */
 531 };
 532
 533 /*
 534  * IMPORTANT: this structure is part of the ABI between the probe and
 535  * UST. Fields need to be only added at the end, never reordered, never
 536  * removed.
 537  *
 538  * The field @struct_size should be used to determine the size of the
 539  * structure. It should be queried before using additional fields added
 540  * at the end of the structure.
 541  */
 542 struct lttng_ust_stack_ctx {
 543         uint32_t struct_size;                   /* Size of this structure */
 544
 545         struct lttng_ust_event_recorder *event_recorder;
 546
 547         /* End of base ABI. Fields below should be used after checking struct_size. */
 548 };
 549
 550 struct lttng_ust_session_private;
 551
 552 /*
 553  * IMPORTANT: this structure is part of the ABI between the probe and
 554  * UST. Fields need to be only added at the end, never reordered, never
 555  * removed.
 556  *
 557  * The field @struct_size should be used to determine the size of the
 558  * structure. It should be queried before using additional fields added
 559  * at the end of the structure.
 560  */
 561 struct lttng_ust_session {
 562         uint32_t struct_size;                   /* Size of this structure */
 563
 564         struct lttng_ust_session_private *priv; /* Private session interface */
 565
 566         int active;                             /* Is trace session active ? */
 567
 568         /* End of base ABI. Fields below should be used after checking struct_size. */
 569 };
 570
 571 /*
 572  * On successful registration of a probe, a pointer to an opaque
 573  * structure is returned. This pointer should be passed to
 574  * lttng_ust_probe_unregister for unregistration.
 575  * lttng_ust_probe_register returns NULL on error.
 576  */
 577 struct lttng_ust_registered_probe *lttng_ust_probe_register(const struct lttng_ust_probe_desc *desc);
 578
 579 void lttng_ust_probe_unregister(struct lttng_ust_registered_probe *reg_probe);
 580
 581 /*
 582  * Applications that change their procname and need the new value to be
 583  * reflected in the procname event context have to call this function to clear
 584  * the internally cached value. This should not be called from a signal
 585  * handler.
 586  */
 587 void lttng_ust_context_procname_reset(void);
 588
 589 #ifdef __cplusplus
 590 }
 591 #endif
 592
 593 #endif /* _LTTNG_UST_EVENTS_H */