Refactoring: bytecode interpreter ABI
[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
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27
28 #define LTTNG_UST_UUID_LEN 16
29
30 /*
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.
35 */
36 #define LTTNG_UST_PROVIDER_MAJOR 2
37 #define LTTNG_UST_PROVIDER_MINOR 0
38
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;
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_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_alignof(_type) * CHAR_BIT, \
127 .signedness = lttng_is_signed_type(_type), \
128 .reverse_byte_order = _byte_order != 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_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_alignof(_type) * CHAR_BIT, \
160 .reverse_byte_order = BYTE_ORDER != 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 struct lttng_ust_enum_desc *desc; /* Enumeration mapping */
174 struct lttng_ust_type_common *container_type;
175 };
176
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;
184 };
185
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;
193 };
194
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;
201 };
202
203 /*
204 * Enumeration description
205 *
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
208 * removed.
209 *
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.
213 */
214
215 struct lttng_ust_enum_desc {
216 uint32_t struct_size;
217
218 const char *name;
219 struct lttng_ust_enum_entry **entries;
220 unsigned int nr_entries;
221
222 /* End of base ABI. Fields below should be used after checking struct_size. */
223 };
224
225 /*
226 * Event field description
227 *
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
230 * removed.
231 *
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.
235 */
236
237 struct lttng_ust_event_field {
238 uint32_t struct_size;
239
240 const char *name;
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 */
244
245 /* End of base ABI. Fields below should be used after checking struct_size. */
246 };
247
248
249 /*
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
252 * removed.
253 *
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.
257 */
258 struct lttng_ust_event_desc {
259 uint32_t struct_size; /* Size of this structure. */
260
261 const char *name;
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;
269
270 /* End of base ABI. Fields below should be used after checking struct_size. */
271 };
272
273 /*
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
276 * removed.
277 *
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.
281 */
282 struct lttng_ust_probe_desc {
283 uint32_t struct_size; /* Size of this structure. */
284
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 */
291 uint32_t major;
292 uint32_t minor;
293
294 /* End of base ABI. Fields below should be used after checking struct_size. */
295 };
296
297 /* Data structures used by the tracer. */
298
299 /*
300 * Bytecode interpreter return value.
301 */
302 enum lttng_ust_bytecode_interpreter_ret {
303 LTTNG_UST_BYTECODE_INTERPRETER_ERROR = -1,
304 LTTNG_UST_BYTECODE_INTERPRETER_OK = 0,
305 };
306
307 struct lttng_interpreter_output;
308 struct lttng_ust_bytecode_runtime_private;
309
310 enum lttng_ust_bytecode_filter_result {
311 LTTNG_UST_BYTECODE_FILTER_ACCEPT = 0,
312 LTTNG_UST_BYTECODE_FILTER_REJECT = 1,
313 };
314
315 /*
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
318 * removed.
319 *
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.
323 */
324 struct lttng_ust_bytecode_filter_ctx {
325 uint32_t struct_size; /* Size of this structure. */
326
327 enum lttng_ust_bytecode_filter_result result;
328
329 /* End of base ABI. Fields below should be used after checking struct_size. */
330 };
331
332 /*
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
335 * removed.
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_bytecode_runtime {
342 uint32_t struct_size; /* Size of this structure. */
343
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,
347 void *ctx);
348 struct cds_list_head node; /* list of bytecode runtime in event */
349
350 /* End of base ABI. Fields below should be used after checking struct_size. */
351 };
352
353 /*
354 * lttng_event structure is referred to by the tracing fast path. It
355 * must be kept small.
356 *
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
359 * removed.
360 */
361
362 struct lttng_ust_ctx;
363 struct lttng_ust_event_common_private;
364
365 enum lttng_ust_event_type {
366 LTTNG_UST_EVENT_TYPE_RECORDER = 0,
367 LTTNG_UST_EVENT_TYPE_NOTIFIER = 1,
368 };
369
370 /*
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
373 * removed.
374 *
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.
380 *
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.
384 */
385 struct lttng_ust_event_common {
386 uint32_t struct_size; /* Size of this structure. */
387
388 struct lttng_ust_event_common_private *priv; /* Private event interface */
389
390 enum lttng_ust_event_type type;
391 void *child; /* Pointer to child, for inheritance by aggregation. */
392
393 int enabled;
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;
397
398 /* End of base ABI. Fields below should be used after checking struct_size. */
399 };
400
401 struct lttng_ust_event_recorder_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_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
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_recorder {
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_recorder_private *priv; /* Private event record interface */
422
423 unsigned int id;
424 struct lttng_ust_channel_buffer *chan;
425
426 /* End of base ABI. Fields below should be used after checking struct_size. */
427 };
428
429 struct lttng_ust_event_notifier_private;
430
431 /*
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
434 * removed.
435 *
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
439 * extensible.
440 *
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.
444 */
445 struct lttng_ust_event_notifier {
446 uint32_t struct_size; /* Size of this structure. */
447
448 struct lttng_ust_event_common *parent; /* Inheritance by aggregation. */
449 struct lttng_ust_event_notifier_private *priv; /* Private event notifier interface */
450
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;
454
455 /* End of base ABI. Fields below should be used after checking struct_size. */
456 };
457
458 struct lttng_ust_lib_ring_buffer_channel;
459 struct lttng_ust_channel_ops_private;
460
461 /*
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
464 * removed.
465 *
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.
469 */
470 struct lttng_ust_channel_ops {
471 uint32_t struct_size;
472
473 struct lttng_ust_channel_ops_private *priv; /* Private channel ops interface */
474
475 int (*event_reserve)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
476 uint32_t event_id);
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);
482
483 /* End of base ABI. Fields below should be used after checking struct_size. */
484 };
485
486 enum lttng_ust_channel_type {
487 LTTNG_UST_CHANNEL_TYPE_BUFFER = 0,
488 };
489
490 struct lttng_ust_channel_common_private;
491
492 /*
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
495 * removed.
496 *
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.
500 */
501 struct lttng_ust_channel_common {
502 uint32_t struct_size; /* Size of this structure. */
503
504 struct lttng_ust_channel_common_private *priv; /* Private channel interface */
505
506 enum lttng_ust_channel_type type;
507 void *child; /* Pointer to child, for inheritance by aggregation. */
508
509 int enabled;
510 struct lttng_ust_session *session;
511
512 /* End of base ABI. Fields below should be used after checking struct_size. */
513 };
514
515 struct lttng_ust_channel_buffer_private;
516
517 /*
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
520 * removed.
521 *
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.
525 */
526 struct lttng_ust_channel_buffer {
527 uint32_t struct_size; /* Size of this structure. */
528
529 struct lttng_ust_channel_common *parent; /* Inheritance by aggregation. */
530 struct lttng_ust_channel_buffer_private *priv; /* Private channel buffer interface */
531
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 */
535
536 /* End of base ABI. Fields below should be used after checking struct_size. */
537 };
538
539 /*
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
542 * removed.
543 *
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.
547 */
548 struct lttng_ust_stack_ctx {
549 uint32_t struct_size; /* Size of this structure */
550
551 struct lttng_ust_event_recorder *event_recorder;
552
553 /* End of base ABI. Fields below should be used after checking struct_size. */
554 };
555
556 struct lttng_ust_session_private;
557
558 /*
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
561 * removed.
562 *
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.
566 */
567 struct lttng_ust_session {
568 uint32_t struct_size; /* Size of this structure */
569
570 struct lttng_ust_session_private *priv; /* Private session interface */
571
572 int active; /* Is trace session active ? */
573
574 /* End of base ABI. Fields below should be used after checking struct_size. */
575 };
576
577 int lttng_ust_probe_register(struct lttng_ust_probe_desc *desc);
578 void lttng_ust_probe_unregister(struct lttng_ust_probe_desc *desc);
579
580 /*
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
584 * handler.
585 */
586 void lttng_ust_context_procname_reset(void);
587
588 #ifdef __cplusplus
589 }
590 #endif
591
592 #endif /* _LTTNG_UST_EVENTS_H */
This page took 0.04437 seconds and 5 git commands to generate.