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