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_ust_session;
  45 struct lttng_ust_lib_ring_buffer_ctx;
  46 struct lttng_ust_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 /*
  87  * Enumeration entry description
  88  *
  89  * IMPORTANT: this structure is part of the ABI between the probe and
  90  * UST. Fields need to be only added at the end, never reordered, never
  91  * removed.
  92  *
  93  * The field @struct_size should be used to determine the size of the
  94  * structure. It should be queried before using additional fields added
  95  * at the end of the structure.
  96  */
  97
  98 struct lttng_ust_enum_entry {
  99         uint32_t struct_size;
 100
 101         struct lttng_enum_value start, end; /* start and end are inclusive */
 102         const char *string;
 103         unsigned int options;
 104
 105         /* End of base ABI. Fields below should be used after checking struct_size. */
 106 };
 107
 108 #define __type_integer(_type, _byte_order, _base, _encoding)            \
 109         {                                                               \
 110                 .atype = atype_integer,                                 \
 111                 .u = {                                                  \
 112                         .integer = {                                    \
 113                                 .size = sizeof(_type) * CHAR_BIT,       \
 114                                 .alignment = lttng_alignof(_type) * CHAR_BIT, \
 115                                 .signedness = lttng_is_signed_type(_type), \
 116                                 .reverse_byte_order = _byte_order != BYTE_ORDER, \
 117                                 .base = _base,                  \
 118                                 .encoding = lttng_encode_##_encoding, \
 119                         }                                       \
 120                 },                                              \
 121         }                                                       \
 122
 123 #define LTTNG_UST_INTEGER_TYPE_PADDING  24
 124 struct lttng_integer_type {
 125         unsigned int size;              /* in bits */
 126         unsigned short alignment;       /* in bits */
 127         unsigned int signedness:1;
 128         unsigned int reverse_byte_order:1;
 129         unsigned int base;              /* 2, 8, 10, 16, for pretty print */
 130         enum lttng_string_encodings encoding;
 131         char padding[LTTNG_UST_INTEGER_TYPE_PADDING];
 132 };
 133
 134 /*
 135  * Only float and double are supported. long double is not supported at
 136  * the moment.
 137  */
 138 #define _float_mant_dig(_type)                                          \
 139         (sizeof(_type) == sizeof(float) ? FLT_MANT_DIG                  \
 140                 : (sizeof(_type) == sizeof(double) ? DBL_MANT_DIG       \
 141                 : 0))
 142
 143 #define __type_float(_type)                                             \
 144         {                                                               \
 145                 .atype = atype_float,                                   \
 146                 .u = {                                                  \
 147                         ._float = {                                     \
 148                                 .exp_dig = sizeof(_type) * CHAR_BIT     \
 149                                         - _float_mant_dig(_type),       \
 150                                 .mant_dig = _float_mant_dig(_type),     \
 151                                 .alignment = lttng_alignof(_type) * CHAR_BIT, \
 152                                 .reverse_byte_order = BYTE_ORDER != FLOAT_WORD_ORDER,   \
 153                         }                                               \
 154                 }                                                       \
 155         }                                                               \
 156
 157 #define LTTNG_UST_FLOAT_TYPE_PADDING    24
 158 struct lttng_float_type {
 159         unsigned int exp_dig;           /* exponent digits, in bits */
 160         unsigned int mant_dig;          /* mantissa digits, in bits */
 161         unsigned short alignment;       /* in bits */
 162         unsigned int reverse_byte_order:1;
 163         char padding[LTTNG_UST_FLOAT_TYPE_PADDING];
 164 };
 165
 166 #define LTTNG_UST_TYPE_PADDING  128
 167 struct lttng_type {
 168         enum lttng_abstract_types atype;
 169         union {
 170                 /* provider ABI 2.0 */
 171                 struct lttng_integer_type integer;
 172                 struct lttng_float_type _float;
 173                 struct {
 174                         enum lttng_string_encodings encoding;
 175                 } string;
 176                 struct {
 177                         const struct lttng_ust_enum_desc *desc; /* Enumeration mapping */
 178                         struct lttng_type *container_type;
 179                 } enum_nestable;
 180                 struct {
 181                         const struct lttng_type *elem_type;
 182                         unsigned int length;                    /* Num. elems. */
 183                         unsigned int alignment;
 184                 } array_nestable;
 185                 struct {
 186                         const char *length_name;                /* Length field name. */
 187                         const struct lttng_type *elem_type;
 188                         unsigned int alignment;                 /* Alignment before elements. */
 189                 } sequence_nestable;
 190                 struct {
 191                         unsigned int nr_fields;
 192                         const struct lttng_ust_event_field **fields; /* Array of pointers to fields. */
 193                         unsigned int alignment;
 194                 } struct_nestable;
 195
 196                 char padding[LTTNG_UST_TYPE_PADDING];
 197         } u;
 198 };
 199
 200 /*
 201  * Enumeration description
 202  *
 203  * IMPORTANT: this structure is part of the ABI between the probe and
 204  * UST. Fields need to be only added at the end, never reordered, never
 205  * removed.
 206  *
 207  * The field @struct_size should be used to determine the size of the
 208  * structure. It should be queried before using additional fields added
 209  * at the end of the structure.
 210  */
 211
 212 struct lttng_ust_enum_desc {
 213         uint32_t struct_size;
 214
 215         const char *name;
 216         const struct lttng_ust_enum_entry **entries;
 217         unsigned int nr_entries;
 218
 219         /* End of base ABI. Fields below should be used after checking struct_size. */
 220 };
 221
 222 /*
 223  * Event field description
 224  *
 225  * IMPORTANT: this structure is part of the ABI between the probe and
 226  * UST. Fields need to be only added at the end, never reordered, never
 227  * removed.
 228  *
 229  * The field @struct_size should be used to determine the size of the
 230  * structure. It should be queried before using additional fields added
 231  * at the end of the structure.
 232  */
 233
 234 struct lttng_ust_event_field {
 235         uint32_t struct_size;
 236
 237         const char *name;
 238         struct lttng_type type;
 239         unsigned int nowrite:1,         /* do not write into trace */
 240                 nofilter:1;             /* do not consider for filter */
 241
 242         /* End of base ABI. Fields below should be used after checking struct_size. */
 243 };
 244
 245
 246 /*
 247  * IMPORTANT: this structure is part of the ABI between the probe and
 248  * UST. Fields need to be only added at the end, never reordered, never
 249  * removed.
 250  *
 251  * The field @struct_size should be used to determine the size of the
 252  * structure. It should be queried before using additional fields added
 253  * at the end of the structure.
 254  */
 255 struct lttng_ust_event_desc {
 256         uint32_t struct_size;                   /* Size of this structure. */
 257
 258         const char *name;
 259         void (*probe_callback)(void);
 260         const struct lttng_event_ctx *ctx;      /* context */
 261         const struct lttng_ust_event_field **fields;    /* event payload */
 262         unsigned int nr_fields;
 263         const int **loglevel;
 264         const char *signature;                  /* Argument types/names received */
 265         const char **model_emf_uri;
 266
 267         /* End of base ABI. Fields below should be used after checking struct_size. */
 268 };
 269
 270 /*
 271  * IMPORTANT: this structure is part of the ABI between the probe and
 272  * UST. Fields need to be only added at the end, never reordered, never
 273  * removed.
 274  *
 275  * The field @struct_size should be used to determine the size of the
 276  * structure. It should be queried before using additional fields added
 277  * at the end of the structure.
 278  */
 279 struct lttng_ust_probe_desc {
 280         uint32_t struct_size;                   /* Size of this structure. */
 281
 282         const char *provider;
 283         const struct lttng_ust_event_desc **event_desc;
 284         unsigned int nr_events;
 285         struct cds_list_head head;              /* chain registered probes */
 286         struct cds_list_head lazy_init_head;
 287         int lazy;                               /* lazy registration */
 288         uint32_t major;
 289         uint32_t minor;
 290
 291         /* End of base ABI. Fields below should be used after checking struct_size. */
 292 };
 293
 294 /* Data structures used by the tracer. */
 295
 296 /*
 297  * Bytecode interpreter return value masks.
 298  */
 299 enum lttng_bytecode_interpreter_ret {
 300         LTTNG_INTERPRETER_DISCARD = 0,
 301         LTTNG_INTERPRETER_RECORD_FLAG = (1ULL << 0),
 302         /* Other bits are kept for future use. */
 303 };
 304
 305 struct lttng_interpreter_output;
 306 struct lttng_ust_bytecode_runtime_private;
 307
 308 /*
 309  * IMPORTANT: this structure is part of the ABI between the probe and
 310  * UST. Fields need to be only added at the end, never reordered, never
 311  * removed.
 312  *
 313  * The field @struct_size should be used to determine the size of the
 314  * structure. It should be queried before using additional fields added
 315  * at the end of the structure.
 316  */
 317 struct lttng_ust_bytecode_runtime {
 318         uint32_t struct_size;                   /* Size of this structure. */
 319
 320         struct lttng_ust_bytecode_runtime_private *priv;
 321         /* Associated bytecode */
 322         union {
 323                 uint64_t (*filter)(void *interpreter_data,
 324                                 const char *interpreter_stack_data);
 325                 uint64_t (*capture)(void *interpreter_data,
 326                                 const char *interpreter_stack_data,
 327                                 struct lttng_interpreter_output *interpreter_output);
 328         } interpreter_funcs;
 329         struct cds_list_head node;      /* list of bytecode runtime in event */
 330
 331         /* End of base ABI. Fields below should be used after checking struct_size. */
 332 };
 333
 334 /*
 335  * lttng_event structure is referred to by the tracing fast path. It
 336  * must be kept small.
 337  *
 338  * IMPORTANT: this structure is part of the ABI between the probe and
 339  * UST. Fields need to be only added at the end, never reordered, never
 340  * removed.
 341  */
 342
 343 struct lttng_ust_ctx;
 344 struct lttng_ust_event_common_private;
 345
 346 enum lttng_ust_event_type {
 347         LTTNG_UST_EVENT_TYPE_RECORDER = 0,
 348         LTTNG_UST_EVENT_TYPE_NOTIFIER = 1,
 349 };
 350
 351 /*
 352  * IMPORTANT: this structure is part of the ABI between the probe and
 353  * UST. Fields need to be only added at the end, never reordered, never
 354  * removed.
 355  *
 356  * struct lttng_ust_event_common is the common ancestor of the various
 357  * public event actions. Inheritance is done by composition: The parent
 358  * has a pointer to its child, and the child has a pointer to its
 359  * parent. Inheritance of those public structures is done by composition
 360  * to ensure both parent and child structures can be extended.
 361  *
 362  * The field @struct_size should be used to determine the size of the
 363  * structure. It should be queried before using additional fields added
 364  * at the end of the structure.
 365  */
 366 struct lttng_ust_event_common {
 367         uint32_t struct_size;                           /* Size of this structure. */
 368
 369         struct lttng_ust_event_common_private *priv;    /* Private event interface */
 370
 371         enum lttng_ust_event_type type;
 372         void *child;                                    /* Pointer to child, for inheritance by aggregation. */
 373
 374         int enabled;
 375         int has_enablers_without_bytecode;
 376         /* list of struct lttng_ust_bytecode_runtime, sorted by seqnum */
 377         struct cds_list_head filter_bytecode_runtime_head;
 378
 379         /* End of base ABI. Fields below should be used after checking struct_size. */
 380 };
 381
 382 struct lttng_ust_event_recorder_private;
 383
 384 /*
 385  * IMPORTANT: this structure is part of the ABI between the probe and
 386  * UST. Fields need to be only added at the end, never reordered, never
 387  * removed.
 388  *
 389  * struct lttng_ust_event_recorder is the action for recording events
 390  * into a ring buffer. It inherits from struct lttng_ust_event_common
 391  * by composition to ensure both parent and child structure are
 392  * extensible.
 393  *
 394  * The field @struct_size should be used to determine the size of the
 395  * structure. It should be queried before using additional fields added
 396  * at the end of the structure.
 397  */
 398 struct lttng_ust_event_recorder {
 399         uint32_t struct_size;                           /* Size of this structure. */
 400
 401         struct lttng_ust_event_common *parent;          /* Inheritance by aggregation. */
 402         struct lttng_ust_event_recorder_private *priv;  /* Private event record interface */
 403
 404         unsigned int id;
 405         struct lttng_channel *chan;
 406         struct lttng_ust_ctx *ctx;
 407
 408         /* End of base ABI. Fields below should be used after checking struct_size. */
 409 };
 410
 411 struct lttng_ust_event_notifier_private;
 412
 413 /*
 414  * IMPORTANT: this structure is part of the ABI between the probe and
 415  * UST. Fields need to be only added at the end, never reordered, never
 416  * removed.
 417  *
 418  * struct lttng_ust_event_notifier is the action for sending
 419  * notifications. It inherits from struct lttng_ust_event_common
 420  * by composition to ensure both parent and child structure are
 421  * extensible.
 422  *
 423  * The field @struct_size should be used to determine the size of the
 424  * structure. It should be queried before using additional fields added
 425  * at the end of the structure.
 426  */
 427 struct lttng_ust_event_notifier {
 428         uint32_t struct_size;                           /* Size of this structure. */
 429
 430         struct lttng_ust_event_common *parent;          /* Inheritance by aggregation. */
 431         struct lttng_ust_event_notifier_private *priv;  /* Private event notifier interface */
 432
 433         void (*notification_send)(struct lttng_ust_event_notifier *event_notifier,
 434                 const char *stack_data);
 435         struct cds_list_head capture_bytecode_runtime_head;
 436
 437         /* End of base ABI. Fields below should be used after checking struct_size. */
 438 };
 439
 440 struct lttng_ust_lib_ring_buffer_channel;
 441 struct lttng_ust_shm_handle;
 442
 443 /*
 444  * IMPORTANT: this structure is part of the ABI between the probe and
 445  * UST. Fields need to be only added at the end, never reordered, never
 446  * removed.
 447  *
 448  * The field @struct_size should be used to determine the size of the
 449  * structure. It should be queried before using additional fields added
 450  * at the end of the structure.
 451  */
 452 struct lttng_ust_channel_ops {
 453         uint32_t struct_size;
 454
 455         struct lttng_channel *(*channel_create)(const char *name,
 456                         void *buf_addr,
 457                         size_t subbuf_size, size_t num_subbuf,
 458                         unsigned int switch_timer_interval,
 459                         unsigned int read_timer_interval,
 460                         unsigned char *uuid,
 461                         uint32_t chan_id,
 462                         const int *stream_fds, int nr_stream_fds,
 463                         int64_t blocking_timeout);
 464         void (*channel_destroy)(struct lttng_channel *chan);
 465         int (*event_reserve)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
 466                              uint32_t event_id);
 467         void (*event_commit)(struct lttng_ust_lib_ring_buffer_ctx *ctx);
 468         void (*event_write)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
 469                         const void *src, size_t len);
 470         /*
 471          * packet_avail_size returns the available size in the current
 472          * packet. Note that the size returned is only a hint, since it
 473          * may change due to concurrent writes.
 474          */
 475         size_t (*packet_avail_size)(struct lttng_ust_lib_ring_buffer_channel *chan,
 476                                     struct lttng_ust_shm_handle *handle);
 477         int (*is_finalized)(struct lttng_ust_lib_ring_buffer_channel *chan);
 478         int (*is_disabled)(struct lttng_ust_lib_ring_buffer_channel *chan);
 479         int (*flush_buffer)(struct lttng_ust_lib_ring_buffer_channel *chan,
 480                             struct lttng_ust_shm_handle *handle);
 481         void (*event_strcpy)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
 482                         const char *src, size_t len);
 483
 484         /* End of base ABI. Fields below should be used after checking struct_size. */
 485 };
 486
 487 /*
 488  * IMPORTANT: this structure is part of the ABI between the probe and
 489  * UST. Fields need to be only added at the end, never reordered, never
 490  * removed.
 491  */
 492 struct lttng_channel {
 493         /*
 494          * The pointers located in this private data are NOT safe to be
 495          * dereferenced by the consumer. The only operations the
 496          * consumer process is designed to be allowed to do is to read
 497          * and perform subbuffer flush.
 498          */
 499         struct lttng_ust_lib_ring_buffer_channel *chan; /* Channel buffers */
 500         int enabled;
 501         struct lttng_ust_ctx *ctx;
 502         /* Event ID management */
 503         struct lttng_ust_session *session;
 504         int objd;                       /* Object associated to channel */
 505         struct cds_list_head node;      /* Channel list in session */
 506         const struct lttng_ust_channel_ops *ops;
 507         int header_type;                /* 0: unset, 1: compact, 2: large */
 508         struct lttng_ust_shm_handle *handle;    /* shared-memory handle */
 509
 510         /* Channel ID */
 511         unsigned int id;
 512         enum lttng_ust_abi_chan_type type;
 513         unsigned char uuid[LTTNG_UST_UUID_LEN]; /* Trace session unique ID */
 514         int tstate:1;                   /* Transient enable state */
 515 };
 516
 517 /*
 518  * IMPORTANT: this structure is part of the ABI between the probe and
 519  * UST. Fields need to be only added at the end, never reordered, never
 520  * removed.
 521  *
 522  * The field @struct_size should be used to determine the size of the
 523  * structure. It should be queried before using additional fields added
 524  * at the end of the structure.
 525  */
 526 struct lttng_ust_stack_ctx {
 527         uint32_t struct_size;                   /* Size of this structure */
 528
 529         struct lttng_ust_event_recorder *event_recorder;
 530         struct lttng_ust_ctx *chan_ctx; /* RCU dereferenced. */
 531         struct lttng_ust_ctx *event_ctx;        /* RCU dereferenced. */
 532
 533         /* End of base ABI. Fields below should be used after checking struct_size. */
 534 };
 535
 536 struct lttng_ust_session_private;
 537
 538 /*
 539  * IMPORTANT: this structure is part of the ABI between the probe and
 540  * UST. Fields need to be only added at the end, never reordered, never
 541  * removed.
 542  *
 543  * The field @struct_size should be used to determine the size of the
 544  * structure. It should be queried before using additional fields added
 545  * at the end of the structure.
 546  */
 547 struct lttng_ust_session {
 548         uint32_t struct_size;                   /* Size of this structure */
 549
 550         struct lttng_ust_session_private *priv; /* Private session interface */
 551
 552         int active;                             /* Is trace session active ? */
 553
 554         /* End of base ABI. Fields below should be used after checking struct_size. */
 555 };
 556
 557 int lttng_ust_probe_register(struct lttng_ust_probe_desc *desc);
 558 void lttng_ust_probe_unregister(struct lttng_ust_probe_desc *desc);
 559
 560 /*
 561  * Applications that change their procname and need the new value to be
 562  * reflected in the procname event context have to call this function to clear
 563  * the internally cached value. This should not be called from a signal
 564  * handler.
 565  */
 566 void lttng_ust_context_procname_reset(void);
 567
 568 #ifdef __cplusplus
 569 }
 570 #endif
 571
 572 #endif /* _LTTNG_UST_EVENTS_H */