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_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_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         unsigned int id;
 381         struct lttng_ust_channel_buffer *chan;
 382
 383         /* End of base ABI. Fields below should be used after checking struct_size. */
 384 };
 385
 386 /*
 387  * IMPORTANT: this structure is part of the ABI between the probe and
 388  * UST. Fields need to be only added at the end, never reordered, never
 389  * removed.
 390  *
 391  * The field @struct_size should be used to determine the size of the
 392  * structure. It should be queried before using additional fields added
 393  * at the end of the structure.
 394  */
 395 struct lttng_ust_notification_ctx {
 396         uint32_t struct_size;           /* Size of this structure. */
 397         int eval_capture;               /* Capture evaluation available. */
 398
 399         /* End of base ABI. Fields below should be used after checking struct_size. */
 400 };
 401
 402 struct lttng_ust_event_notifier_private;
 403
 404 /*
 405  * IMPORTANT: this structure is part of the ABI between the probe and
 406  * UST. Fields need to be only added at the end, never reordered, never
 407  * removed.
 408  *
 409  * struct lttng_ust_event_notifier is the action for sending
 410  * notifications. It inherits from struct lttng_ust_event_common
 411  * by composition to ensure both parent and child structure are
 412  * extensible.
 413  *
 414  * The field @struct_size should be used to determine the size of the
 415  * structure. It should be queried before using additional fields added
 416  * at the end of the structure.
 417  */
 418 struct lttng_ust_event_notifier {
 419         uint32_t struct_size;                           /* Size of this structure. */
 420
 421         struct lttng_ust_event_common *parent;          /* Inheritance by aggregation. */
 422         struct lttng_ust_event_notifier_private *priv;  /* Private event notifier interface */
 423
 424         int eval_capture;                               /* Need to evaluate capture */
 425         void (*notification_send)(struct lttng_ust_event_notifier *event_notifier,
 426                 const char *stack_data,
 427                 struct lttng_ust_notification_ctx *notif_ctx);
 428
 429         /* End of base ABI. Fields below should be used after checking struct_size. */
 430 };
 431
 432 struct lttng_ust_lib_ring_buffer_channel;
 433 struct lttng_ust_channel_buffer_ops_private;
 434
 435 /*
 436  * IMPORTANT: this structure is part of the ABI between the probe and
 437  * UST. Fields need to be only added at the end, never reordered, never
 438  * removed.
 439  *
 440  * The field @struct_size should be used to determine the size of the
 441  * structure. It should be queried before using additional fields added
 442  * at the end of the structure.
 443  */
 444 struct lttng_ust_channel_buffer_ops {
 445         uint32_t struct_size;
 446
 447         struct lttng_ust_channel_buffer_ops_private *priv;      /* Private channel buffer ops interface */
 448
 449         int (*event_reserve)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
 450                              uint32_t event_id);
 451         void (*event_commit)(struct lttng_ust_lib_ring_buffer_ctx *ctx);
 452         void (*event_write)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
 453                         const void *src, size_t len);
 454         void (*event_strcpy)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
 455                         const char *src, size_t len);
 456         void (*event_pstrcpy_pad)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
 457                         const char *src, size_t len);
 458
 459         /* End of base ABI. Fields below should be used after checking struct_size. */
 460 };
 461
 462 enum lttng_ust_channel_type {
 463         LTTNG_UST_CHANNEL_TYPE_BUFFER = 0,
 464 };
 465
 466 struct lttng_ust_channel_common_private;
 467
 468 /*
 469  * IMPORTANT: this structure is part of the ABI between the probe and
 470  * UST. Fields need to be only added at the end, never reordered, never
 471  * removed.
 472  *
 473  * The field @struct_size should be used to determine the size of the
 474  * structure. It should be queried before using additional fields added
 475  * at the end of the structure.
 476  */
 477 struct lttng_ust_channel_common {
 478         uint32_t struct_size;                           /* Size of this structure. */
 479
 480         struct lttng_ust_channel_common_private *priv;  /* Private channel interface */
 481
 482         enum lttng_ust_channel_type type;
 483         void *child;                                    /* Pointer to child, for inheritance by aggregation. */
 484
 485         int enabled;
 486         struct lttng_ust_session *session;
 487
 488         /* End of base ABI. Fields below should be used after checking struct_size. */
 489 };
 490
 491 struct lttng_ust_channel_buffer_private;
 492
 493 /*
 494  * IMPORTANT: this structure is part of the ABI between the probe and
 495  * UST. Fields need to be only added at the end, never reordered, never
 496  * removed.
 497  *
 498  * The field @struct_size should be used to determine the size of the
 499  * structure. It should be queried before using additional fields added
 500  * at the end of the structure.
 501  */
 502 struct lttng_ust_channel_buffer {
 503         uint32_t struct_size;                           /* Size of this structure. */
 504
 505         struct lttng_ust_channel_common *parent;        /* Inheritance by aggregation. */
 506         struct lttng_ust_channel_buffer_private *priv;  /* Private channel buffer interface */
 507
 508         struct lttng_ust_channel_buffer_ops *ops;
 509
 510         /* End of base ABI. Fields below should be used after checking struct_size. */
 511 };
 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_stack_ctx {
 523         uint32_t struct_size;                   /* Size of this structure */
 524
 525         struct lttng_ust_event_recorder *event_recorder;
 526
 527         /* End of base ABI. Fields below should be used after checking struct_size. */
 528 };
 529
 530 struct lttng_ust_session_private;
 531
 532 /*
 533  * IMPORTANT: this structure is part of the ABI between the probe and
 534  * UST. Fields need to be only added at the end, never reordered, never
 535  * removed.
 536  *
 537  * The field @struct_size should be used to determine the size of the
 538  * structure. It should be queried before using additional fields added
 539  * at the end of the structure.
 540  */
 541 struct lttng_ust_session {
 542         uint32_t struct_size;                   /* Size of this structure */
 543
 544         struct lttng_ust_session_private *priv; /* Private session interface */
 545
 546         int active;                             /* Is trace session active ? */
 547
 548         /* End of base ABI. Fields below should be used after checking struct_size. */
 549 };
 550
 551 int lttng_ust_probe_register(struct lttng_ust_probe_desc *desc);
 552 void lttng_ust_probe_unregister(struct lttng_ust_probe_desc *desc);
 553
 554 /*
 555  * Applications that change their procname and need the new value to be
 556  * reflected in the procname event context have to call this function to clear
 557  * the internally cached value. This should not be called from a signal
 558  * handler.
 559  */
 560 void lttng_ust_context_procname_reset(void);
 561
 562 #ifdef __cplusplus
 563 }
 564 #endif
 565
 566 #endif /* _LTTNG_UST_EVENTS_H */