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
  24 #ifndef LTTNG_PACKED
  25 #error "LTTNG_PACKED should be defined"
  26 #endif
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 #define LTTNG_UST_UUID_LEN              16
  33
  34 /*
  35  * Tracepoint provider version. Compatibility based on the major number.
  36  * Older tracepoint providers can always register to newer lttng-ust
  37  * library, but the opposite is rejected: a newer tracepoint provider is
  38  * rejected by an older lttng-ust library.
  39  */
  40 #define LTTNG_UST_PROVIDER_MAJOR        2
  41 #define LTTNG_UST_PROVIDER_MINOR        0
  42
  43 struct lttng_channel;
  44 struct lttng_session;
  45 struct lttng_ust_lib_ring_buffer_ctx;
  46 struct lttng_event_field;
  47 struct lttng_event_notifier_group;
  48
  49 /*
  50  * Data structures used by tracepoint event declarations, and by the
  51  * tracer. Those structures have padding for future extension.
  52  */
  53
  54 /* Type description */
  55
  56 /* Update the astract_types name table in lttng-types.c along with this enum */
  57 enum lttng_abstract_types {
  58         atype_integer,
  59         atype_string,
  60         atype_float,
  61         atype_dynamic,
  62         atype_enum_nestable,
  63         atype_array_nestable,
  64         atype_sequence_nestable,
  65         atype_struct_nestable,
  66         NR_ABSTRACT_TYPES,
  67 };
  68
  69 /* Update the string_encodings name table in lttng-types.c along with this enum */
  70 enum lttng_string_encodings {
  71         lttng_encode_none = 0,
  72         lttng_encode_UTF8 = 1,
  73         lttng_encode_ASCII = 2,
  74         NR_STRING_ENCODINGS,
  75 };
  76
  77 struct lttng_enum_value {
  78         unsigned long long value;
  79         unsigned int signedness:1;
  80 };
  81
  82 enum lttng_enum_entry_options {
  83         LTTNG_ENUM_ENTRY_OPTION_IS_AUTO = 1U << 0,
  84 };
  85
  86 #define LTTNG_UST_ENUM_ENTRY_PADDING    16
  87 struct lttng_enum_entry {
  88         struct lttng_enum_value start, end; /* start and end are inclusive */
  89         const char *string;
  90         union {
  91                 struct {
  92                         unsigned int options;
  93                 } LTTNG_PACKED extra;
  94                 char padding[LTTNG_UST_ENUM_ENTRY_PADDING];
  95         } u;
  96 };
  97
  98 #define __type_integer(_type, _byte_order, _base, _encoding)    \
  99         {                                                       \
 100           .atype = atype_integer,                               \
 101           .u =                                                  \
 102                 {                                               \
 103                   .integer =                                    \
 104                         {                                       \
 105                           .size = sizeof(_type) * CHAR_BIT,     \
 106                           .alignment = lttng_alignof(_type) * CHAR_BIT, \
 107                           .signedness = lttng_is_signed_type(_type), \
 108                           .reverse_byte_order = _byte_order != BYTE_ORDER, \
 109                           .base = _base,                        \
 110                           .encoding = lttng_encode_##_encoding, \
 111                         }                                       \
 112                 },                                              \
 113         }                                                       \
 114
 115 #define LTTNG_UST_INTEGER_TYPE_PADDING  24
 116 struct lttng_integer_type {
 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         enum lttng_string_encodings encoding;
 123         char padding[LTTNG_UST_INTEGER_TYPE_PADDING];
 124 };
 125
 126 /*
 127  * Only float and double are supported. long double is not supported at
 128  * the moment.
 129  */
 130 #define _float_mant_dig(_type)                                          \
 131         (sizeof(_type) == sizeof(float) ? FLT_MANT_DIG                  \
 132                 : (sizeof(_type) == sizeof(double) ? DBL_MANT_DIG       \
 133                 : 0))
 134
 135 #define __type_float(_type)                                     \
 136         {                                                       \
 137           .atype = atype_float,                                 \
 138           .u =                                                  \
 139                 {                                               \
 140                   ._float =                                     \
 141                         {                                       \
 142                           .exp_dig = sizeof(_type) * CHAR_BIT   \
 143                                           - _float_mant_dig(_type), \
 144                           .mant_dig = _float_mant_dig(_type),   \
 145                           .alignment = lttng_alignof(_type) * CHAR_BIT, \
 146                           .reverse_byte_order = BYTE_ORDER != FLOAT_WORD_ORDER, \
 147                         }                                       \
 148                 }                                               \
 149         }                                                       \
 150
 151 #define LTTNG_UST_FLOAT_TYPE_PADDING    24
 152 struct lttng_float_type {
 153         unsigned int exp_dig;           /* exponent digits, in bits */
 154         unsigned int mant_dig;          /* mantissa digits, in bits */
 155         unsigned short alignment;       /* in bits */
 156         unsigned int reverse_byte_order:1;
 157         char padding[LTTNG_UST_FLOAT_TYPE_PADDING];
 158 };
 159
 160 #define LTTNG_UST_TYPE_PADDING  128
 161 struct lttng_type {
 162         enum lttng_abstract_types atype;
 163         union {
 164                 /* provider ABI 2.0 */
 165                 struct lttng_integer_type integer;
 166                 struct lttng_float_type _float;
 167                 struct {
 168                         enum lttng_string_encodings encoding;
 169                 } string;
 170                 struct {
 171                         const struct lttng_enum_desc *desc;     /* Enumeration mapping */
 172                         struct lttng_type *container_type;
 173                 } enum_nestable;
 174                 struct {
 175                         const struct lttng_type *elem_type;
 176                         unsigned int length;                    /* Num. elems. */
 177                         unsigned int alignment;
 178                 } array_nestable;
 179                 struct {
 180                         const char *length_name;                /* Length field name. */
 181                         const struct lttng_type *elem_type;
 182                         unsigned int alignment;                 /* Alignment before elements. */
 183                 } sequence_nestable;
 184                 struct {
 185                         unsigned int nr_fields;
 186                         const struct lttng_event_field *fields; /* Array of fields. */
 187                         unsigned int alignment;
 188                 } struct_nestable;
 189
 190                 char padding[LTTNG_UST_TYPE_PADDING];
 191         } u;
 192 };
 193
 194 #define LTTNG_UST_ENUM_TYPE_PADDING     24
 195 struct lttng_enum_desc {
 196         const char *name;
 197         const struct lttng_enum_entry *entries;
 198         unsigned int nr_entries;
 199         char padding[LTTNG_UST_ENUM_TYPE_PADDING];
 200 };
 201
 202 /*
 203  * Event field description
 204  *
 205  * IMPORTANT: this structure is part of the ABI between the probe and
 206  * UST. Fields need to be only added at the end, never reordered, never
 207  * removed.
 208  */
 209
 210 #define LTTNG_UST_EVENT_FIELD_PADDING   28
 211 struct lttng_event_field {
 212         const char *name;
 213         struct lttng_type type;
 214         unsigned int nowrite;   /* do not write into trace */
 215         union {
 216                 struct {
 217                         unsigned int nofilter:1;        /* do not consider for filter */
 218                 } ext;
 219                 char padding[LTTNG_UST_EVENT_FIELD_PADDING];
 220         } u;
 221 };
 222
 223 enum lttng_ust_dynamic_type {
 224         LTTNG_UST_DYNAMIC_TYPE_NONE,
 225         LTTNG_UST_DYNAMIC_TYPE_S8,
 226         LTTNG_UST_DYNAMIC_TYPE_S16,
 227         LTTNG_UST_DYNAMIC_TYPE_S32,
 228         LTTNG_UST_DYNAMIC_TYPE_S64,
 229         LTTNG_UST_DYNAMIC_TYPE_U8,
 230         LTTNG_UST_DYNAMIC_TYPE_U16,
 231         LTTNG_UST_DYNAMIC_TYPE_U32,
 232         LTTNG_UST_DYNAMIC_TYPE_U64,
 233         LTTNG_UST_DYNAMIC_TYPE_FLOAT,
 234         LTTNG_UST_DYNAMIC_TYPE_DOUBLE,
 235         LTTNG_UST_DYNAMIC_TYPE_STRING,
 236         _NR_LTTNG_UST_DYNAMIC_TYPES,
 237 };
 238
 239 struct lttng_ctx_value {
 240         enum lttng_ust_dynamic_type sel;
 241         union {
 242                 int64_t s64;
 243                 uint64_t u64;
 244                 const char *str;
 245                 double d;
 246         } u;
 247 };
 248
 249 struct lttng_perf_counter_field;
 250
 251 #define LTTNG_UST_CTX_FIELD_PADDING     40
 252 struct lttng_ctx_field {
 253         struct lttng_event_field event_field;
 254         size_t (*get_size)(struct lttng_ctx_field *field, size_t offset);
 255         void (*record)(struct lttng_ctx_field *field,
 256                        struct lttng_ust_lib_ring_buffer_ctx *ctx,
 257                        struct lttng_channel *chan);
 258         void (*get_value)(struct lttng_ctx_field *field,
 259                          struct lttng_ctx_value *value);
 260         union {
 261                 struct lttng_perf_counter_field *perf_counter;
 262                 char padding[LTTNG_UST_CTX_FIELD_PADDING];
 263         } u;
 264         void (*destroy)(struct lttng_ctx_field *field);
 265         char *field_name;       /* Has ownership, dynamically allocated. */
 266 };
 267
 268 #define LTTNG_UST_CTX_PADDING   20
 269 struct lttng_ctx {
 270         struct lttng_ctx_field *fields;
 271         unsigned int nr_fields;
 272         unsigned int allocated_fields;
 273         unsigned int largest_align;
 274         char padding[LTTNG_UST_CTX_PADDING];
 275 };
 276
 277 #define LTTNG_UST_EVENT_DESC_PADDING    40
 278 struct lttng_event_desc {
 279         const char *name;
 280         void (*probe_callback)(void);
 281         const struct lttng_event_ctx *ctx;      /* context */
 282         const struct lttng_event_field *fields; /* event payload */
 283         unsigned int nr_fields;
 284         const int **loglevel;
 285         const char *signature;  /* Argument types/names received */
 286         union {
 287                 struct {
 288                         const char **model_emf_uri;
 289                 } ext;
 290                 char padding[LTTNG_UST_EVENT_DESC_PADDING];
 291         } u;
 292 };
 293
 294 #define LTTNG_UST_PROBE_DESC_PADDING    12
 295 struct lttng_probe_desc {
 296         const char *provider;
 297         const struct lttng_event_desc **event_desc;
 298         unsigned int nr_events;
 299         struct cds_list_head head;              /* chain registered probes */
 300         struct cds_list_head lazy_init_head;
 301         int lazy;                               /* lazy registration */
 302         uint32_t major;
 303         uint32_t minor;
 304         char padding[LTTNG_UST_PROBE_DESC_PADDING];
 305 };
 306
 307 /* Data structures used by the tracer. */
 308
 309 /*
 310  * Bytecode interpreter return value masks.
 311  */
 312 enum lttng_bytecode_interpreter_ret {
 313         LTTNG_INTERPRETER_DISCARD = 0,
 314         LTTNG_INTERPRETER_RECORD_FLAG = (1ULL << 0),
 315         /* Other bits are kept for future use. */
 316 };
 317
 318 struct lttng_interpreter_output;
 319 struct lttng_ust_bytecode_runtime_private;
 320
 321 /*
 322  * This structure is used in the probes. More specifically, the
 323  * `interpreter_funcs` and `node` fields are explicity used in the
 324  * probes. When modifying this structure we must not change the layout
 325  * of these two fields as it is considered ABI.
 326  */
 327 struct lttng_bytecode_runtime {
 328         struct lttng_ust_bytecode_runtime_private *priv;
 329
 330         /* Associated bytecode */
 331         union {
 332                 uint64_t (*filter)(void *interpreter_data,
 333                                 const char *interpreter_stack_data);
 334                 uint64_t (*capture)(void *interpreter_data,
 335                                 const char *interpreter_stack_data,
 336                                 struct lttng_interpreter_output *interpreter_output);
 337         } interpreter_funcs;
 338         struct cds_list_head node;      /* list of bytecode runtime in event */
 339 };
 340
 341 /*
 342  * lttng_event structure is referred to by the tracing fast path. It
 343  * must be kept small.
 344  *
 345  * IMPORTANT: this structure is part of the ABI between the probe and
 346  * UST. Fields need to be only added at the end, never reordered, never
 347  * removed.
 348  */
 349
 350 struct lttng_ust_event_common_private;
 351
 352 enum lttng_ust_event_type {
 353         LTTNG_UST_EVENT_TYPE_RECORDER = 0,
 354         LTTNG_UST_EVENT_TYPE_NOTIFIER = 1,
 355 };
 356
 357 /*
 358  * IMPORTANT: this structure is part of the ABI between the probe and
 359  * UST. Fields need to be only added at the end, never reordered, never
 360  * removed.
 361  *
 362  * struct lttng_ust_event_common is the common ancestor of the various
 363  * public event actions. Inheritance is done by composition: The parent
 364  * has a pointer to its child, and the child has a pointer to its
 365  * parent. Inheritance of those public structures is done by composition
 366  * to ensure both parent and child structures can be extended.
 367  *
 368  * The field @struct_size should be used to determine the size of the
 369  * structure. It should be queried before using additional fields added
 370  * at the end of the structure.
 371  */
 372 struct lttng_ust_event_common {
 373         uint32_t struct_size;                           /* Size of this structure. */
 374         struct lttng_ust_event_common_private *priv;    /* Private event interface */
 375
 376         enum lttng_ust_event_type type;
 377         void *child;                                    /* Pointer to child, for inheritance by aggregation. */
 378
 379         int enabled;
 380         int has_enablers_without_bytecode;
 381         /* list of struct lttng_bytecode_runtime, sorted by seqnum */
 382         struct cds_list_head filter_bytecode_runtime_head;
 383
 384         /* End of base ABI. Fields below should be used after checking struct_size. */
 385 };
 386
 387 struct lttng_ust_event_recorder_private;
 388
 389 /*
 390  * IMPORTANT: this structure is part of the ABI between the probe and
 391  * UST. Fields need to be only added at the end, never reordered, never
 392  * removed.
 393  *
 394  * struct lttng_ust_event_recorder is the action for recording events
 395  * into a ring buffer. It inherits from struct lttng_ust_event_common
 396  * by composition to ensure both parent and child structure are
 397  * extensible.
 398  *
 399  * The field @struct_size should be used to determine the size of the
 400  * structure. It should be queried before using additional fields added
 401  * at the end of the structure.
 402  */
 403 struct lttng_ust_event_recorder {
 404         uint32_t struct_size;                           /* Size of this structure. */
 405         struct lttng_ust_event_common *parent;          /* Inheritance by aggregation. */
 406         struct lttng_ust_event_recorder_private *priv;  /* Private event record interface */
 407
 408         unsigned int id;
 409         struct lttng_channel *chan;
 410         struct lttng_ctx *ctx;
 411
 412         /* End of base ABI. Fields below should be used after checking struct_size. */
 413 };
 414
 415 struct lttng_ust_event_notifier_private;
 416
 417 /*
 418  * IMPORTANT: this structure is part of the ABI between the probe and
 419  * UST. Fields need to be only added at the end, never reordered, never
 420  * removed.
 421  *
 422  * struct lttng_ust_event_notifier is the action for sending
 423  * notifications. It inherits from struct lttng_ust_event_common
 424  * by composition to ensure both parent and child structure are
 425  * extensible.
 426  *
 427  * The field @struct_size should be used to determine the size of the
 428  * structure. It should be queried before using additional fields added
 429  * at the end of the structure.
 430  */
 431 struct lttng_ust_event_notifier {
 432         uint32_t struct_size;                           /* Size of this structure. */
 433         struct lttng_ust_event_common *parent;          /* Inheritance by aggregation. */
 434         struct lttng_ust_event_notifier_private *priv;  /* Private event notifier interface */
 435
 436         void (*notification_send)(struct lttng_ust_event_notifier *event_notifier,
 437                 const char *stack_data);
 438         struct cds_list_head capture_bytecode_runtime_head;
 439
 440         /* End of base ABI. Fields below should be used after checking struct_size. */
 441 };
 442
 443 struct lttng_enum {
 444         const struct lttng_enum_desc *desc;
 445         struct lttng_session *session;
 446         struct cds_list_head node;      /* Enum list in session */
 447         struct cds_hlist_node hlist;    /* Session ht of enums */
 448         uint64_t id;                    /* Enumeration ID in sessiond */
 449 };
 450
 451 struct channel;
 452 struct lttng_ust_shm_handle;
 453
 454 /*
 455  * IMPORTANT: this structure is part of the ABI between the probe and
 456  * UST. Fields need to be only added at the end, never reordered, never
 457  * removed.
 458  */
 459 struct lttng_channel_ops {
 460         struct lttng_channel *(*channel_create)(const char *name,
 461                         void *buf_addr,
 462                         size_t subbuf_size, size_t num_subbuf,
 463                         unsigned int switch_timer_interval,
 464                         unsigned int read_timer_interval,
 465                         unsigned char *uuid,
 466                         uint32_t chan_id,
 467                         const int *stream_fds, int nr_stream_fds,
 468                         int64_t blocking_timeout);
 469         void (*channel_destroy)(struct lttng_channel *chan);
 470         int (*event_reserve)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
 471                              uint32_t event_id);
 472         void (*event_commit)(struct lttng_ust_lib_ring_buffer_ctx *ctx);
 473         void (*event_write)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
 474                         const void *src, size_t len);
 475         /*
 476          * packet_avail_size returns the available size in the current
 477          * packet. Note that the size returned is only a hint, since it
 478          * may change due to concurrent writes.
 479          */
 480         size_t (*packet_avail_size)(struct channel *chan,
 481                                     struct lttng_ust_shm_handle *handle);
 482         int (*is_finalized)(struct channel *chan);
 483         int (*is_disabled)(struct channel *chan);
 484         int (*flush_buffer)(struct channel *chan, struct lttng_ust_shm_handle *handle);
 485         void (*event_strcpy)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
 486                         const char *src, size_t len);
 487 };
 488
 489 /*
 490  * IMPORTANT: this structure is part of the ABI between the probe and
 491  * UST. Fields need to be only added at the end, never reordered, never
 492  * removed.
 493  */
 494 struct lttng_channel {
 495         /*
 496          * The pointers located in this private data are NOT safe to be
 497          * dereferenced by the consumer. The only operations the
 498          * consumer process is designed to be allowed to do is to read
 499          * and perform subbuffer flush.
 500          */
 501         struct channel *chan;           /* Channel buffers */
 502         int enabled;
 503         struct lttng_ctx *ctx;
 504         /* Event ID management */
 505         struct lttng_session *session;
 506         int objd;                       /* Object associated to channel */
 507         struct cds_list_head node;      /* Channel list in session */
 508         const struct lttng_channel_ops *ops;
 509         int header_type;                /* 0: unset, 1: compact, 2: large */
 510         struct lttng_ust_shm_handle *handle;    /* shared-memory handle */
 511
 512         /* Channel ID */
 513         unsigned int id;
 514         enum lttng_ust_abi_chan_type type;
 515         unsigned char uuid[LTTNG_UST_UUID_LEN]; /* Trace session unique ID */
 516         int tstate:1;                   /* Transient enable state */
 517 };
 518
 519 struct lttng_counter_dimension;
 520
 521 struct lttng_counter_ops {
 522         struct lib_counter *(*counter_create)(size_t nr_dimensions,
 523                         const struct lttng_counter_dimension *dimensions,
 524                         int64_t global_sum_step,
 525                         int global_counter_fd,
 526                         int nr_counter_cpu_fds,
 527                         const int *counter_cpu_fds,
 528                         bool is_daemon);
 529         void (*counter_destroy)(struct lib_counter *counter);
 530         int (*counter_add)(struct lib_counter *counter,
 531                         const size_t *dimension_indexes, int64_t v);
 532         int (*counter_read)(struct lib_counter *counter,
 533                         const size_t *dimension_indexes, int cpu,
 534                         int64_t *value, bool *overflow, bool *underflow);
 535         int (*counter_aggregate)(struct lib_counter *counter,
 536                         const size_t *dimension_indexes, int64_t *value,
 537                         bool *overflow, bool *underflow);
 538         int (*counter_clear)(struct lib_counter *counter, const size_t *dimension_indexes);
 539 };
 540
 541 #define LTTNG_UST_STACK_CTX_PADDING     32
 542 struct lttng_stack_ctx {
 543         struct lttng_ust_event_recorder *event_recorder;
 544         struct lttng_ctx *chan_ctx;     /* RCU dereferenced. */
 545         struct lttng_ctx *event_ctx;    /* RCU dereferenced. */
 546         char padding[LTTNG_UST_STACK_CTX_PADDING];
 547 };
 548
 549 #define LTTNG_UST_EVENT_HT_BITS         12
 550 #define LTTNG_UST_EVENT_HT_SIZE         (1U << LTTNG_UST_EVENT_HT_BITS)
 551
 552 struct lttng_ust_event_ht {
 553         struct cds_hlist_head table[LTTNG_UST_EVENT_HT_SIZE];
 554 };
 555
 556 #define LTTNG_UST_EVENT_NOTIFIER_HT_BITS                12
 557 #define LTTNG_UST_EVENT_NOTIFIER_HT_SIZE                (1U << LTTNG_UST_EVENT_NOTIFIER_HT_BITS)
 558 struct lttng_ust_event_notifier_ht {
 559         struct cds_hlist_head table[LTTNG_UST_EVENT_NOTIFIER_HT_SIZE];
 560 };
 561
 562 #define LTTNG_UST_ENUM_HT_BITS          12
 563 #define LTTNG_UST_ENUM_HT_SIZE          (1U << LTTNG_UST_ENUM_HT_BITS)
 564
 565 struct lttng_ust_enum_ht {
 566         struct cds_hlist_head table[LTTNG_UST_ENUM_HT_SIZE];
 567 };
 568
 569 struct lttng_ust_session_private;
 570
 571 /*
 572  * IMPORTANT: this structure is part of the ABI between the probe and
 573  * UST. Fields need to be only added at the end, never reordered, never
 574  * removed.
 575  *
 576  * The field @struct_size should be used to determine the size of the
 577  * structure. It should be queried before using additional fields added
 578  * at the end of the structure.
 579  */
 580 struct lttng_session {
 581         uint32_t struct_size;                   /* Size of this structure */
 582         struct lttng_ust_session_private *priv; /* Private session interface */
 583
 584         int active;                             /* Is trace session active ? */
 585
 586         /* End of base ABI. Fields below should be used after checking struct_size. */
 587 };
 588
 589 int lttng_probe_register(struct lttng_probe_desc *desc);
 590 void lttng_probe_unregister(struct lttng_probe_desc *desc);
 591
 592 /*
 593  * Can be used by applications that change their procname to clear the ust cached value.
 594  */
 595 void lttng_context_procname_reset(void);
 596
 597 struct lttng_transport *lttng_transport_find(const char *name);
 598
 599 int lttng_session_active(void);
 600
 601 void lttng_ust_dl_update(void *ip);
 602
 603 #ifdef __cplusplus
 604 }
 605 #endif
 606
 607 #endif /* _LTTNG_UST_EVENTS_H */