1 // SPDX-FileCopyrightText: 2010-2012 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
3 // SPDX-License-Identifier: MIT
6 * Holds LTTng per-session event registry.
9 #ifndef _LTTNG_UST_EVENTS_H
10 #define _LTTNG_UST_EVENTS_H
14 #include <lttng/ust-abi.h>
15 #include <lttng/ust-tracer.h>
16 #include <lttng/ust-endian.h>
27 #define LTTNG_UST_UUID_LEN 16
30 * Tracepoint provider version. Compatibility based on the major number.
31 * Older tracepoint providers can always register to newer lttng-ust
32 * library, but the opposite is rejected: a newer tracepoint provider is
33 * rejected by an older lttng-ust library.
35 * LTTNG_UST_PROVIDER_MAJOR_OLDEST_COMPATIBLE is the floor value of
36 * oldest provider major version currently allowed, typically increased
37 * when LTTng-UST has an ABI-breaking soname bump.
39 #define LTTNG_UST_PROVIDER_MAJOR 3
40 #define LTTNG_UST_PROVIDER_MAJOR_OLDEST_COMPATIBLE 3
41 #define LTTNG_UST_PROVIDER_MINOR 0
43 struct lttng_ust_channel_buffer
;
44 struct lttng_ust_session
;
45 struct lttng_ust_ring_buffer_ctx
;
46 struct lttng_ust_event_field
;
47 struct lttng_ust_registered_probe
;
50 * Data structures used by tracepoint event declarations, and by the
54 /* Type description */
57 lttng_ust_type_integer
,
58 lttng_ust_type_string
,
60 lttng_ust_type_dynamic
,
63 lttng_ust_type_sequence
,
64 lttng_ust_type_struct
,
68 enum lttng_ust_string_encoding
{
69 lttng_ust_string_encoding_none
= 0,
70 lttng_ust_string_encoding_UTF8
= 1,
71 lttng_ust_string_encoding_ASCII
= 2,
72 NR_LTTNG_UST_STRING_ENCODING
,
75 struct lttng_ust_enum_value
{
76 unsigned long long value
;
77 unsigned int signedness
:1;
80 enum lttng_ust_enum_entry_option
{
81 LTTNG_UST_ENUM_ENTRY_OPTION_IS_AUTO
= 1U << 0,
85 * Enumeration entry description
87 * IMPORTANT: this structure is part of the ABI between the probe and
88 * UST. Fields need to be only added at the end, never reordered, never
91 * The field @struct_size should be used to determine the size of the
92 * structure. It should be queried before using additional fields added
93 * at the end of the structure.
96 struct lttng_ust_enum_entry
{
99 struct lttng_ust_enum_value start
, end
; /* start and end are inclusive */
101 unsigned int options
;
103 /* End of base ABI. Fields below should be used after checking struct_size. */
107 * struct lttng_ust_type_common is fixed-size. Its children inherits
108 * from it by embedding struct lttng_ust_type_common as its first field.
110 struct lttng_ust_type_common
{
111 enum lttng_ust_type type
;
114 struct lttng_ust_type_integer
{
115 struct lttng_ust_type_common parent
;
116 uint32_t struct_size
;
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 */
124 #define lttng_ust_type_integer_define(_type, _byte_order, _base) \
125 ((struct lttng_ust_type_common *) LTTNG_UST_COMPOUND_LITERAL(struct lttng_ust_type_integer, { \
127 .type = lttng_ust_type_integer, \
129 .struct_size = sizeof(struct lttng_ust_type_integer), \
130 .size = sizeof(_type) * CHAR_BIT, \
131 .alignment = lttng_ust_rb_alignof(_type) * CHAR_BIT, \
132 .signedness = lttng_ust_is_signed_type(_type), \
133 .reverse_byte_order = _byte_order != LTTNG_UST_BYTE_ORDER, \
137 struct lttng_ust_type_float
{
138 struct lttng_ust_type_common parent
;
139 uint32_t struct_size
;
140 unsigned int exp_dig
; /* exponent digits, in bits */
141 unsigned int mant_dig
; /* mantissa digits, in bits */
142 unsigned short alignment
; /* in bits */
143 unsigned int reverse_byte_order
:1;
147 * Only float and double are supported. long double is not supported at
150 #define lttng_ust_float_mant_dig(_type) \
151 (sizeof(_type) == sizeof(float) ? FLT_MANT_DIG \
152 : (sizeof(_type) == sizeof(double) ? DBL_MANT_DIG \
155 #define lttng_ust_type_float_define(_type) \
156 ((struct lttng_ust_type_common *) LTTNG_UST_COMPOUND_LITERAL(struct lttng_ust_type_float, { \
158 .type = lttng_ust_type_float, \
160 .struct_size = sizeof(struct lttng_ust_type_float), \
161 .exp_dig = sizeof(_type) * CHAR_BIT \
162 - lttng_ust_float_mant_dig(_type), \
163 .mant_dig = lttng_ust_float_mant_dig(_type), \
164 .alignment = lttng_ust_rb_alignof(_type) * CHAR_BIT, \
165 .reverse_byte_order = LTTNG_UST_BYTE_ORDER != LTTNG_UST_FLOAT_WORD_ORDER, \
169 struct lttng_ust_type_string
{
170 struct lttng_ust_type_common parent
;
171 uint32_t struct_size
;
172 enum lttng_ust_string_encoding encoding
;
175 struct lttng_ust_type_enum
{
176 struct lttng_ust_type_common parent
;
177 uint32_t struct_size
;
178 const struct lttng_ust_enum_desc
*desc
; /* Enumeration mapping */
179 const struct lttng_ust_type_common
*container_type
;
183 * The alignment field in structure, array, and sequence types is a
184 * minimum alignment requirement. The actual alignment of a type may be
185 * larger than this explicit alignment value if its nested types have a
189 struct lttng_ust_type_array
{
190 struct lttng_ust_type_common parent
;
191 uint32_t struct_size
;
192 const struct lttng_ust_type_common
*elem_type
;
193 unsigned int length
; /* Num. elems. */
194 unsigned int alignment
; /* Minimum alignment for this type. */
195 enum lttng_ust_string_encoding encoding
;
198 struct lttng_ust_type_sequence
{
199 struct lttng_ust_type_common parent
;
200 uint32_t struct_size
;
201 const char *length_name
; /* Length field name. If NULL, use previous field. */
202 const struct lttng_ust_type_common
*elem_type
;
203 unsigned int alignment
; /* Minimum alignment before elements. */
204 enum lttng_ust_string_encoding encoding
;
207 struct lttng_ust_type_struct
{
208 struct lttng_ust_type_common parent
;
209 uint32_t struct_size
;
210 unsigned int nr_fields
;
211 const struct lttng_ust_event_field
* const *fields
; /* Array of pointers to fields. */
212 unsigned int alignment
; /* Minimum alignment for this type. */
216 * Enumeration description
218 * IMPORTANT: this structure is part of the ABI between the probe and
219 * UST. Fields need to be only added at the end, never reordered, never
222 * The field @struct_size should be used to determine the size of the
223 * structure. It should be queried before using additional fields added
224 * at the end of the structure.
227 struct lttng_ust_enum_desc
{
228 uint32_t struct_size
;
231 const struct lttng_ust_enum_entry
* const *entries
;
232 unsigned int nr_entries
;
233 const struct lttng_ust_probe_desc
*probe_desc
;
235 /* End of base ABI. Fields below should be used after checking struct_size. */
239 * Event field description
241 * IMPORTANT: this structure is part of the ABI between the probe and
242 * UST. Fields need to be only added at the end, never reordered, never
245 * The field @struct_size should be used to determine the size of the
246 * structure. It should be queried before using additional fields added
247 * at the end of the structure.
250 struct lttng_ust_event_field
{
251 uint32_t struct_size
;
254 const struct lttng_ust_type_common
*type
;
255 unsigned int nowrite
:1, /* do not write into trace */
256 nofilter
:1; /* do not consider for filter */
258 /* End of base ABI. Fields below should be used after checking struct_size. */
262 * Tracepoint class description
264 * IMPORTANT: this structure is part of the ABI between the probe and
265 * UST. Fields need to be only added at the end, never reordered, never
268 * The field @struct_size should be used to determine the size of the
269 * structure. It should be queried before using additional fields added
270 * at the end of the structure.
273 struct lttng_ust_tracepoint_class
{
274 uint32_t struct_size
;
276 const struct lttng_ust_event_field
* const *fields
;
278 void (*probe_callback
)(void);
279 const char *signature
; /* Argument types/names received */
280 const struct lttng_ust_probe_desc
*probe_desc
;
282 /* End of base ABI. Fields below should be used after checking struct_size. */
286 * IMPORTANT: this structure is part of the ABI between the probe and
287 * UST. Fields need to be only added at the end, never reordered, never
290 * The field @struct_size should be used to determine the size of the
291 * structure. It should be queried before using additional fields added
292 * at the end of the structure.
294 struct lttng_ust_event_desc
{
295 uint32_t struct_size
; /* Size of this structure. */
297 const char *event_name
;
298 const struct lttng_ust_probe_desc
*probe_desc
;
299 const struct lttng_ust_tracepoint_class
*tp_class
;
300 const int **loglevel
;
301 const char **model_emf_uri
;
303 /* End of base ABI. Fields below should be used after checking struct_size. */
307 * IMPORTANT: this structure is part of the ABI between the probe and
308 * UST. Fields need to be only added at the end, never reordered, never
311 * The field @struct_size should be used to determine the size of the
312 * structure. It should be queried before using additional fields added
313 * at the end of the structure.
315 struct lttng_ust_probe_desc
{
316 uint32_t struct_size
; /* Size of this structure. */
318 const char *provider_name
;
319 const struct lttng_ust_event_desc
* const *event_desc
;
320 unsigned int nr_events
;
324 /* End of base ABI. Fields below should be used after checking struct_size. */
327 /* Data structures used by the tracer. */
330 * IMPORTANT: this structure is part of the ABI between the probe and
331 * UST. Fields need to be only added at the end, never reordered, never
334 * The field @struct_size should be used to determine the size of the
335 * structure. It should be queried before using additional fields added
336 * at the end of the structure.
338 * The probe_ctx is not const because it may be extended to add future
339 * fields which could be modified by callbacks.
341 struct lttng_ust_probe_ctx
{
342 uint32_t struct_size
; /* Size of this structure. */
344 void *ip
; /* caller ip address */
346 /* End of base ABI. Fields below should be used after checking struct_size. */
350 * lttng_event structure is referred to by the tracing fast path. It
351 * must be kept small.
353 * IMPORTANT: this structure is part of the ABI between the probe and
354 * UST. Fields need to be only added at the end, never reordered, never
358 struct lttng_ust_event_common_private
;
360 enum lttng_ust_event_type
{
361 LTTNG_UST_EVENT_TYPE_RECORDER
= 0,
362 LTTNG_UST_EVENT_TYPE_NOTIFIER
= 1,
363 LTTNG_UST_EVENT_TYPE_COUNTER
= 2,
367 * Result of the run_filter() callback.
369 enum lttng_ust_event_filter_result
{
370 LTTNG_UST_EVENT_FILTER_ACCEPT
= 0,
371 LTTNG_UST_EVENT_FILTER_REJECT
= 1,
375 * IMPORTANT: this structure is part of the ABI between the probe and
376 * UST. Fields need to be only added at the end, never reordered, never
379 * struct lttng_ust_event_common is the common ancestor of the various
380 * public event actions. Inheritance is done by composition: The parent
381 * has a pointer to its child, and the child has a pointer to its
382 * parent. Inheritance of those public structures is done by composition
383 * to ensure both parent and child structures can be extended.
385 * The field @struct_size should be used to determine the size of the
386 * structure. It should be queried before using additional fields added
387 * at the end of the structure.
389 struct lttng_ust_event_common
{
390 uint32_t struct_size
; /* Size of this structure. */
392 struct lttng_ust_event_common_private
*priv
; /* Private event interface */
394 enum lttng_ust_event_type type
;
395 void *child
; /* Pointer to child, for inheritance by aggregation. */
398 int eval_filter
; /* Need to evaluate filters */
399 int (*run_filter
)(const struct lttng_ust_event_common
*event
,
400 const char *stack_data
,
401 struct lttng_ust_probe_ctx
*probe_ctx
,
404 /* End of base ABI. Fields below should be used after checking struct_size. */
407 struct lttng_ust_event_recorder_private
;
410 * IMPORTANT: this structure is part of the ABI between the probe and
411 * UST. Fields need to be only added at the end, never reordered, never
414 * struct lttng_ust_event_recorder is the action for recording events
415 * into a ring buffer. It inherits from struct lttng_ust_event_common
416 * by composition to ensure both parent and child structure are
419 * The field @struct_size should be used to determine the size of the
420 * structure. It should be queried before using additional fields added
421 * at the end of the structure.
423 struct lttng_ust_event_recorder
{
424 uint32_t struct_size
; /* Size of this structure. */
426 struct lttng_ust_event_common
*parent
; /* Inheritance by aggregation. */
427 struct lttng_ust_event_recorder_private
*priv
; /* Private event record interface */
429 struct lttng_ust_channel_buffer
*chan
;
431 /* End of base ABI. Fields below should be used after checking struct_size. */
434 struct lttng_ust_event_counter_private
;
437 * IMPORTANT: this structure is part of the ABI between the probe and
438 * UST. Fields need to be only added at the end, never reordered, never
441 * The field @struct_size should be used to determine the size of the
442 * structure. It should be queried before using additional fields added
443 * at the end of the structure.
445 struct lttng_ust_event_counter_ctx
{
446 uint32_t struct_size
; /* Size of this structure. */
447 int args_available
; /* Input arguments are available. */
449 /* End of base ABI. Fields below should be used after checking struct_size. */
453 * IMPORTANT: this structure is part of the ABI between the probe and
454 * UST. Fields need to be only added at the end, never reordered, never
457 * struct lttng_ust_event_recorder is the action for recording events
458 * into a ring buffer. It inherits from struct lttng_ust_event_common
459 * by composition to ensure both parent and child structure are
462 * The field @struct_size should be used to determine the size of the
463 * structure. It should be queried before using additional fields added
464 * at the end of the structure.
466 struct lttng_ust_event_counter
{
467 uint32_t struct_size
; /* Size of this structure. */
469 struct lttng_ust_event_common
*parent
; /* Inheritance by aggregation. */
470 struct lttng_ust_event_counter_private
*priv
; /* Private event counter interface */
472 struct lttng_ust_channel_counter
*chan
;
474 int use_args
; /* Use input arguments. */
476 /* End of base ABI. Fields below should be used after checking struct_size. */
480 * IMPORTANT: this structure is part of the ABI between the probe and
481 * UST. Fields need to be only added at the end, never reordered, never
484 * The field @struct_size should be used to determine the size of the
485 * structure. It should be queried before using additional fields added
486 * at the end of the structure.
488 struct lttng_ust_notification_ctx
{
489 uint32_t struct_size
; /* Size of this structure. */
490 int eval_capture
; /* Capture evaluation available. */
491 /* End of base ABI. Fields below should be used after checking struct_size. */
494 struct lttng_ust_event_notifier_private
;
497 * IMPORTANT: this structure is part of the ABI between the probe and
498 * UST. Fields need to be only added at the end, never reordered, never
501 * struct lttng_ust_event_notifier is the action for sending
502 * notifications. It inherits from struct lttng_ust_event_common
503 * by composition to ensure both parent and child structure are
506 * The field @struct_size should be used to determine the size of the
507 * structure. It should be queried before using additional fields added
508 * at the end of the structure.
510 struct lttng_ust_event_notifier
{
511 uint32_t struct_size
; /* Size of this structure. */
513 struct lttng_ust_event_common
*parent
; /* Inheritance by aggregation. */
514 struct lttng_ust_event_notifier_private
*priv
; /* Private event notifier interface */
516 int eval_capture
; /* Need to evaluate capture */
517 void (*notification_send
)(const struct lttng_ust_event_notifier
*event_notifier
,
518 const char *stack_data
,
519 struct lttng_ust_probe_ctx
*probe_ctx
,
520 struct lttng_ust_notification_ctx
*notif_ctx
);
522 /* End of base ABI. Fields below should be used after checking struct_size. */
525 struct lttng_ust_ring_buffer_channel
;
526 struct lttng_ust_channel_buffer_ops_private
;
529 * IMPORTANT: this structure is part of the ABI between the probe and
530 * UST. Fields need to be only added at the end, never reordered, never
533 * The field @struct_size should be used to determine the size of the
534 * structure. It should be queried before using additional fields added
535 * at the end of the structure.
537 struct lttng_ust_channel_buffer_ops
{
538 uint32_t struct_size
;
540 struct lttng_ust_channel_buffer_ops_private
*priv
; /* Private channel buffer ops interface */
542 int (*event_reserve
)(struct lttng_ust_ring_buffer_ctx
*ctx
);
543 void (*event_commit
)(struct lttng_ust_ring_buffer_ctx
*ctx
);
544 void (*event_write
)(struct lttng_ust_ring_buffer_ctx
*ctx
,
545 const void *src
, size_t len
, size_t alignment
);
546 void (*event_strcpy
)(struct lttng_ust_ring_buffer_ctx
*ctx
,
547 const char *src
, size_t len
);
548 void (*event_pstrcpy_pad
)(struct lttng_ust_ring_buffer_ctx
*ctx
,
549 const char *src
, size_t len
);
551 /* End of base ABI. Fields below should be used after checking struct_size. */
554 enum lttng_ust_channel_type
{
555 LTTNG_UST_CHANNEL_TYPE_BUFFER
= 0,
556 LTTNG_UST_CHANNEL_TYPE_COUNTER
= 1,
559 struct lttng_ust_channel_common_private
;
562 * IMPORTANT: this structure is part of the ABI between the probe and
563 * UST. Fields need to be only added at the end, never reordered, never
566 * The field @struct_size should be used to determine the size of the
567 * structure. It should be queried before using additional fields added
568 * at the end of the structure.
570 struct lttng_ust_channel_common
{
571 uint32_t struct_size
; /* Size of this structure. */
573 struct lttng_ust_channel_common_private
*priv
; /* Private channel interface */
575 enum lttng_ust_channel_type type
;
576 void *child
; /* Pointer to child, for inheritance by aggregation. */
579 struct lttng_ust_session
*session
;
581 /* End of base ABI. Fields below should be used after checking struct_size. */
584 struct lttng_ust_channel_buffer_private
;
587 * IMPORTANT: this structure is part of the ABI between the probe and
588 * UST. Fields need to be only added at the end, never reordered, never
591 * The field @struct_size should be used to determine the size of the
592 * structure. It should be queried before using additional fields added
593 * at the end of the structure.
595 struct lttng_ust_channel_buffer
{
596 uint32_t struct_size
; /* Size of this structure. */
598 struct lttng_ust_channel_common
*parent
; /* Inheritance by aggregation. */
599 struct lttng_ust_channel_buffer_private
*priv
; /* Private channel buffer interface */
601 struct lttng_ust_channel_buffer_ops
*ops
;
603 /* End of base ABI. Fields below should be used after checking struct_size. */
606 struct lttng_ust_channel_counter
;
607 struct lttng_ust_channel_counter_ops_private
;
610 * IMPORTANT: this structure is part of the ABI between the probe and
611 * UST. Fields need to be only added at the end, never reordered, never
614 * The field @struct_size should be used to determine the size of the
615 * structure. It should be queried before using additional fields added
616 * at the end of the structure.
618 struct lttng_ust_channel_counter_ops
{
619 uint32_t struct_size
;
621 struct lttng_ust_channel_counter_ops_private
*priv
; /* Private channel counter ops interface */
623 int (*counter_hit
)(struct lttng_ust_event_counter
*event_counter
,
624 const char *stack_data
,
625 struct lttng_ust_probe_ctx
*probe_ctx
,
626 struct lttng_ust_event_counter_ctx
*event_counter_ctx
);
628 /* End of base ABI. Fields below should be used after checking struct_size. */
632 * IMPORTANT: this structure is part of the ABI between the probe and
633 * UST. Fields need to be only added at the end, never reordered, never
636 * The field @struct_size should be used to determine the size of the
637 * structure. It should be queried before using additional fields added
638 * at the end of the structure.
640 struct lttng_ust_channel_counter
{
641 uint32_t struct_size
; /* Size of this structure. */
643 struct lttng_ust_channel_common
*parent
; /* Inheritance by aggregation. */
644 struct lttng_ust_channel_counter_private
*priv
; /* Private channel counter interface */
646 struct lttng_ust_channel_counter_ops
*ops
;
648 /* End of base ABI. Fields below should be used after checking struct_size. */
652 * IMPORTANT: this structure is part of the ABI between the probe and
653 * UST. Fields need to be only added at the end, never reordered, never
656 * The field @struct_size should be used to determine the size of the
657 * structure. It should be queried before using additional fields added
658 * at the end of the structure.
660 struct lttng_ust_stack_ctx
{
661 uint32_t struct_size
; /* Size of this structure */
663 struct lttng_ust_event_recorder
*event_recorder
;
665 /* End of base ABI. Fields below should be used after checking struct_size. */
668 struct lttng_ust_session_private
;
671 * IMPORTANT: this structure is part of the ABI between the probe and
672 * UST. Fields need to be only added at the end, never reordered, never
675 * The field @struct_size should be used to determine the size of the
676 * structure. It should be queried before using additional fields added
677 * at the end of the structure.
679 struct lttng_ust_session
{
680 uint32_t struct_size
; /* Size of this structure */
682 struct lttng_ust_session_private
*priv
; /* Private session interface */
684 int active
; /* Is trace session active ? */
686 /* End of base ABI. Fields below should be used after checking struct_size. */
690 * On successful registration of a probe, a pointer to an opaque
691 * structure is returned. This pointer should be passed to
692 * lttng_ust_probe_unregister for unregistration.
693 * lttng_ust_probe_register returns NULL on error.
695 struct lttng_ust_registered_probe
*lttng_ust_probe_register(const struct lttng_ust_probe_desc
*desc
);
697 void lttng_ust_probe_unregister(struct lttng_ust_registered_probe
*reg_probe
);
700 * Applications that change their procname and need the new value to be
701 * reflected in the procname event context have to call this function to clear
702 * the internally cached value. This should not be called from a signal
705 void lttng_ust_context_procname_reset(void);
708 struct lttng_ust_channel_common
*lttng_ust_get_chan_common_from_event_common(
709 struct lttng_ust_event_common
*event
)
711 switch (event
->type
) {
712 case LTTNG_UST_EVENT_TYPE_RECORDER
:
714 struct lttng_ust_event_recorder
*event_recorder
= (struct lttng_ust_event_recorder
*) event
->child
;
715 struct lttng_ust_channel_buffer
*chan_buf
= event_recorder
->chan
;
717 return chan_buf
->parent
;
719 case LTTNG_UST_EVENT_TYPE_COUNTER
:
721 struct lttng_ust_event_counter
*event_counter
= (struct lttng_ust_event_counter
*) event
->child
;
722 struct lttng_ust_channel_counter
*chan_counter
= event_counter
->chan
;
724 return chan_counter
->parent
;
735 #endif /* _LTTNG_UST_EVENTS_H */