sequence type: use previous field for length if length_name is NULL
[lttng-ust.git] / include / lttng / ust-events.h
1 /*
2 * SPDX-License-Identifier: MIT
3 *
4 * Copyright (C) 2010-2012 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
5 *
6 * Holds LTTng per-session event registry.
7 */
8
9 #ifndef _LTTNG_UST_EVENTS_H
10 #define _LTTNG_UST_EVENTS_H
11
12 #include <stddef.h>
13 #include <stdint.h>
14 #include <lttng/ust-abi.h>
15 #include <lttng/ust-tracer.h>
16 #include <lttng/ust-endian.h>
17 #include <float.h>
18 #include <errno.h>
19 #include <urcu/ref.h>
20 #include <pthread.h>
21 #include <limits.h>
22
23 #ifdef __cplusplus
24 extern "C" {
25 #endif
26
27 #define LTTNG_UST_UUID_LEN 16
28
29 /*
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.
34 */
35 #define LTTNG_UST_PROVIDER_MAJOR 2
36 #define LTTNG_UST_PROVIDER_MINOR 0
37
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;
43
44 /*
45 * Data structures used by tracepoint event declarations, and by the
46 * tracer.
47 */
48
49 /* Type description */
50
51 enum lttng_ust_type {
52 lttng_ust_type_integer,
53 lttng_ust_type_string,
54 lttng_ust_type_float,
55 lttng_ust_type_dynamic,
56 lttng_ust_type_enum,
57 lttng_ust_type_array,
58 lttng_ust_type_sequence,
59 lttng_ust_type_struct,
60 NR_LTTNG_UST_TYPE,
61 };
62
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,
68 };
69
70 struct lttng_ust_enum_value {
71 unsigned long long value;
72 unsigned int signedness:1;
73 };
74
75 enum lttng_ust_enum_entry_option {
76 LTTNG_UST_ENUM_ENTRY_OPTION_IS_AUTO = 1U << 0,
77 };
78
79 /*
80 * Enumeration entry description
81 *
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
84 * removed.
85 *
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.
89 */
90
91 struct lttng_ust_enum_entry {
92 uint32_t struct_size;
93
94 struct lttng_ust_enum_value start, end; /* start and end are inclusive */
95 const char *string;
96 unsigned int options;
97
98 /* End of base ABI. Fields below should be used after checking struct_size. */
99 };
100
101 /*
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.
104 */
105 struct lttng_ust_type_common {
106 enum lttng_ust_type type;
107 };
108
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 */
117 };
118
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, { \
121 .parent = { \
122 .type = lttng_ust_type_integer, \
123 }, \
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, \
129 .base = _base, \
130 }))
131
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;
139 };
140
141 /*
142 * Only float and double are supported. long double is not supported at
143 * the moment.
144 */
145 #define lttng_ust_float_mant_dig(_type) \
146 (sizeof(_type) == sizeof(float) ? FLT_MANT_DIG \
147 : (sizeof(_type) == sizeof(double) ? DBL_MANT_DIG \
148 : 0))
149
150 #define lttng_ust_type_float_define(_type) \
151 ((struct lttng_ust_type_common *) LTTNG_UST_COMPOUND_LITERAL(struct lttng_ust_type_float, { \
152 .parent = { \
153 .type = lttng_ust_type_float, \
154 }, \
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, \
161 }))
162
163
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;
168 };
169
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;
175 };
176
177 /*
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
181 * larger alignment.
182 */
183
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;
191 };
192
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;
200 };
201
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. */
208 };
209
210 /*
211 * Enumeration description
212 *
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
215 * removed.
216 *
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.
220 */
221
222 struct lttng_ust_enum_desc {
223 uint32_t struct_size;
224
225 const char *name;
226 const struct lttng_ust_enum_entry * const *entries;
227 unsigned int nr_entries;
228
229 /* End of base ABI. Fields below should be used after checking struct_size. */
230 };
231
232 /*
233 * Event field description
234 *
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
237 * removed.
238 *
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.
242 */
243
244 struct lttng_ust_event_field {
245 uint32_t struct_size;
246
247 const char *name;
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 */
251
252 /* End of base ABI. Fields below should be used after checking struct_size. */
253 };
254
255
256 /*
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
259 * removed.
260 *
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.
264 */
265 struct lttng_ust_event_desc {
266 uint32_t struct_size; /* Size of this structure. */
267
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;
276
277 /* End of base ABI. Fields below should be used after checking struct_size. */
278 };
279
280 /*
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
283 * removed.
284 *
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.
288 */
289 struct lttng_ust_probe_desc {
290 uint32_t struct_size; /* Size of this structure. */
291
292 const char *provider_name;
293 const struct lttng_ust_event_desc * const *event_desc;
294 unsigned int nr_events;
295 uint32_t major;
296 uint32_t minor;
297
298 /* End of base ABI. Fields below should be used after checking struct_size. */
299 };
300
301 /* Data structures used by the tracer. */
302
303 /*
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
306 * removed.
307 *
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.
311 *
312 * The probe_ctx is not const because it may be extended to add future
313 * fields which could be modified by callbacks.
314 */
315 struct lttng_ust_probe_ctx {
316 uint32_t struct_size; /* Size of this structure. */
317
318 void *ip; /* caller ip address */
319
320 /* End of base ABI. Fields below should be used after checking struct_size. */
321 };
322
323 /*
324 * lttng_event structure is referred to by the tracing fast path. It
325 * must be kept small.
326 *
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
329 * removed.
330 */
331
332 struct lttng_ust_event_common_private;
333
334 enum lttng_ust_event_type {
335 LTTNG_UST_EVENT_TYPE_RECORDER = 0,
336 LTTNG_UST_EVENT_TYPE_NOTIFIER = 1,
337 };
338
339 /*
340 * Result of the run_filter() callback.
341 */
342 enum lttng_ust_event_filter_result {
343 LTTNG_UST_EVENT_FILTER_ACCEPT = 0,
344 LTTNG_UST_EVENT_FILTER_REJECT = 1,
345 };
346
347 /*
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
350 * removed.
351 *
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.
357 *
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.
361 */
362 struct lttng_ust_event_common {
363 uint32_t struct_size; /* Size of this structure. */
364
365 struct lttng_ust_event_common_private *priv; /* Private event interface */
366
367 enum lttng_ust_event_type type;
368 void *child; /* Pointer to child, for inheritance by aggregation. */
369
370 int enabled;
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,
375 void *filter_ctx);
376
377 /* End of base ABI. Fields below should be used after checking struct_size. */
378 };
379
380 struct lttng_ust_event_recorder_private;
381
382 /*
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
385 * removed.
386 *
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
390 * extensible.
391 *
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.
395 */
396 struct lttng_ust_event_recorder {
397 uint32_t struct_size; /* Size of this structure. */
398
399 struct lttng_ust_event_common *parent; /* Inheritance by aggregation. */
400 struct lttng_ust_event_recorder_private *priv; /* Private event record interface */
401
402 struct lttng_ust_channel_buffer *chan;
403
404 /* End of base ABI. Fields below should be used after checking struct_size. */
405 };
406
407 /*
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
410 * removed.
411 *
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.
415 */
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. */
420 };
421
422 struct lttng_ust_event_notifier_private;
423
424 /*
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
427 * removed.
428 *
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
432 * extensible.
433 *
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.
437 */
438 struct lttng_ust_event_notifier {
439 uint32_t struct_size; /* Size of this structure. */
440
441 struct lttng_ust_event_common *parent; /* Inheritance by aggregation. */
442 struct lttng_ust_event_notifier_private *priv; /* Private event notifier interface */
443
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);
449
450 /* End of base ABI. Fields below should be used after checking struct_size. */
451 };
452
453 struct lttng_ust_ring_buffer_channel;
454 struct lttng_ust_channel_buffer_ops_private;
455
456 /*
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
459 * removed.
460 *
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.
464 */
465 struct lttng_ust_channel_buffer_ops {
466 uint32_t struct_size;
467
468 struct lttng_ust_channel_buffer_ops_private *priv; /* Private channel buffer ops interface */
469
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);
478
479 /* End of base ABI. Fields below should be used after checking struct_size. */
480 };
481
482 enum lttng_ust_channel_type {
483 LTTNG_UST_CHANNEL_TYPE_BUFFER = 0,
484 };
485
486 struct lttng_ust_channel_common_private;
487
488 /*
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
491 * removed.
492 *
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.
496 */
497 struct lttng_ust_channel_common {
498 uint32_t struct_size; /* Size of this structure. */
499
500 struct lttng_ust_channel_common_private *priv; /* Private channel interface */
501
502 enum lttng_ust_channel_type type;
503 void *child; /* Pointer to child, for inheritance by aggregation. */
504
505 int enabled;
506 struct lttng_ust_session *session;
507
508 /* End of base ABI. Fields below should be used after checking struct_size. */
509 };
510
511 struct lttng_ust_channel_buffer_private;
512
513 /*
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
516 * removed.
517 *
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.
521 */
522 struct lttng_ust_channel_buffer {
523 uint32_t struct_size; /* Size of this structure. */
524
525 struct lttng_ust_channel_common *parent; /* Inheritance by aggregation. */
526 struct lttng_ust_channel_buffer_private *priv; /* Private channel buffer interface */
527
528 struct lttng_ust_channel_buffer_ops *ops;
529
530 /* End of base ABI. Fields below should be used after checking struct_size. */
531 };
532
533 /*
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
536 * removed.
537 *
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.
541 */
542 struct lttng_ust_stack_ctx {
543 uint32_t struct_size; /* Size of this structure */
544
545 struct lttng_ust_event_recorder *event_recorder;
546
547 /* End of base ABI. Fields below should be used after checking struct_size. */
548 };
549
550 struct lttng_ust_session_private;
551
552 /*
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
555 * removed.
556 *
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.
560 */
561 struct lttng_ust_session {
562 uint32_t struct_size; /* Size of this structure */
563
564 struct lttng_ust_session_private *priv; /* Private session interface */
565
566 int active; /* Is trace session active ? */
567
568 /* End of base ABI. Fields below should be used after checking struct_size. */
569 };
570
571 /*
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.
576 */
577 struct lttng_ust_registered_probe *lttng_ust_probe_register(const struct lttng_ust_probe_desc *desc);
578
579 void lttng_ust_probe_unregister(struct lttng_ust_registered_probe *reg_probe);
580
581 /*
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
585 * handler.
586 */
587 void lttng_ust_context_procname_reset(void);
588
589 #ifdef __cplusplus
590 }
591 #endif
592
593 #endif /* _LTTNG_UST_EVENTS_H */
This page took 0.042797 seconds and 5 git commands to generate.