2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2012 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
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 #define LTTNG_UST_PROVIDER_MAJOR 2
36 #define LTTNG_UST_PROVIDER_MINOR 0
38 struct lttng_ust_channel_buffer
;
39 struct lttng_ust_session
;
40 struct lttng_ust_ring_buffer_ctx
;
41 struct lttng_ust_event_field
;
42 struct lttng_ust_registered_probe
;
45 * Data structures used by tracepoint event declarations, and by the
49 /* Type description */
52 lttng_ust_type_integer
,
53 lttng_ust_type_string
,
55 lttng_ust_type_dynamic
,
58 lttng_ust_type_sequence
,
59 lttng_ust_type_struct
,
63 enum lttng_ust_string_encoding
{
64 lttng_ust_string_encoding_none
= 0,
65 lttng_ust_string_encoding_UTF8
= 1,
66 lttng_ust_string_encoding_ASCII
= 2,
67 NR_LTTNG_UST_STRING_ENCODING
,
70 struct lttng_ust_enum_value
{
71 unsigned long long value
;
72 unsigned int signedness
:1;
75 enum lttng_ust_enum_entry_option
{
76 LTTNG_UST_ENUM_ENTRY_OPTION_IS_AUTO
= 1U << 0,
80 * Enumeration entry description
82 * IMPORTANT: this structure is part of the ABI between the probe and
83 * UST. Fields need to be only added at the end, never reordered, never
86 * The field @struct_size should be used to determine the size of the
87 * structure. It should be queried before using additional fields added
88 * at the end of the structure.
91 struct lttng_ust_enum_entry
{
94 struct lttng_ust_enum_value start
, end
; /* start and end are inclusive */
98 /* End of base ABI. Fields below should be used after checking struct_size. */
102 * struct lttng_ust_type_common is fixed-size. Its children inherits
103 * from it by embedding struct lttng_ust_type_common as its first field.
105 struct lttng_ust_type_common
{
106 enum lttng_ust_type type
;
109 struct lttng_ust_type_integer
{
110 struct lttng_ust_type_common parent
;
111 uint32_t struct_size
;
112 unsigned int size
; /* in bits */
113 unsigned short alignment
; /* in bits */
114 unsigned int signedness
:1;
115 unsigned int reverse_byte_order
:1;
116 unsigned int base
; /* 2, 8, 10, 16, for pretty print */
119 #define lttng_ust_type_integer_define(_type, _byte_order, _base) \
120 ((struct lttng_ust_type_common *) LTTNG_UST_COMPOUND_LITERAL(struct lttng_ust_type_integer, { \
122 .type = lttng_ust_type_integer, \
124 .struct_size = sizeof(struct lttng_ust_type_integer), \
125 .size = sizeof(_type) * CHAR_BIT, \
126 .alignment = lttng_ust_rb_alignof(_type) * CHAR_BIT, \
127 .signedness = lttng_ust_is_signed_type(_type), \
128 .reverse_byte_order = _byte_order != LTTNG_UST_BYTE_ORDER, \
132 struct lttng_ust_type_float
{
133 struct lttng_ust_type_common parent
;
134 uint32_t struct_size
;
135 unsigned int exp_dig
; /* exponent digits, in bits */
136 unsigned int mant_dig
; /* mantissa digits, in bits */
137 unsigned short alignment
; /* in bits */
138 unsigned int reverse_byte_order
:1;
142 * Only float and double are supported. long double is not supported at
145 #define lttng_ust_float_mant_dig(_type) \
146 (sizeof(_type) == sizeof(float) ? FLT_MANT_DIG \
147 : (sizeof(_type) == sizeof(double) ? DBL_MANT_DIG \
150 #define lttng_ust_type_float_define(_type) \
151 ((struct lttng_ust_type_common *) LTTNG_UST_COMPOUND_LITERAL(struct lttng_ust_type_float, { \
153 .type = lttng_ust_type_float, \
155 .struct_size = sizeof(struct lttng_ust_type_float), \
156 .exp_dig = sizeof(_type) * CHAR_BIT \
157 - lttng_ust_float_mant_dig(_type), \
158 .mant_dig = lttng_ust_float_mant_dig(_type), \
159 .alignment = lttng_ust_rb_alignof(_type) * CHAR_BIT, \
160 .reverse_byte_order = LTTNG_UST_BYTE_ORDER != LTTNG_UST_FLOAT_WORD_ORDER, \
164 struct lttng_ust_type_string
{
165 struct lttng_ust_type_common parent
;
166 uint32_t struct_size
;
167 enum lttng_ust_string_encoding encoding
;
170 struct lttng_ust_type_enum
{
171 struct lttng_ust_type_common parent
;
172 uint32_t struct_size
;
173 const struct lttng_ust_enum_desc
*desc
; /* Enumeration mapping */
174 const struct lttng_ust_type_common
*container_type
;
178 * The alignment field in structure, array, and sequence types is a
179 * minimum alignment requirement. The actual alignment of a type may be
180 * larger than this explicit alignment value if its nested types have a
184 struct lttng_ust_type_array
{
185 struct lttng_ust_type_common parent
;
186 uint32_t struct_size
;
187 const struct lttng_ust_type_common
*elem_type
;
188 unsigned int length
; /* Num. elems. */
189 unsigned int alignment
; /* Minimum alignment for this type. */
190 enum lttng_ust_string_encoding encoding
;
193 struct lttng_ust_type_sequence
{
194 struct lttng_ust_type_common parent
;
195 uint32_t struct_size
;
196 const char *length_name
; /* Length field name. If NULL, use previous field. */
197 const struct lttng_ust_type_common
*elem_type
;
198 unsigned int alignment
; /* Minimum alignment before elements. */
199 enum lttng_ust_string_encoding encoding
;
202 struct lttng_ust_type_struct
{
203 struct lttng_ust_type_common parent
;
204 uint32_t struct_size
;
205 unsigned int nr_fields
;
206 const struct lttng_ust_event_field
* const *fields
; /* Array of pointers to fields. */
207 unsigned int alignment
; /* Minimum alignment for this type. */
211 * Enumeration description
213 * IMPORTANT: this structure is part of the ABI between the probe and
214 * UST. Fields need to be only added at the end, never reordered, never
217 * The field @struct_size should be used to determine the size of the
218 * structure. It should be queried before using additional fields added
219 * at the end of the structure.
222 struct lttng_ust_enum_desc
{
223 uint32_t struct_size
;
226 const struct lttng_ust_enum_entry
* const *entries
;
227 unsigned int nr_entries
;
229 /* End of base ABI. Fields below should be used after checking struct_size. */
233 * Event field description
235 * IMPORTANT: this structure is part of the ABI between the probe and
236 * UST. Fields need to be only added at the end, never reordered, never
239 * The field @struct_size should be used to determine the size of the
240 * structure. It should be queried before using additional fields added
241 * at the end of the structure.
244 struct lttng_ust_event_field
{
245 uint32_t struct_size
;
248 const struct lttng_ust_type_common
*type
;
249 unsigned int nowrite
:1, /* do not write into trace */
250 nofilter
:1; /* do not consider for filter */
252 /* End of base ABI. Fields below should be used after checking struct_size. */
257 * IMPORTANT: this structure is part of the ABI between the probe and
258 * UST. Fields need to be only added at the end, never reordered, never
261 * The field @struct_size should be used to determine the size of the
262 * structure. It should be queried before using additional fields added
263 * at the end of the structure.
265 struct lttng_ust_event_desc
{
266 uint32_t struct_size
; /* Size of this structure. */
268 const char *event_name
;
269 const struct lttng_ust_probe_desc
*probe_desc
;
270 void (*probe_callback
)(void);
271 const struct lttng_ust_event_field
* const *fields
; /* event payload */
272 unsigned int nr_fields
;
273 const int **loglevel
;
274 const char *signature
; /* Argument types/names received */
275 const char **model_emf_uri
;
277 /* End of base ABI. Fields below should be used after checking struct_size. */
281 * IMPORTANT: this structure is part of the ABI between the probe and
282 * UST. Fields need to be only added at the end, never reordered, never
285 * The field @struct_size should be used to determine the size of the
286 * structure. It should be queried before using additional fields added
287 * at the end of the structure.
289 struct lttng_ust_probe_desc
{
290 uint32_t struct_size
; /* Size of this structure. */
292 const char *provider_name
;
293 const struct lttng_ust_event_desc
* const *event_desc
;
294 unsigned int nr_events
;
298 /* End of base ABI. Fields below should be used after checking struct_size. */
301 /* Data structures used by the tracer. */
304 * IMPORTANT: this structure is part of the ABI between the probe and
305 * UST. Fields need to be only added at the end, never reordered, never
308 * The field @struct_size should be used to determine the size of the
309 * structure. It should be queried before using additional fields added
310 * at the end of the structure.
312 * The probe_ctx is not const because it may be extended to add future
313 * fields which could be modified by callbacks.
315 struct lttng_ust_probe_ctx
{
316 uint32_t struct_size
; /* Size of this structure. */
318 void *ip
; /* caller ip address */
320 /* End of base ABI. Fields below should be used after checking struct_size. */
324 * lttng_event structure is referred to by the tracing fast path. It
325 * must be kept small.
327 * IMPORTANT: this structure is part of the ABI between the probe and
328 * UST. Fields need to be only added at the end, never reordered, never
332 struct lttng_ust_event_common_private
;
334 enum lttng_ust_event_type
{
335 LTTNG_UST_EVENT_TYPE_RECORDER
= 0,
336 LTTNG_UST_EVENT_TYPE_NOTIFIER
= 1,
340 * Result of the run_filter() callback.
342 enum lttng_ust_event_filter_result
{
343 LTTNG_UST_EVENT_FILTER_ACCEPT
= 0,
344 LTTNG_UST_EVENT_FILTER_REJECT
= 1,
348 * IMPORTANT: this structure is part of the ABI between the probe and
349 * UST. Fields need to be only added at the end, never reordered, never
352 * struct lttng_ust_event_common is the common ancestor of the various
353 * public event actions. Inheritance is done by composition: The parent
354 * has a pointer to its child, and the child has a pointer to its
355 * parent. Inheritance of those public structures is done by composition
356 * to ensure both parent and child structures can be extended.
358 * The field @struct_size should be used to determine the size of the
359 * structure. It should be queried before using additional fields added
360 * at the end of the structure.
362 struct lttng_ust_event_common
{
363 uint32_t struct_size
; /* Size of this structure. */
365 struct lttng_ust_event_common_private
*priv
; /* Private event interface */
367 enum lttng_ust_event_type type
;
368 void *child
; /* Pointer to child, for inheritance by aggregation. */
371 int eval_filter
; /* Need to evaluate filters */
372 int (*run_filter
)(const struct lttng_ust_event_common
*event
,
373 const char *stack_data
,
374 struct lttng_ust_probe_ctx
*probe_ctx
,
377 /* End of base ABI. Fields below should be used after checking struct_size. */
380 struct lttng_ust_event_recorder_private
;
383 * IMPORTANT: this structure is part of the ABI between the probe and
384 * UST. Fields need to be only added at the end, never reordered, never
387 * struct lttng_ust_event_recorder is the action for recording events
388 * into a ring buffer. It inherits from struct lttng_ust_event_common
389 * by composition to ensure both parent and child structure are
392 * The field @struct_size should be used to determine the size of the
393 * structure. It should be queried before using additional fields added
394 * at the end of the structure.
396 struct lttng_ust_event_recorder
{
397 uint32_t struct_size
; /* Size of this structure. */
399 struct lttng_ust_event_common
*parent
; /* Inheritance by aggregation. */
400 struct lttng_ust_event_recorder_private
*priv
; /* Private event record interface */
402 struct lttng_ust_channel_buffer
*chan
;
404 /* End of base ABI. Fields below should be used after checking struct_size. */
408 * IMPORTANT: this structure is part of the ABI between the probe and
409 * UST. Fields need to be only added at the end, never reordered, never
412 * The field @struct_size should be used to determine the size of the
413 * structure. It should be queried before using additional fields added
414 * at the end of the structure.
416 struct lttng_ust_notification_ctx
{
417 uint32_t struct_size
; /* Size of this structure. */
418 int eval_capture
; /* Capture evaluation available. */
419 /* End of base ABI. Fields below should be used after checking struct_size. */
422 struct lttng_ust_event_notifier_private
;
425 * IMPORTANT: this structure is part of the ABI between the probe and
426 * UST. Fields need to be only added at the end, never reordered, never
429 * struct lttng_ust_event_notifier is the action for sending
430 * notifications. It inherits from struct lttng_ust_event_common
431 * by composition to ensure both parent and child structure are
434 * The field @struct_size should be used to determine the size of the
435 * structure. It should be queried before using additional fields added
436 * at the end of the structure.
438 struct lttng_ust_event_notifier
{
439 uint32_t struct_size
; /* Size of this structure. */
441 struct lttng_ust_event_common
*parent
; /* Inheritance by aggregation. */
442 struct lttng_ust_event_notifier_private
*priv
; /* Private event notifier interface */
444 int eval_capture
; /* Need to evaluate capture */
445 void (*notification_send
)(const struct lttng_ust_event_notifier
*event_notifier
,
446 const char *stack_data
,
447 struct lttng_ust_probe_ctx
*probe_ctx
,
448 struct lttng_ust_notification_ctx
*notif_ctx
);
450 /* End of base ABI. Fields below should be used after checking struct_size. */
453 struct lttng_ust_ring_buffer_channel
;
454 struct lttng_ust_channel_buffer_ops_private
;
457 * IMPORTANT: this structure is part of the ABI between the probe and
458 * UST. Fields need to be only added at the end, never reordered, never
461 * The field @struct_size should be used to determine the size of the
462 * structure. It should be queried before using additional fields added
463 * at the end of the structure.
465 struct lttng_ust_channel_buffer_ops
{
466 uint32_t struct_size
;
468 struct lttng_ust_channel_buffer_ops_private
*priv
; /* Private channel buffer ops interface */
470 int (*event_reserve
)(struct lttng_ust_ring_buffer_ctx
*ctx
);
471 void (*event_commit
)(struct lttng_ust_ring_buffer_ctx
*ctx
);
472 void (*event_write
)(struct lttng_ust_ring_buffer_ctx
*ctx
,
473 const void *src
, size_t len
, size_t alignment
);
474 void (*event_strcpy
)(struct lttng_ust_ring_buffer_ctx
*ctx
,
475 const char *src
, size_t len
);
476 void (*event_pstrcpy_pad
)(struct lttng_ust_ring_buffer_ctx
*ctx
,
477 const char *src
, size_t len
);
479 /* End of base ABI. Fields below should be used after checking struct_size. */
482 enum lttng_ust_channel_type
{
483 LTTNG_UST_CHANNEL_TYPE_BUFFER
= 0,
486 struct lttng_ust_channel_common_private
;
489 * IMPORTANT: this structure is part of the ABI between the probe and
490 * UST. Fields need to be only added at the end, never reordered, never
493 * The field @struct_size should be used to determine the size of the
494 * structure. It should be queried before using additional fields added
495 * at the end of the structure.
497 struct lttng_ust_channel_common
{
498 uint32_t struct_size
; /* Size of this structure. */
500 struct lttng_ust_channel_common_private
*priv
; /* Private channel interface */
502 enum lttng_ust_channel_type type
;
503 void *child
; /* Pointer to child, for inheritance by aggregation. */
506 struct lttng_ust_session
*session
;
508 /* End of base ABI. Fields below should be used after checking struct_size. */
511 struct lttng_ust_channel_buffer_private
;
514 * IMPORTANT: this structure is part of the ABI between the probe and
515 * UST. Fields need to be only added at the end, never reordered, never
518 * The field @struct_size should be used to determine the size of the
519 * structure. It should be queried before using additional fields added
520 * at the end of the structure.
522 struct lttng_ust_channel_buffer
{
523 uint32_t struct_size
; /* Size of this structure. */
525 struct lttng_ust_channel_common
*parent
; /* Inheritance by aggregation. */
526 struct lttng_ust_channel_buffer_private
*priv
; /* Private channel buffer interface */
528 struct lttng_ust_channel_buffer_ops
*ops
;
530 /* End of base ABI. Fields below should be used after checking struct_size. */
534 * IMPORTANT: this structure is part of the ABI between the probe and
535 * UST. Fields need to be only added at the end, never reordered, never
538 * The field @struct_size should be used to determine the size of the
539 * structure. It should be queried before using additional fields added
540 * at the end of the structure.
542 struct lttng_ust_stack_ctx
{
543 uint32_t struct_size
; /* Size of this structure */
545 struct lttng_ust_event_recorder
*event_recorder
;
547 /* End of base ABI. Fields below should be used after checking struct_size. */
550 struct lttng_ust_session_private
;
553 * IMPORTANT: this structure is part of the ABI between the probe and
554 * UST. Fields need to be only added at the end, never reordered, never
557 * The field @struct_size should be used to determine the size of the
558 * structure. It should be queried before using additional fields added
559 * at the end of the structure.
561 struct lttng_ust_session
{
562 uint32_t struct_size
; /* Size of this structure */
564 struct lttng_ust_session_private
*priv
; /* Private session interface */
566 int active
; /* Is trace session active ? */
568 /* End of base ABI. Fields below should be used after checking struct_size. */
572 * On successful registration of a probe, a pointer to an opaque
573 * structure is returned. This pointer should be passed to
574 * lttng_ust_probe_unregister for unregistration.
575 * lttng_ust_probe_register returns NULL on error.
577 struct lttng_ust_registered_probe
*lttng_ust_probe_register(const struct lttng_ust_probe_desc
*desc
);
579 void lttng_ust_probe_unregister(struct lttng_ust_registered_probe
*reg_probe
);
582 * Applications that change their procname and need the new value to be
583 * reflected in the procname event context have to call this function to clear
584 * the internally cached value. This should not be called from a signal
587 void lttng_ust_context_procname_reset(void);
593 #endif /* _LTTNG_UST_EVENTS_H */