Refactoring: hide internal fields of ring buffer context
[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 <urcu/list.h>
13 #include <urcu/hlist.h>
14 #include <stddef.h>
15 #include <stdint.h>
16 #include <lttng/ust-abi.h>
17 #include <lttng/ust-tracer.h>
18 #include <lttng/ust-endian.h>
19 #include <float.h>
20 #include <errno.h>
21 #include <urcu/ref.h>
22 #include <pthread.h>
23 #include <limits.h>
24
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28
29 #define LTTNG_UST_UUID_LEN 16
30
31 /*
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.
36 */
37 #define LTTNG_UST_PROVIDER_MAJOR 2
38 #define LTTNG_UST_PROVIDER_MINOR 0
39
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;
44
45 /*
46 * Data structures used by tracepoint event declarations, and by the
47 * tracer.
48 */
49
50 /* Type description */
51
52 enum lttng_ust_type {
53 lttng_ust_type_integer,
54 lttng_ust_type_string,
55 lttng_ust_type_float,
56 lttng_ust_type_dynamic,
57 lttng_ust_type_enum,
58 lttng_ust_type_array,
59 lttng_ust_type_sequence,
60 lttng_ust_type_struct,
61 NR_LTTNG_UST_TYPE,
62 };
63
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,
69 };
70
71 struct lttng_ust_enum_value {
72 unsigned long long value;
73 unsigned int signedness:1;
74 };
75
76 enum lttng_ust_enum_entry_option {
77 LTTNG_UST_ENUM_ENTRY_OPTION_IS_AUTO = 1U << 0,
78 };
79
80 /*
81 * Enumeration entry description
82 *
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
85 * removed.
86 *
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.
90 */
91
92 struct lttng_ust_enum_entry {
93 uint32_t struct_size;
94
95 struct lttng_ust_enum_value start, end; /* start and end are inclusive */
96 const char *string;
97 unsigned int options;
98
99 /* End of base ABI. Fields below should be used after checking struct_size. */
100 };
101
102 /*
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.
105 */
106 struct lttng_ust_type_common {
107 enum lttng_ust_type type;
108 };
109
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 */
118 };
119
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, { \
122 .parent = { \
123 .type = lttng_ust_type_integer, \
124 }, \
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, \
130 .base = _base, \
131 }))
132
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;
140 };
141
142 /*
143 * Only float and double are supported. long double is not supported at
144 * the moment.
145 */
146 #define lttng_ust_float_mant_dig(_type) \
147 (sizeof(_type) == sizeof(float) ? FLT_MANT_DIG \
148 : (sizeof(_type) == sizeof(double) ? DBL_MANT_DIG \
149 : 0))
150
151 #define lttng_ust_type_float_define(_type) \
152 ((struct lttng_ust_type_common *) __LTTNG_COMPOUND_LITERAL(struct lttng_ust_type_float, { \
153 .parent = { \
154 .type = lttng_ust_type_float, \
155 }, \
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, \
162 }))
163
164
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;
169 };
170
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;
176 };
177
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;
185 };
186
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;
194 };
195
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;
202 };
203
204 /*
205 * Enumeration description
206 *
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
209 * removed.
210 *
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.
214 */
215
216 struct lttng_ust_enum_desc {
217 uint32_t struct_size;
218
219 const char *name;
220 struct lttng_ust_enum_entry **entries;
221 unsigned int nr_entries;
222
223 /* End of base ABI. Fields below should be used after checking struct_size. */
224 };
225
226 /*
227 * Event field description
228 *
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
231 * removed.
232 *
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.
236 */
237
238 struct lttng_ust_event_field {
239 uint32_t struct_size;
240
241 const char *name;
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 */
245
246 /* End of base ABI. Fields below should be used after checking struct_size. */
247 };
248
249
250 /*
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
253 * removed.
254 *
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.
258 */
259 struct lttng_ust_event_desc {
260 uint32_t struct_size; /* Size of this structure. */
261
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;
271
272 /* End of base ABI. Fields below should be used after checking struct_size. */
273 };
274
275 /*
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
278 * removed.
279 *
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.
283 */
284 struct lttng_ust_probe_desc {
285 uint32_t struct_size; /* Size of this structure. */
286
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 */
293 uint32_t major;
294 uint32_t minor;
295
296 /* End of base ABI. Fields below should be used after checking struct_size. */
297 };
298
299 /* Data structures used by the tracer. */
300
301 /*
302 * lttng_event structure is referred to by the tracing fast path. It
303 * must be kept small.
304 *
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
307 * removed.
308 */
309
310 struct lttng_ust_ctx;
311 struct lttng_ust_event_common_private;
312
313 enum lttng_ust_event_type {
314 LTTNG_UST_EVENT_TYPE_RECORDER = 0,
315 LTTNG_UST_EVENT_TYPE_NOTIFIER = 1,
316 };
317
318 /*
319 * Result of the run_filter() callback.
320 */
321 enum lttng_ust_event_filter_result {
322 LTTNG_UST_EVENT_FILTER_ACCEPT = 0,
323 LTTNG_UST_EVENT_FILTER_REJECT = 1,
324 };
325
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 * 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.
336 *
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.
340 */
341 struct lttng_ust_event_common {
342 uint32_t struct_size; /* Size of this structure. */
343
344 struct lttng_ust_event_common_private *priv; /* Private event interface */
345
346 enum lttng_ust_event_type type;
347 void *child; /* Pointer to child, for inheritance by aggregation. */
348
349 int enabled;
350 int eval_filter; /* Need to evaluate filters */
351 int (*run_filter)(struct lttng_ust_event_common *event,
352 const char *stack_data,
353 void *filter_ctx);
354
355 /* End of base ABI. Fields below should be used after checking struct_size. */
356 };
357
358 struct lttng_ust_event_recorder_private;
359
360 /*
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
363 * removed.
364 *
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
368 * extensible.
369 *
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.
373 */
374 struct lttng_ust_event_recorder {
375 uint32_t struct_size; /* Size of this structure. */
376
377 struct lttng_ust_event_common *parent; /* Inheritance by aggregation. */
378 struct lttng_ust_event_recorder_private *priv; /* Private event record interface */
379
380 struct lttng_ust_channel_buffer *chan;
381
382 /* End of base ABI. Fields below should be used after checking struct_size. */
383 };
384
385 /*
386 * IMPORTANT: this structure is part of the ABI between the probe and
387 * UST. Fields need to be only added at the end, never reordered, never
388 * removed.
389 *
390 * The field @struct_size should be used to determine the size of the
391 * structure. It should be queried before using additional fields added
392 * at the end of the structure.
393 */
394 struct lttng_ust_notification_ctx {
395 uint32_t struct_size; /* Size of this structure. */
396 int eval_capture; /* Capture evaluation available. */
397
398 /* End of base ABI. Fields below should be used after checking struct_size. */
399 };
400
401 struct lttng_ust_event_notifier_private;
402
403 /*
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
406 * removed.
407 *
408 * struct lttng_ust_event_notifier is the action for sending
409 * notifications. It inherits from struct lttng_ust_event_common
410 * by composition to ensure both parent and child structure are
411 * extensible.
412 *
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.
416 */
417 struct lttng_ust_event_notifier {
418 uint32_t struct_size; /* Size of this structure. */
419
420 struct lttng_ust_event_common *parent; /* Inheritance by aggregation. */
421 struct lttng_ust_event_notifier_private *priv; /* Private event notifier interface */
422
423 int eval_capture; /* Need to evaluate capture */
424 void (*notification_send)(struct lttng_ust_event_notifier *event_notifier,
425 const char *stack_data,
426 struct lttng_ust_notification_ctx *notif_ctx);
427
428 /* End of base ABI. Fields below should be used after checking struct_size. */
429 };
430
431 struct lttng_ust_lib_ring_buffer_channel;
432 struct lttng_ust_channel_buffer_ops_private;
433
434 /*
435 * IMPORTANT: this structure is part of the ABI between the probe and
436 * UST. Fields need to be only added at the end, never reordered, never
437 * removed.
438 *
439 * The field @struct_size should be used to determine the size of the
440 * structure. It should be queried before using additional fields added
441 * at the end of the structure.
442 */
443 struct lttng_ust_channel_buffer_ops {
444 uint32_t struct_size;
445
446 struct lttng_ust_channel_buffer_ops_private *priv; /* Private channel buffer ops interface */
447
448 int (*event_reserve)(struct lttng_ust_lib_ring_buffer_ctx *ctx);
449 void (*event_commit)(struct lttng_ust_lib_ring_buffer_ctx *ctx);
450 void (*event_write)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
451 const void *src, size_t len, size_t alignment);
452 void (*event_strcpy)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
453 const char *src, size_t len);
454 void (*event_pstrcpy_pad)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
455 const char *src, size_t len);
456
457 /* End of base ABI. Fields below should be used after checking struct_size. */
458 };
459
460 enum lttng_ust_channel_type {
461 LTTNG_UST_CHANNEL_TYPE_BUFFER = 0,
462 };
463
464 struct lttng_ust_channel_common_private;
465
466 /*
467 * IMPORTANT: this structure is part of the ABI between the probe and
468 * UST. Fields need to be only added at the end, never reordered, never
469 * removed.
470 *
471 * The field @struct_size should be used to determine the size of the
472 * structure. It should be queried before using additional fields added
473 * at the end of the structure.
474 */
475 struct lttng_ust_channel_common {
476 uint32_t struct_size; /* Size of this structure. */
477
478 struct lttng_ust_channel_common_private *priv; /* Private channel interface */
479
480 enum lttng_ust_channel_type type;
481 void *child; /* Pointer to child, for inheritance by aggregation. */
482
483 int enabled;
484 struct lttng_ust_session *session;
485
486 /* End of base ABI. Fields below should be used after checking struct_size. */
487 };
488
489 struct lttng_ust_channel_buffer_private;
490
491 /*
492 * IMPORTANT: this structure is part of the ABI between the probe and
493 * UST. Fields need to be only added at the end, never reordered, never
494 * removed.
495 *
496 * The field @struct_size should be used to determine the size of the
497 * structure. It should be queried before using additional fields added
498 * at the end of the structure.
499 */
500 struct lttng_ust_channel_buffer {
501 uint32_t struct_size; /* Size of this structure. */
502
503 struct lttng_ust_channel_common *parent; /* Inheritance by aggregation. */
504 struct lttng_ust_channel_buffer_private *priv; /* Private channel buffer interface */
505
506 struct lttng_ust_channel_buffer_ops *ops;
507
508 /* End of base ABI. Fields below should be used after checking struct_size. */
509 };
510
511 /*
512 * IMPORTANT: this structure is part of the ABI between the probe and
513 * UST. Fields need to be only added at the end, never reordered, never
514 * removed.
515 *
516 * The field @struct_size should be used to determine the size of the
517 * structure. It should be queried before using additional fields added
518 * at the end of the structure.
519 */
520 struct lttng_ust_stack_ctx {
521 uint32_t struct_size; /* Size of this structure */
522
523 struct lttng_ust_event_recorder *event_recorder;
524
525 /* End of base ABI. Fields below should be used after checking struct_size. */
526 };
527
528 struct lttng_ust_session_private;
529
530 /*
531 * IMPORTANT: this structure is part of the ABI between the probe and
532 * UST. Fields need to be only added at the end, never reordered, never
533 * removed.
534 *
535 * The field @struct_size should be used to determine the size of the
536 * structure. It should be queried before using additional fields added
537 * at the end of the structure.
538 */
539 struct lttng_ust_session {
540 uint32_t struct_size; /* Size of this structure */
541
542 struct lttng_ust_session_private *priv; /* Private session interface */
543
544 int active; /* Is trace session active ? */
545
546 /* End of base ABI. Fields below should be used after checking struct_size. */
547 };
548
549 int lttng_ust_probe_register(struct lttng_ust_probe_desc *desc);
550 void lttng_ust_probe_unregister(struct lttng_ust_probe_desc *desc);
551
552 /*
553 * Applications that change their procname and need the new value to be
554 * reflected in the procname event context have to call this function to clear
555 * the internally cached value. This should not be called from a signal
556 * handler.
557 */
558 void lttng_ust_context_procname_reset(void);
559
560 #ifdef __cplusplus
561 }
562 #endif
563
564 #endif /* _LTTNG_UST_EVENTS_H */
This page took 0.054888 seconds and 5 git commands to generate.