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
12 #include <urcu/list.h>
13 #include <urcu/hlist.h>
16 #include <lttng/ust-abi.h>
17 #include <lttng/ust-tracer.h>
18 #include <lttng/ust-endian.h>
28 #define LTTNG_UST_UUID_LEN 16
31 * Tracepoint provider version. Compatibility based on the major number.
32 * Older tracepoint providers can always register to newer lttng-ust
33 * library, but the opposite is rejected: a newer tracepoint provider is
34 * rejected by an older lttng-ust library.
36 #define LTTNG_UST_PROVIDER_MAJOR 2
37 #define LTTNG_UST_PROVIDER_MINOR 0
39 struct lttng_ust_channel_buffer
;
40 struct lttng_ust_session
;
41 struct lttng_ust_lib_ring_buffer_ctx
;
42 struct lttng_ust_event_field
;
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_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_alignof(_type) * CHAR_BIT, \
127 .signedness = lttng_is_signed_type(_type), \
128 .reverse_byte_order = _byte_order != 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_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_alignof(_type) * CHAR_BIT, \
160 .reverse_byte_order = BYTE_ORDER != 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 struct lttng_ust_enum_desc
*desc
; /* Enumeration mapping */
174 struct lttng_ust_type_common
*container_type
;
177 struct lttng_ust_type_array
{
178 struct lttng_ust_type_common parent
;
179 uint32_t struct_size
;
180 struct lttng_ust_type_common
*elem_type
;
181 unsigned int length
; /* Num. elems. */
182 unsigned int alignment
;
183 enum lttng_ust_string_encoding encoding
;
186 struct lttng_ust_type_sequence
{
187 struct lttng_ust_type_common parent
;
188 uint32_t struct_size
;
189 const char *length_name
; /* Length field name. */
190 struct lttng_ust_type_common
*elem_type
;
191 unsigned int alignment
; /* Alignment before elements. */
192 enum lttng_ust_string_encoding encoding
;
195 struct lttng_ust_type_struct
{
196 struct lttng_ust_type_common parent
;
197 uint32_t struct_size
;
198 unsigned int nr_fields
;
199 struct lttng_ust_event_field
**fields
; /* Array of pointers to fields. */
200 unsigned int alignment
;
204 * Enumeration description
206 * IMPORTANT: this structure is part of the ABI between the probe and
207 * UST. Fields need to be only added at the end, never reordered, never
210 * The field @struct_size should be used to determine the size of the
211 * structure. It should be queried before using additional fields added
212 * at the end of the structure.
215 struct lttng_ust_enum_desc
{
216 uint32_t struct_size
;
219 struct lttng_ust_enum_entry
**entries
;
220 unsigned int nr_entries
;
222 /* End of base ABI. Fields below should be used after checking struct_size. */
226 * Event field description
228 * IMPORTANT: this structure is part of the ABI between the probe and
229 * UST. Fields need to be only added at the end, never reordered, never
232 * The field @struct_size should be used to determine the size of the
233 * structure. It should be queried before using additional fields added
234 * at the end of the structure.
237 struct lttng_ust_event_field
{
238 uint32_t struct_size
;
241 struct lttng_ust_type_common
*type
;
242 unsigned int nowrite
:1, /* do not write into trace */
243 nofilter
:1; /* do not consider for filter */
245 /* End of base ABI. Fields below should be used after checking struct_size. */
250 * IMPORTANT: this structure is part of the ABI between the probe and
251 * UST. Fields need to be only added at the end, never reordered, never
254 * The field @struct_size should be used to determine the size of the
255 * structure. It should be queried before using additional fields added
256 * at the end of the structure.
258 struct lttng_ust_event_desc
{
259 uint32_t struct_size
; /* Size of this structure. */
262 void (*probe_callback
)(void);
263 struct lttng_event_ctx
*ctx
; /* context */
264 struct lttng_ust_event_field
**fields
; /* event payload */
265 unsigned int nr_fields
;
266 const int **loglevel
;
267 const char *signature
; /* Argument types/names received */
268 const char **model_emf_uri
;
270 /* End of base ABI. Fields below should be used after checking struct_size. */
274 * IMPORTANT: this structure is part of the ABI between the probe and
275 * UST. Fields need to be only added at the end, never reordered, never
278 * The field @struct_size should be used to determine the size of the
279 * structure. It should be queried before using additional fields added
280 * at the end of the structure.
282 struct lttng_ust_probe_desc
{
283 uint32_t struct_size
; /* Size of this structure. */
285 const char *provider
;
286 struct lttng_ust_event_desc
**event_desc
;
287 unsigned int nr_events
;
288 struct cds_list_head head
; /* chain registered probes */
289 struct cds_list_head lazy_init_head
;
290 int lazy
; /* lazy registration */
294 /* End of base ABI. Fields below should be used after checking struct_size. */
297 /* Data structures used by the tracer. */
300 * Bytecode interpreter return value.
302 enum lttng_ust_bytecode_interpreter_ret
{
303 LTTNG_UST_BYTECODE_INTERPRETER_ERROR
= -1,
304 LTTNG_UST_BYTECODE_INTERPRETER_OK
= 0,
307 struct lttng_interpreter_output
;
308 struct lttng_ust_bytecode_runtime_private
;
310 enum lttng_ust_bytecode_filter_result
{
311 LTTNG_UST_BYTECODE_FILTER_ACCEPT
= 0,
312 LTTNG_UST_BYTECODE_FILTER_REJECT
= 1,
316 * IMPORTANT: this structure is part of the ABI between the probe and
317 * UST. Fields need to be only added at the end, never reordered, never
320 * The field @struct_size should be used to determine the size of the
321 * structure. It should be queried before using additional fields added
322 * at the end of the structure.
324 struct lttng_ust_bytecode_filter_ctx
{
325 uint32_t struct_size
; /* Size of this structure. */
327 enum lttng_ust_bytecode_filter_result result
;
329 /* End of base ABI. Fields below should be used after checking struct_size. */
333 * IMPORTANT: this structure is part of the ABI between the probe and
334 * UST. Fields need to be only added at the end, never reordered, never
337 * The field @struct_size should be used to determine the size of the
338 * structure. It should be queried before using additional fields added
339 * at the end of the structure.
341 struct lttng_ust_bytecode_runtime
{
342 uint32_t struct_size
; /* Size of this structure. */
344 struct lttng_ust_bytecode_runtime_private
*priv
;
345 int (*interpreter_func
)(struct lttng_ust_bytecode_runtime
*bytecode_runtime
,
346 const char *interpreter_stack_data
,
348 struct cds_list_head node
; /* list of bytecode runtime in event */
350 /* End of base ABI. Fields below should be used after checking struct_size. */
354 * lttng_event structure is referred to by the tracing fast path. It
355 * must be kept small.
357 * IMPORTANT: this structure is part of the ABI between the probe and
358 * UST. Fields need to be only added at the end, never reordered, never
362 struct lttng_ust_ctx
;
363 struct lttng_ust_event_common_private
;
365 enum lttng_ust_event_type
{
366 LTTNG_UST_EVENT_TYPE_RECORDER
= 0,
367 LTTNG_UST_EVENT_TYPE_NOTIFIER
= 1,
371 * IMPORTANT: this structure is part of the ABI between the probe and
372 * UST. Fields need to be only added at the end, never reordered, never
375 * struct lttng_ust_event_common is the common ancestor of the various
376 * public event actions. Inheritance is done by composition: The parent
377 * has a pointer to its child, and the child has a pointer to its
378 * parent. Inheritance of those public structures is done by composition
379 * to ensure both parent and child structures can be extended.
381 * The field @struct_size should be used to determine the size of the
382 * structure. It should be queried before using additional fields added
383 * at the end of the structure.
385 struct lttng_ust_event_common
{
386 uint32_t struct_size
; /* Size of this structure. */
388 struct lttng_ust_event_common_private
*priv
; /* Private event interface */
390 enum lttng_ust_event_type type
;
391 void *child
; /* Pointer to child, for inheritance by aggregation. */
394 int has_enablers_without_bytecode
;
395 /* list of struct lttng_ust_bytecode_runtime, sorted by seqnum */
396 struct cds_list_head filter_bytecode_runtime_head
;
398 /* End of base ABI. Fields below should be used after checking struct_size. */
401 struct lttng_ust_event_recorder_private
;
404 * IMPORTANT: this structure is part of the ABI between the probe and
405 * UST. Fields need to be only added at the end, never reordered, never
408 * struct lttng_ust_event_recorder is the action for recording events
409 * into a ring buffer. It inherits from struct lttng_ust_event_common
410 * by composition to ensure both parent and child structure are
413 * The field @struct_size should be used to determine the size of the
414 * structure. It should be queried before using additional fields added
415 * at the end of the structure.
417 struct lttng_ust_event_recorder
{
418 uint32_t struct_size
; /* Size of this structure. */
420 struct lttng_ust_event_common
*parent
; /* Inheritance by aggregation. */
421 struct lttng_ust_event_recorder_private
*priv
; /* Private event record interface */
424 struct lttng_ust_channel_buffer
*chan
;
426 /* End of base ABI. Fields below should be used after checking struct_size. */
429 struct lttng_ust_event_notifier_private
;
432 * IMPORTANT: this structure is part of the ABI between the probe and
433 * UST. Fields need to be only added at the end, never reordered, never
436 * struct lttng_ust_event_notifier is the action for sending
437 * notifications. It inherits from struct lttng_ust_event_common
438 * by composition to ensure both parent and child structure are
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_notifier
{
446 uint32_t struct_size
; /* Size of this structure. */
448 struct lttng_ust_event_common
*parent
; /* Inheritance by aggregation. */
449 struct lttng_ust_event_notifier_private
*priv
; /* Private event notifier interface */
451 void (*notification_send
)(struct lttng_ust_event_notifier
*event_notifier
,
452 const char *stack_data
);
453 struct cds_list_head capture_bytecode_runtime_head
;
455 /* End of base ABI. Fields below should be used after checking struct_size. */
458 struct lttng_ust_lib_ring_buffer_channel
;
459 struct lttng_ust_channel_ops_private
;
462 * IMPORTANT: this structure is part of the ABI between the probe and
463 * UST. Fields need to be only added at the end, never reordered, never
466 * The field @struct_size should be used to determine the size of the
467 * structure. It should be queried before using additional fields added
468 * at the end of the structure.
470 struct lttng_ust_channel_ops
{
471 uint32_t struct_size
;
473 struct lttng_ust_channel_ops_private
*priv
; /* Private channel ops interface */
475 int (*event_reserve
)(struct lttng_ust_lib_ring_buffer_ctx
*ctx
,
477 void (*event_commit
)(struct lttng_ust_lib_ring_buffer_ctx
*ctx
);
478 void (*event_write
)(struct lttng_ust_lib_ring_buffer_ctx
*ctx
,
479 const void *src
, size_t len
);
480 void (*event_strcpy
)(struct lttng_ust_lib_ring_buffer_ctx
*ctx
,
481 const char *src
, size_t len
);
483 /* End of base ABI. Fields below should be used after checking struct_size. */
486 enum lttng_ust_channel_type
{
487 LTTNG_UST_CHANNEL_TYPE_BUFFER
= 0,
490 struct lttng_ust_channel_common_private
;
493 * IMPORTANT: this structure is part of the ABI between the probe and
494 * UST. Fields need to be only added at the end, never reordered, never
497 * The field @struct_size should be used to determine the size of the
498 * structure. It should be queried before using additional fields added
499 * at the end of the structure.
501 struct lttng_ust_channel_common
{
502 uint32_t struct_size
; /* Size of this structure. */
504 struct lttng_ust_channel_common_private
*priv
; /* Private channel interface */
506 enum lttng_ust_channel_type type
;
507 void *child
; /* Pointer to child, for inheritance by aggregation. */
510 struct lttng_ust_session
*session
;
512 /* End of base ABI. Fields below should be used after checking struct_size. */
515 struct lttng_ust_channel_buffer_private
;
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
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.
526 struct lttng_ust_channel_buffer
{
527 uint32_t struct_size
; /* Size of this structure. */
529 struct lttng_ust_channel_common
*parent
; /* Inheritance by aggregation. */
530 struct lttng_ust_channel_buffer_private
*priv
; /* Private channel buffer interface */
532 struct lttng_ust_channel_ops
*ops
;
533 struct lttng_ust_lib_ring_buffer_channel
*chan
; /* Channel buffers */
534 struct lttng_ust_shm_handle
*handle
; /* shared-memory handle */
536 /* End of base ABI. Fields below should be used after checking struct_size. */
540 * IMPORTANT: this structure is part of the ABI between the probe and
541 * UST. Fields need to be only added at the end, never reordered, never
544 * The field @struct_size should be used to determine the size of the
545 * structure. It should be queried before using additional fields added
546 * at the end of the structure.
548 struct lttng_ust_stack_ctx
{
549 uint32_t struct_size
; /* Size of this structure */
551 struct lttng_ust_event_recorder
*event_recorder
;
553 /* End of base ABI. Fields below should be used after checking struct_size. */
556 struct lttng_ust_session_private
;
559 * IMPORTANT: this structure is part of the ABI between the probe and
560 * UST. Fields need to be only added at the end, never reordered, never
563 * The field @struct_size should be used to determine the size of the
564 * structure. It should be queried before using additional fields added
565 * at the end of the structure.
567 struct lttng_ust_session
{
568 uint32_t struct_size
; /* Size of this structure */
570 struct lttng_ust_session_private
*priv
; /* Private session interface */
572 int active
; /* Is trace session active ? */
574 /* End of base ABI. Fields below should be used after checking struct_size. */
577 int lttng_ust_probe_register(struct lttng_ust_probe_desc
*desc
);
578 void lttng_ust_probe_unregister(struct lttng_ust_probe_desc
*desc
);
581 * Applications that change their procname and need the new value to be
582 * reflected in the procname event context have to call this function to clear
583 * the internally cached value. This should not be called from a signal
586 void lttng_ust_context_procname_reset(void);
592 #endif /* _LTTNG_UST_EVENTS_H */