ABI refactoring: sequence and array of text: copy input as string
[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 * lttng_event structure is referred to by the tracing fast path. It
301 * must be kept small.
302 *
303 * IMPORTANT: this structure is part of the ABI between the probe and
304 * UST. Fields need to be only added at the end, never reordered, never
305 * removed.
306 */
307
308 struct lttng_ust_ctx;
309 struct lttng_ust_event_common_private;
310
311 enum lttng_ust_event_type {
312 LTTNG_UST_EVENT_TYPE_RECORDER = 0,
313 LTTNG_UST_EVENT_TYPE_NOTIFIER = 1,
314 };
315
316 /*
317 * Result of the run_filter() callback.
318 */
319 enum lttng_ust_event_filter_result {
320 LTTNG_UST_EVENT_FILTER_ACCEPT = 0,
321 LTTNG_UST_EVENT_FILTER_REJECT = 1,
322 };
323
324 /*
325 * IMPORTANT: this structure is part of the ABI between the probe and
326 * UST. Fields need to be only added at the end, never reordered, never
327 * removed.
328 *
329 * struct lttng_ust_event_common is the common ancestor of the various
330 * public event actions. Inheritance is done by composition: The parent
331 * has a pointer to its child, and the child has a pointer to its
332 * parent. Inheritance of those public structures is done by composition
333 * to ensure both parent and child structures can be extended.
334 *
335 * The field @struct_size should be used to determine the size of the
336 * structure. It should be queried before using additional fields added
337 * at the end of the structure.
338 */
339 struct lttng_ust_event_common {
340 uint32_t struct_size; /* Size of this structure. */
341
342 struct lttng_ust_event_common_private *priv; /* Private event interface */
343
344 enum lttng_ust_event_type type;
345 void *child; /* Pointer to child, for inheritance by aggregation. */
346
347 int enabled;
348 int eval_filter; /* Need to evaluate filters */
349 int (*run_filter)(struct lttng_ust_event_common *event,
350 const char *stack_data,
351 void *filter_ctx);
352
353 /* End of base ABI. Fields below should be used after checking struct_size. */
354 };
355
356 struct lttng_ust_event_recorder_private;
357
358 /*
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
361 * removed.
362 *
363 * struct lttng_ust_event_recorder is the action for recording events
364 * into a ring buffer. It inherits from struct lttng_ust_event_common
365 * by composition to ensure both parent and child structure are
366 * extensible.
367 *
368 * The field @struct_size should be used to determine the size of the
369 * structure. It should be queried before using additional fields added
370 * at the end of the structure.
371 */
372 struct lttng_ust_event_recorder {
373 uint32_t struct_size; /* Size of this structure. */
374
375 struct lttng_ust_event_common *parent; /* Inheritance by aggregation. */
376 struct lttng_ust_event_recorder_private *priv; /* Private event record interface */
377
378 unsigned int id;
379 struct lttng_ust_channel_buffer *chan;
380
381 /* End of base ABI. Fields below should be used after checking struct_size. */
382 };
383
384 /*
385 * IMPORTANT: this structure is part of the ABI between the probe and
386 * UST. Fields need to be only added at the end, never reordered, never
387 * removed.
388 *
389 * The field @struct_size should be used to determine the size of the
390 * structure. It should be queried before using additional fields added
391 * at the end of the structure.
392 */
393 struct lttng_ust_notification_ctx {
394 uint32_t struct_size; /* Size of this structure. */
395 int eval_capture; /* Capture evaluation available. */
396
397 /* End of base ABI. Fields below should be used after checking struct_size. */
398 };
399
400 struct lttng_ust_event_notifier_private;
401
402 /*
403 * IMPORTANT: this structure is part of the ABI between the probe and
404 * UST. Fields need to be only added at the end, never reordered, never
405 * removed.
406 *
407 * struct lttng_ust_event_notifier is the action for sending
408 * notifications. It inherits from struct lttng_ust_event_common
409 * by composition to ensure both parent and child structure are
410 * extensible.
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_event_notifier {
417 uint32_t struct_size; /* Size of this structure. */
418
419 struct lttng_ust_event_common *parent; /* Inheritance by aggregation. */
420 struct lttng_ust_event_notifier_private *priv; /* Private event notifier interface */
421
422 int eval_capture; /* Need to evaluate capture */
423 void (*notification_send)(struct lttng_ust_event_notifier *event_notifier,
424 const char *stack_data,
425 struct lttng_ust_notification_ctx *notif_ctx);
426
427 /* End of base ABI. Fields below should be used after checking struct_size. */
428 };
429
430 struct lttng_ust_lib_ring_buffer_channel;
431 struct lttng_ust_channel_ops_private;
432
433 /*
434 * IMPORTANT: this structure is part of the ABI between the probe and
435 * UST. Fields need to be only added at the end, never reordered, never
436 * removed.
437 *
438 * The field @struct_size should be used to determine the size of the
439 * structure. It should be queried before using additional fields added
440 * at the end of the structure.
441 */
442 struct lttng_ust_channel_ops {
443 uint32_t struct_size;
444
445 struct lttng_ust_channel_ops_private *priv; /* Private channel ops interface */
446
447 int (*event_reserve)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
448 uint32_t event_id);
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);
452 void (*event_strcpy)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
453 const char *src, size_t len);
454 void (*event_strcpy_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_ops *ops;
507 struct lttng_ust_lib_ring_buffer_channel *chan; /* Channel buffers */
508 struct lttng_ust_shm_handle *handle; /* shared-memory handle */
509
510 /* End of base ABI. Fields below should be used after checking struct_size. */
511 };
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_stack_ctx {
523 uint32_t struct_size; /* Size of this structure */
524
525 struct lttng_ust_event_recorder *event_recorder;
526
527 /* End of base ABI. Fields below should be used after checking struct_size. */
528 };
529
530 struct lttng_ust_session_private;
531
532 /*
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
535 * removed.
536 *
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.
540 */
541 struct lttng_ust_session {
542 uint32_t struct_size; /* Size of this structure */
543
544 struct lttng_ust_session_private *priv; /* Private session interface */
545
546 int active; /* Is trace session active ? */
547
548 /* End of base ABI. Fields below should be used after checking struct_size. */
549 };
550
551 int lttng_ust_probe_register(struct lttng_ust_probe_desc *desc);
552 void lttng_ust_probe_unregister(struct lttng_ust_probe_desc *desc);
553
554 /*
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
558 * handler.
559 */
560 void lttng_ust_context_procname_reset(void);
561
562 #ifdef __cplusplus
563 }
564 #endif
565
566 #endif /* _LTTNG_UST_EVENTS_H */
This page took 0.042892 seconds and 5 git commands to generate.