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>
29 #define LTTNG_UST_UUID_LEN 16
32 * Tracepoint provider version. Compatibility based on the major number.
33 * Older tracepoint providers can always register to newer lttng-ust
34 * library, but the opposite is rejected: a newer tracepoint provider is
35 * rejected by an older lttng-ust library.
37 #define LTTNG_UST_PROVIDER_MAJOR 2
38 #define LTTNG_UST_PROVIDER_MINOR 0
40 struct lttng_ust_channel_buffer
;
41 struct lttng_ust_session
;
42 struct lttng_ust_lib_ring_buffer_ctx
;
43 struct lttng_ust_event_field
;
46 * Data structures used by tracepoint event declarations, and by the
50 /* Type description */
53 lttng_ust_type_integer
,
54 lttng_ust_type_string
,
56 lttng_ust_type_dynamic
,
59 lttng_ust_type_sequence
,
60 lttng_ust_type_struct
,
64 enum lttng_ust_string_encoding
{
65 lttng_ust_string_encoding_none
= 0,
66 lttng_ust_string_encoding_UTF8
= 1,
67 lttng_ust_string_encoding_ASCII
= 2,
68 NR_LTTNG_UST_STRING_ENCODING
,
71 struct lttng_ust_enum_value
{
72 unsigned long long value
;
73 unsigned int signedness
:1;
76 enum lttng_ust_enum_entry_option
{
77 LTTNG_UST_ENUM_ENTRY_OPTION_IS_AUTO
= 1U << 0,
81 * Enumeration entry description
83 * IMPORTANT: this structure is part of the ABI between the probe and
84 * UST. Fields need to be only added at the end, never reordered, never
87 * The field @struct_size should be used to determine the size of the
88 * structure. It should be queried before using additional fields added
89 * at the end of the structure.
92 struct lttng_ust_enum_entry
{
95 struct lttng_ust_enum_value start
, end
; /* start and end are inclusive */
99 /* End of base ABI. Fields below should be used after checking struct_size. */
103 * struct lttng_ust_type_common is fixed-size. Its children inherits
104 * from it by embedding struct lttng_ust_type_common as its first field.
106 struct lttng_ust_type_common
{
107 enum lttng_ust_type type
;
110 struct lttng_ust_type_integer
{
111 struct lttng_ust_type_common parent
;
112 uint32_t struct_size
;
113 unsigned int size
; /* in bits */
114 unsigned short alignment
; /* in bits */
115 unsigned int signedness
:1;
116 unsigned int reverse_byte_order
:1;
117 unsigned int base
; /* 2, 8, 10, 16, for pretty print */
120 #define lttng_ust_type_integer_define(_type, _byte_order, _base) \
121 ((struct lttng_ust_type_common *) __LTTNG_COMPOUND_LITERAL(struct lttng_ust_type_integer, { \
123 .type = lttng_ust_type_integer, \
125 .struct_size = sizeof(struct lttng_ust_type_integer), \
126 .size = sizeof(_type) * CHAR_BIT, \
127 .alignment = lttng_ust_rb_alignof(_type) * CHAR_BIT, \
128 .signedness = lttng_ust_is_signed_type(_type), \
129 .reverse_byte_order = _byte_order != BYTE_ORDER, \
133 struct lttng_ust_type_float
{
134 struct lttng_ust_type_common parent
;
135 uint32_t struct_size
;
136 unsigned int exp_dig
; /* exponent digits, in bits */
137 unsigned int mant_dig
; /* mantissa digits, in bits */
138 unsigned short alignment
; /* in bits */
139 unsigned int reverse_byte_order
:1;
143 * Only float and double are supported. long double is not supported at
146 #define lttng_ust_float_mant_dig(_type) \
147 (sizeof(_type) == sizeof(float) ? FLT_MANT_DIG \
148 : (sizeof(_type) == sizeof(double) ? DBL_MANT_DIG \
151 #define lttng_ust_type_float_define(_type) \
152 ((struct lttng_ust_type_common *) __LTTNG_COMPOUND_LITERAL(struct lttng_ust_type_float, { \
154 .type = lttng_ust_type_float, \
156 .struct_size = sizeof(struct lttng_ust_type_float), \
157 .exp_dig = sizeof(_type) * CHAR_BIT \
158 - lttng_ust_float_mant_dig(_type), \
159 .mant_dig = lttng_ust_float_mant_dig(_type), \
160 .alignment = lttng_ust_rb_alignof(_type) * CHAR_BIT, \
161 .reverse_byte_order = BYTE_ORDER != FLOAT_WORD_ORDER, \
165 struct lttng_ust_type_string
{
166 struct lttng_ust_type_common parent
;
167 uint32_t struct_size
;
168 enum lttng_ust_string_encoding encoding
;
171 struct lttng_ust_type_enum
{
172 struct lttng_ust_type_common parent
;
173 uint32_t struct_size
;
174 struct lttng_ust_enum_desc
*desc
; /* Enumeration mapping */
175 struct lttng_ust_type_common
*container_type
;
178 struct lttng_ust_type_array
{
179 struct lttng_ust_type_common parent
;
180 uint32_t struct_size
;
181 struct lttng_ust_type_common
*elem_type
;
182 unsigned int length
; /* Num. elems. */
183 unsigned int alignment
;
184 enum lttng_ust_string_encoding encoding
;
187 struct lttng_ust_type_sequence
{
188 struct lttng_ust_type_common parent
;
189 uint32_t struct_size
;
190 const char *length_name
; /* Length field name. */
191 struct lttng_ust_type_common
*elem_type
;
192 unsigned int alignment
; /* Alignment before elements. */
193 enum lttng_ust_string_encoding encoding
;
196 struct lttng_ust_type_struct
{
197 struct lttng_ust_type_common parent
;
198 uint32_t struct_size
;
199 unsigned int nr_fields
;
200 struct lttng_ust_event_field
**fields
; /* Array of pointers to fields. */
201 unsigned int alignment
;
205 * Enumeration description
207 * IMPORTANT: this structure is part of the ABI between the probe and
208 * UST. Fields need to be only added at the end, never reordered, never
211 * The field @struct_size should be used to determine the size of the
212 * structure. It should be queried before using additional fields added
213 * at the end of the structure.
216 struct lttng_ust_enum_desc
{
217 uint32_t struct_size
;
220 struct lttng_ust_enum_entry
**entries
;
221 unsigned int nr_entries
;
223 /* End of base ABI. Fields below should be used after checking struct_size. */
227 * Event field description
229 * IMPORTANT: this structure is part of the ABI between the probe and
230 * UST. Fields need to be only added at the end, never reordered, never
233 * The field @struct_size should be used to determine the size of the
234 * structure. It should be queried before using additional fields added
235 * at the end of the structure.
238 struct lttng_ust_event_field
{
239 uint32_t struct_size
;
242 struct lttng_ust_type_common
*type
;
243 unsigned int nowrite
:1, /* do not write into trace */
244 nofilter
:1; /* do not consider for filter */
246 /* End of base ABI. Fields below should be used after checking struct_size. */
251 * IMPORTANT: this structure is part of the ABI between the probe and
252 * UST. Fields need to be only added at the end, never reordered, never
255 * The field @struct_size should be used to determine the size of the
256 * structure. It should be queried before using additional fields added
257 * at the end of the structure.
259 struct lttng_ust_event_desc
{
260 uint32_t struct_size
; /* Size of this structure. */
262 const char *event_name
;
263 struct lttng_ust_probe_desc
*probe_desc
;
264 void (*probe_callback
)(void);
265 struct lttng_event_ctx
*ctx
; /* context */
266 struct lttng_ust_event_field
**fields
; /* event payload */
267 unsigned int nr_fields
;
268 const int **loglevel
;
269 const char *signature
; /* Argument types/names received */
270 const char **model_emf_uri
;
272 /* End of base ABI. Fields below should be used after checking struct_size. */
276 * IMPORTANT: this structure is part of the ABI between the probe and
277 * UST. Fields need to be only added at the end, never reordered, never
280 * The field @struct_size should be used to determine the size of the
281 * structure. It should be queried before using additional fields added
282 * at the end of the structure.
284 struct lttng_ust_probe_desc
{
285 uint32_t struct_size
; /* Size of this structure. */
287 const char *provider_name
;
288 struct lttng_ust_event_desc
**event_desc
;
289 unsigned int nr_events
;
290 struct cds_list_head head
; /* chain registered probes */
291 struct cds_list_head lazy_init_head
;
292 int lazy
; /* lazy registration */
296 /* End of base ABI. Fields below should be used after checking struct_size. */
299 /* Data structures used by the tracer. */
302 * lttng_event structure is referred to by the tracing fast path. It
303 * must be kept small.
305 * IMPORTANT: this structure is part of the ABI between the probe and
306 * UST. Fields need to be only added at the end, never reordered, never
310 struct lttng_ust_ctx
;
311 struct lttng_ust_event_common_private
;
313 enum lttng_ust_event_type
{
314 LTTNG_UST_EVENT_TYPE_RECORDER
= 0,
315 LTTNG_UST_EVENT_TYPE_NOTIFIER
= 1,
319 * Result of the run_filter() callback.
321 enum lttng_ust_event_filter_result
{
322 LTTNG_UST_EVENT_FILTER_ACCEPT
= 0,
323 LTTNG_UST_EVENT_FILTER_REJECT
= 1,
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
331 * struct lttng_ust_event_common is the common ancestor of the various
332 * public event actions. Inheritance is done by composition: The parent
333 * has a pointer to its child, and the child has a pointer to its
334 * parent. Inheritance of those public structures is done by composition
335 * to ensure both parent and child structures can be extended.
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_event_common
{
342 uint32_t struct_size
; /* Size of this structure. */
344 struct lttng_ust_event_common_private
*priv
; /* Private event interface */
346 enum lttng_ust_event_type type
;
347 void *child
; /* Pointer to child, for inheritance by aggregation. */
350 int eval_filter
; /* Need to evaluate filters */
351 int (*run_filter
)(struct lttng_ust_event_common
*event
,
352 const char *stack_data
,
355 /* End of base ABI. Fields below should be used after checking struct_size. */
358 struct lttng_ust_event_recorder_private
;
361 * IMPORTANT: this structure is part of the ABI between the probe and
362 * UST. Fields need to be only added at the end, never reordered, never
365 * struct lttng_ust_event_recorder is the action for recording events
366 * into a ring buffer. It inherits from struct lttng_ust_event_common
367 * by composition to ensure both parent and child structure are
370 * The field @struct_size should be used to determine the size of the
371 * structure. It should be queried before using additional fields added
372 * at the end of the structure.
374 struct lttng_ust_event_recorder
{
375 uint32_t struct_size
; /* Size of this structure. */
377 struct lttng_ust_event_common
*parent
; /* Inheritance by aggregation. */
378 struct lttng_ust_event_recorder_private
*priv
; /* Private event record interface */
381 struct lttng_ust_channel_buffer
*chan
;
383 /* End of base ABI. Fields below should be used after checking struct_size. */
387 * IMPORTANT: this structure is part of the ABI between the probe and
388 * UST. Fields need to be only added at the end, never reordered, never
391 * The field @struct_size should be used to determine the size of the
392 * structure. It should be queried before using additional fields added
393 * at the end of the structure.
395 struct lttng_ust_notification_ctx
{
396 uint32_t struct_size
; /* Size of this structure. */
397 int eval_capture
; /* Capture evaluation available. */
399 /* End of base ABI. Fields below should be used after checking struct_size. */
402 struct lttng_ust_event_notifier_private
;
405 * IMPORTANT: this structure is part of the ABI between the probe and
406 * UST. Fields need to be only added at the end, never reordered, never
409 * struct lttng_ust_event_notifier is the action for sending
410 * notifications. It inherits from struct lttng_ust_event_common
411 * by composition to ensure both parent and child structure are
414 * The field @struct_size should be used to determine the size of the
415 * structure. It should be queried before using additional fields added
416 * at the end of the structure.
418 struct lttng_ust_event_notifier
{
419 uint32_t struct_size
; /* Size of this structure. */
421 struct lttng_ust_event_common
*parent
; /* Inheritance by aggregation. */
422 struct lttng_ust_event_notifier_private
*priv
; /* Private event notifier interface */
424 int eval_capture
; /* Need to evaluate capture */
425 void (*notification_send
)(struct lttng_ust_event_notifier
*event_notifier
,
426 const char *stack_data
,
427 struct lttng_ust_notification_ctx
*notif_ctx
);
429 /* End of base ABI. Fields below should be used after checking struct_size. */
432 struct lttng_ust_lib_ring_buffer_channel
;
433 struct lttng_ust_channel_buffer_ops_private
;
436 * IMPORTANT: this structure is part of the ABI between the probe and
437 * UST. Fields need to be only added at the end, never reordered, never
440 * The field @struct_size should be used to determine the size of the
441 * structure. It should be queried before using additional fields added
442 * at the end of the structure.
444 struct lttng_ust_channel_buffer_ops
{
445 uint32_t struct_size
;
447 struct lttng_ust_channel_buffer_ops_private
*priv
; /* Private channel buffer ops interface */
449 int (*event_reserve
)(struct lttng_ust_lib_ring_buffer_ctx
*ctx
,
451 void (*event_commit
)(struct lttng_ust_lib_ring_buffer_ctx
*ctx
);
452 void (*event_write
)(struct lttng_ust_lib_ring_buffer_ctx
*ctx
,
453 const void *src
, size_t len
);
454 void (*event_strcpy
)(struct lttng_ust_lib_ring_buffer_ctx
*ctx
,
455 const char *src
, size_t len
);
456 void (*event_pstrcpy_pad
)(struct lttng_ust_lib_ring_buffer_ctx
*ctx
,
457 const char *src
, size_t len
);
459 /* End of base ABI. Fields below should be used after checking struct_size. */
462 enum lttng_ust_channel_type
{
463 LTTNG_UST_CHANNEL_TYPE_BUFFER
= 0,
466 struct lttng_ust_channel_common_private
;
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
473 * The field @struct_size should be used to determine the size of the
474 * structure. It should be queried before using additional fields added
475 * at the end of the structure.
477 struct lttng_ust_channel_common
{
478 uint32_t struct_size
; /* Size of this structure. */
480 struct lttng_ust_channel_common_private
*priv
; /* Private channel interface */
482 enum lttng_ust_channel_type type
;
483 void *child
; /* Pointer to child, for inheritance by aggregation. */
486 struct lttng_ust_session
*session
;
488 /* End of base ABI. Fields below should be used after checking struct_size. */
491 struct lttng_ust_channel_buffer_private
;
494 * IMPORTANT: this structure is part of the ABI between the probe and
495 * UST. Fields need to be only added at the end, never reordered, never
498 * The field @struct_size should be used to determine the size of the
499 * structure. It should be queried before using additional fields added
500 * at the end of the structure.
502 struct lttng_ust_channel_buffer
{
503 uint32_t struct_size
; /* Size of this structure. */
505 struct lttng_ust_channel_common
*parent
; /* Inheritance by aggregation. */
506 struct lttng_ust_channel_buffer_private
*priv
; /* Private channel buffer interface */
508 struct lttng_ust_channel_buffer_ops
*ops
;
510 /* End of base ABI. Fields below should be used after checking struct_size. */
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_stack_ctx
{
523 uint32_t struct_size
; /* Size of this structure */
525 struct lttng_ust_event_recorder
*event_recorder
;
527 /* End of base ABI. Fields below should be used after checking struct_size. */
530 struct lttng_ust_session_private
;
533 * IMPORTANT: this structure is part of the ABI between the probe and
534 * UST. Fields need to be only added at the end, never reordered, never
537 * The field @struct_size should be used to determine the size of the
538 * structure. It should be queried before using additional fields added
539 * at the end of the structure.
541 struct lttng_ust_session
{
542 uint32_t struct_size
; /* Size of this structure */
544 struct lttng_ust_session_private
*priv
; /* Private session interface */
546 int active
; /* Is trace session active ? */
548 /* End of base ABI. Fields below should be used after checking struct_size. */
551 int lttng_ust_probe_register(struct lttng_ust_probe_desc
*desc
);
552 void lttng_ust_probe_unregister(struct lttng_ust_probe_desc
*desc
);
555 * Applications that change their procname and need the new value to be
556 * reflected in the procname event context have to call this function to clear
557 * the internally cached value. This should not be called from a signal
560 void lttng_ust_context_procname_reset(void);
566 #endif /* _LTTNG_UST_EVENTS_H */