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>
25 #error "LTTNG_PACKED should be defined"
32 #define LTTNG_UST_UUID_LEN 16
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.
40 #define LTTNG_UST_PROVIDER_MAJOR 2
41 #define LTTNG_UST_PROVIDER_MINOR 0
44 struct lttng_ust_session
;
45 struct lttng_ust_lib_ring_buffer_ctx
;
46 struct lttng_ust_event_field
;
49 * Data structures used by tracepoint event declarations, and by the
53 /* Type description */
56 lttng_ust_type_integer
,
57 lttng_ust_type_string
,
59 lttng_ust_type_dynamic
,
62 lttng_ust_type_sequence
,
63 lttng_ust_type_struct
,
67 enum lttng_ust_string_encoding
{
68 lttng_ust_string_encoding_none
= 0,
69 lttng_ust_string_encoding_UTF8
= 1,
70 lttng_ust_string_encoding_ASCII
= 2,
71 NR_LTTNG_UST_STRING_ENCODING
,
74 struct lttng_ust_enum_value
{
75 unsigned long long value
;
76 unsigned int signedness
:1;
79 enum lttng_ust_enum_entry_option
{
80 LTTNG_UST_ENUM_ENTRY_OPTION_IS_AUTO
= 1U << 0,
84 * Enumeration entry description
86 * IMPORTANT: this structure is part of the ABI between the probe and
87 * UST. Fields need to be only added at the end, never reordered, never
90 * The field @struct_size should be used to determine the size of the
91 * structure. It should be queried before using additional fields added
92 * at the end of the structure.
95 struct lttng_ust_enum_entry
{
98 struct lttng_ust_enum_value start
, end
; /* start and end are inclusive */
100 unsigned int options
;
102 /* End of base ABI. Fields below should be used after checking struct_size. */
106 * struct lttng_ust_type_common is fixed-size. Its children inherits
107 * from it by embedding struct lttng_ust_type_common as its first field.
109 struct lttng_ust_type_common
{
110 enum lttng_ust_type type
;
113 struct lttng_ust_type_integer
{
114 struct lttng_ust_type_common parent
;
115 uint32_t struct_size
;
116 unsigned int size
; /* in bits */
117 unsigned short alignment
; /* in bits */
118 unsigned int signedness
:1;
119 unsigned int reverse_byte_order
:1;
120 unsigned int base
; /* 2, 8, 10, 16, for pretty print */
123 #define lttng_ust_type_integer_define(_type, _byte_order, _base) \
124 ((struct lttng_ust_type_common *) __LTTNG_COMPOUND_LITERAL(struct lttng_ust_type_integer, { \
126 .type = lttng_ust_type_integer, \
128 .struct_size = sizeof(struct lttng_ust_type_integer), \
129 .size = sizeof(_type) * CHAR_BIT, \
130 .alignment = lttng_alignof(_type) * CHAR_BIT, \
131 .signedness = lttng_is_signed_type(_type), \
132 .reverse_byte_order = _byte_order != BYTE_ORDER, \
136 struct lttng_ust_type_float
{
137 struct lttng_ust_type_common parent
;
138 uint32_t struct_size
;
139 unsigned int exp_dig
; /* exponent digits, in bits */
140 unsigned int mant_dig
; /* mantissa digits, in bits */
141 unsigned short alignment
; /* in bits */
142 unsigned int reverse_byte_order
:1;
146 * Only float and double are supported. long double is not supported at
149 #define _float_mant_dig(_type) \
150 (sizeof(_type) == sizeof(float) ? FLT_MANT_DIG \
151 : (sizeof(_type) == sizeof(double) ? DBL_MANT_DIG \
154 #define lttng_ust_type_float_define(_type) \
155 ((struct lttng_ust_type_common *) __LTTNG_COMPOUND_LITERAL(struct lttng_ust_type_float, { \
157 .type = lttng_ust_type_float, \
159 .struct_size = sizeof(struct lttng_ust_type_float), \
160 .exp_dig = sizeof(_type) * CHAR_BIT \
161 - _float_mant_dig(_type), \
162 .mant_dig = _float_mant_dig(_type), \
163 .alignment = lttng_alignof(_type) * CHAR_BIT, \
164 .reverse_byte_order = BYTE_ORDER != FLOAT_WORD_ORDER, \
168 struct lttng_ust_type_string
{
169 struct lttng_ust_type_common parent
;
170 uint32_t struct_size
;
171 enum lttng_ust_string_encoding encoding
;
174 struct lttng_ust_type_enum
{
175 struct lttng_ust_type_common parent
;
176 uint32_t struct_size
;
177 struct lttng_ust_enum_desc
*desc
; /* Enumeration mapping */
178 struct lttng_ust_type_common
*container_type
;
181 struct lttng_ust_type_array
{
182 struct lttng_ust_type_common parent
;
183 uint32_t struct_size
;
184 struct lttng_ust_type_common
*elem_type
;
185 unsigned int length
; /* Num. elems. */
186 unsigned int alignment
;
187 enum lttng_ust_string_encoding encoding
;
190 struct lttng_ust_type_sequence
{
191 struct lttng_ust_type_common parent
;
192 uint32_t struct_size
;
193 const char *length_name
; /* Length field name. */
194 struct lttng_ust_type_common
*elem_type
;
195 unsigned int alignment
; /* Alignment before elements. */
196 enum lttng_ust_string_encoding encoding
;
199 struct lttng_ust_type_struct
{
200 struct lttng_ust_type_common parent
;
201 uint32_t struct_size
;
202 unsigned int nr_fields
;
203 struct lttng_ust_event_field
**fields
; /* Array of pointers to fields. */
204 unsigned int alignment
;
208 * Enumeration description
210 * IMPORTANT: this structure is part of the ABI between the probe and
211 * UST. Fields need to be only added at the end, never reordered, never
214 * The field @struct_size should be used to determine the size of the
215 * structure. It should be queried before using additional fields added
216 * at the end of the structure.
219 struct lttng_ust_enum_desc
{
220 uint32_t struct_size
;
223 struct lttng_ust_enum_entry
**entries
;
224 unsigned int nr_entries
;
226 /* End of base ABI. Fields below should be used after checking struct_size. */
230 * Event field description
232 * IMPORTANT: this structure is part of the ABI between the probe and
233 * UST. Fields need to be only added at the end, never reordered, never
236 * The field @struct_size should be used to determine the size of the
237 * structure. It should be queried before using additional fields added
238 * at the end of the structure.
241 struct lttng_ust_event_field
{
242 uint32_t struct_size
;
245 struct lttng_ust_type_common
*type
;
246 unsigned int nowrite
:1, /* do not write into trace */
247 nofilter
:1; /* do not consider for filter */
249 /* End of base ABI. Fields below should be used after checking struct_size. */
254 * IMPORTANT: this structure is part of the ABI between the probe and
255 * UST. Fields need to be only added at the end, never reordered, never
258 * The field @struct_size should be used to determine the size of the
259 * structure. It should be queried before using additional fields added
260 * at the end of the structure.
262 struct lttng_ust_event_desc
{
263 uint32_t struct_size
; /* Size of this structure. */
266 void (*probe_callback
)(void);
267 struct lttng_event_ctx
*ctx
; /* context */
268 struct lttng_ust_event_field
**fields
; /* event payload */
269 unsigned int nr_fields
;
270 const int **loglevel
;
271 const char *signature
; /* Argument types/names received */
272 const char **model_emf_uri
;
274 /* End of base ABI. Fields below should be used after checking struct_size. */
278 * IMPORTANT: this structure is part of the ABI between the probe and
279 * UST. Fields need to be only added at the end, never reordered, never
282 * The field @struct_size should be used to determine the size of the
283 * structure. It should be queried before using additional fields added
284 * at the end of the structure.
286 struct lttng_ust_probe_desc
{
287 uint32_t struct_size
; /* Size of this structure. */
289 const char *provider
;
290 struct lttng_ust_event_desc
**event_desc
;
291 unsigned int nr_events
;
292 struct cds_list_head head
; /* chain registered probes */
293 struct cds_list_head lazy_init_head
;
294 int lazy
; /* lazy registration */
298 /* End of base ABI. Fields below should be used after checking struct_size. */
301 /* Data structures used by the tracer. */
304 * Bytecode interpreter return value masks.
306 enum lttng_bytecode_interpreter_ret
{
307 LTTNG_INTERPRETER_DISCARD
= 0,
308 LTTNG_INTERPRETER_RECORD_FLAG
= (1ULL << 0),
309 /* Other bits are kept for future use. */
312 struct lttng_interpreter_output
;
313 struct lttng_ust_bytecode_runtime_private
;
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_runtime
{
325 uint32_t struct_size
; /* Size of this structure. */
327 struct lttng_ust_bytecode_runtime_private
*priv
;
328 /* Associated bytecode */
330 uint64_t (*filter
)(void *interpreter_data
,
331 const char *interpreter_stack_data
);
332 uint64_t (*capture
)(void *interpreter_data
,
333 const char *interpreter_stack_data
,
334 struct lttng_interpreter_output
*interpreter_output
);
336 struct cds_list_head node
; /* list of bytecode runtime in event */
338 /* End of base ABI. Fields below should be used after checking struct_size. */
342 * lttng_event structure is referred to by the tracing fast path. It
343 * must be kept small.
345 * IMPORTANT: this structure is part of the ABI between the probe and
346 * UST. Fields need to be only added at the end, never reordered, never
350 struct lttng_ust_ctx
;
351 struct lttng_ust_event_common_private
;
353 enum lttng_ust_event_type
{
354 LTTNG_UST_EVENT_TYPE_RECORDER
= 0,
355 LTTNG_UST_EVENT_TYPE_NOTIFIER
= 1,
359 * IMPORTANT: this structure is part of the ABI between the probe and
360 * UST. Fields need to be only added at the end, never reordered, never
363 * struct lttng_ust_event_common is the common ancestor of the various
364 * public event actions. Inheritance is done by composition: The parent
365 * has a pointer to its child, and the child has a pointer to its
366 * parent. Inheritance of those public structures is done by composition
367 * to ensure both parent and child structures can be extended.
369 * The field @struct_size should be used to determine the size of the
370 * structure. It should be queried before using additional fields added
371 * at the end of the structure.
373 struct lttng_ust_event_common
{
374 uint32_t struct_size
; /* Size of this structure. */
376 struct lttng_ust_event_common_private
*priv
; /* Private event interface */
378 enum lttng_ust_event_type type
;
379 void *child
; /* Pointer to child, for inheritance by aggregation. */
382 int has_enablers_without_bytecode
;
383 /* list of struct lttng_ust_bytecode_runtime, sorted by seqnum */
384 struct cds_list_head filter_bytecode_runtime_head
;
386 /* End of base ABI. Fields below should be used after checking struct_size. */
389 struct lttng_ust_event_recorder_private
;
392 * IMPORTANT: this structure is part of the ABI between the probe and
393 * UST. Fields need to be only added at the end, never reordered, never
396 * struct lttng_ust_event_recorder is the action for recording events
397 * into a ring buffer. It inherits from struct lttng_ust_event_common
398 * by composition to ensure both parent and child structure are
401 * The field @struct_size should be used to determine the size of the
402 * structure. It should be queried before using additional fields added
403 * at the end of the structure.
405 struct lttng_ust_event_recorder
{
406 uint32_t struct_size
; /* Size of this structure. */
408 struct lttng_ust_event_common
*parent
; /* Inheritance by aggregation. */
409 struct lttng_ust_event_recorder_private
*priv
; /* Private event record interface */
412 struct lttng_channel
*chan
;
413 struct lttng_ust_ctx
*ctx
;
415 /* End of base ABI. Fields below should be used after checking struct_size. */
418 struct lttng_ust_event_notifier_private
;
421 * IMPORTANT: this structure is part of the ABI between the probe and
422 * UST. Fields need to be only added at the end, never reordered, never
425 * struct lttng_ust_event_notifier is the action for sending
426 * notifications. It inherits from struct lttng_ust_event_common
427 * by composition to ensure both parent and child structure are
430 * The field @struct_size should be used to determine the size of the
431 * structure. It should be queried before using additional fields added
432 * at the end of the structure.
434 struct lttng_ust_event_notifier
{
435 uint32_t struct_size
; /* Size of this structure. */
437 struct lttng_ust_event_common
*parent
; /* Inheritance by aggregation. */
438 struct lttng_ust_event_notifier_private
*priv
; /* Private event notifier interface */
440 void (*notification_send
)(struct lttng_ust_event_notifier
*event_notifier
,
441 const char *stack_data
);
442 struct cds_list_head capture_bytecode_runtime_head
;
444 /* End of base ABI. Fields below should be used after checking struct_size. */
447 struct lttng_ust_lib_ring_buffer_channel
;
448 struct lttng_ust_shm_handle
;
449 struct lttng_ust_channel_ops_private
;
452 * IMPORTANT: this structure is part of the ABI between the probe and
453 * UST. Fields need to be only added at the end, never reordered, never
456 * The field @struct_size should be used to determine the size of the
457 * structure. It should be queried before using additional fields added
458 * at the end of the structure.
460 struct lttng_ust_channel_ops
{
461 uint32_t struct_size
;
463 struct lttng_ust_channel_ops_private
*priv
; /* Private channel ops interface */
465 int (*event_reserve
)(struct lttng_ust_lib_ring_buffer_ctx
*ctx
,
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 void (*event_strcpy
)(struct lttng_ust_lib_ring_buffer_ctx
*ctx
,
471 const char *src
, size_t len
);
473 /* End of base ABI. Fields below should be used after checking struct_size. */
477 * IMPORTANT: this structure is part of the ABI between the probe and
478 * UST. Fields need to be only added at the end, never reordered, never
481 struct lttng_channel
{
483 * The pointers located in this private data are NOT safe to be
484 * dereferenced by the consumer. The only operations the
485 * consumer process is designed to be allowed to do is to read
486 * and perform subbuffer flush.
488 struct lttng_ust_lib_ring_buffer_channel
*chan
; /* Channel buffers */
490 struct lttng_ust_ctx
*ctx
;
491 /* Event ID management */
492 struct lttng_ust_session
*session
;
493 int objd
; /* Object associated to channel */
494 struct cds_list_head node
; /* Channel list in session */
495 struct lttng_ust_channel_ops
*ops
;
496 int header_type
; /* 0: unset, 1: compact, 2: large */
497 struct lttng_ust_shm_handle
*handle
; /* shared-memory handle */
501 enum lttng_ust_abi_chan_type type
;
502 unsigned char uuid
[LTTNG_UST_UUID_LEN
]; /* Trace session unique ID */
503 int tstate
:1; /* Transient enable state */
507 * IMPORTANT: this structure is part of the ABI between the probe and
508 * UST. Fields need to be only added at the end, never reordered, never
511 * The field @struct_size should be used to determine the size of the
512 * structure. It should be queried before using additional fields added
513 * at the end of the structure.
515 struct lttng_ust_stack_ctx
{
516 uint32_t struct_size
; /* Size of this structure */
518 struct lttng_ust_event_recorder
*event_recorder
;
519 struct lttng_ust_ctx
*chan_ctx
; /* RCU dereferenced. */
520 struct lttng_ust_ctx
*event_ctx
; /* RCU dereferenced. */
522 /* End of base ABI. Fields below should be used after checking struct_size. */
525 struct lttng_ust_session_private
;
528 * IMPORTANT: this structure is part of the ABI between the probe and
529 * UST. Fields need to be only added at the end, never reordered, never
532 * The field @struct_size should be used to determine the size of the
533 * structure. It should be queried before using additional fields added
534 * at the end of the structure.
536 struct lttng_ust_session
{
537 uint32_t struct_size
; /* Size of this structure */
539 struct lttng_ust_session_private
*priv
; /* Private session interface */
541 int active
; /* Is trace session active ? */
543 /* End of base ABI. Fields below should be used after checking struct_size. */
546 int lttng_ust_probe_register(struct lttng_ust_probe_desc
*desc
);
547 void lttng_ust_probe_unregister(struct lttng_ust_probe_desc
*desc
);
550 * Applications that change their procname and need the new value to be
551 * reflected in the procname event context have to call this function to clear
552 * the internally cached value. This should not be called from a signal
555 void lttng_ust_context_procname_reset(void);
561 #endif /* _LTTNG_UST_EVENTS_H */