Namespace enumeration structures/enum with lttng_ust_ prefix
[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 #ifndef LTTNG_PACKED
25 #error "LTTNG_PACKED should be defined"
26 #endif
27
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31
32 #define LTTNG_UST_UUID_LEN 16
33
34 /*
35 * Tracepoint provider version. Compatibility based on the major number.
36 * Older tracepoint providers can always register to newer lttng-ust
37 * library, but the opposite is rejected: a newer tracepoint provider is
38 * rejected by an older lttng-ust library.
39 */
40 #define LTTNG_UST_PROVIDER_MAJOR 2
41 #define LTTNG_UST_PROVIDER_MINOR 0
42
43 struct lttng_channel;
44 struct lttng_ust_session;
45 struct lttng_ust_lib_ring_buffer_ctx;
46 struct lttng_ust_event_field;
47
48 /*
49 * Data structures used by tracepoint event declarations, and by the
50 * tracer.
51 */
52
53 /* Type description */
54
55 enum lttng_ust_type {
56 lttng_ust_type_integer,
57 lttng_ust_type_string,
58 lttng_ust_type_float,
59 lttng_ust_type_dynamic,
60 lttng_ust_type_enum,
61 lttng_ust_type_array,
62 lttng_ust_type_sequence,
63 lttng_ust_type_struct,
64 NR_LTTNG_UST_TYPE,
65 };
66
67 enum lttng_ust_string_encoding {
68 lttng_ust_string_encoding_none = 0,
69 lttng_ust_string_encoding_UTF8 = 1,
70 lttng_ust_string_encoding_ASCII = 2,
71 NR_LTTNG_UST_STRING_ENCODING,
72 };
73
74 struct lttng_ust_enum_value {
75 unsigned long long value;
76 unsigned int signedness:1;
77 };
78
79 enum lttng_ust_enum_entry_option {
80 LTTNG_UST_ENUM_ENTRY_OPTION_IS_AUTO = 1U << 0,
81 };
82
83 /*
84 * Enumeration entry description
85 *
86 * IMPORTANT: this structure is part of the ABI between the probe and
87 * UST. Fields need to be only added at the end, never reordered, never
88 * removed.
89 *
90 * The field @struct_size should be used to determine the size of the
91 * structure. It should be queried before using additional fields added
92 * at the end of the structure.
93 */
94
95 struct lttng_ust_enum_entry {
96 uint32_t struct_size;
97
98 struct lttng_ust_enum_value start, end; /* start and end are inclusive */
99 const char *string;
100 unsigned int options;
101
102 /* End of base ABI. Fields below should be used after checking struct_size. */
103 };
104
105 /*
106 * struct lttng_ust_type_common is fixed-size. Its children inherits
107 * from it by embedding struct lttng_ust_type_common as its first field.
108 */
109 struct lttng_ust_type_common {
110 enum lttng_ust_type type;
111 };
112
113 struct lttng_ust_type_integer {
114 struct lttng_ust_type_common parent;
115 uint32_t struct_size;
116 unsigned int size; /* in bits */
117 unsigned short alignment; /* in bits */
118 unsigned int signedness:1;
119 unsigned int reverse_byte_order:1;
120 unsigned int base; /* 2, 8, 10, 16, for pretty print */
121 };
122
123 #define lttng_ust_type_integer_define(_type, _byte_order, _base) \
124 ((struct lttng_ust_type_common *) __LTTNG_COMPOUND_LITERAL(struct lttng_ust_type_integer, { \
125 .parent = { \
126 .type = lttng_ust_type_integer, \
127 }, \
128 .struct_size = sizeof(struct lttng_ust_type_integer), \
129 .size = sizeof(_type) * CHAR_BIT, \
130 .alignment = lttng_alignof(_type) * CHAR_BIT, \
131 .signedness = lttng_is_signed_type(_type), \
132 .reverse_byte_order = _byte_order != BYTE_ORDER, \
133 .base = _base, \
134 }))
135
136 struct lttng_ust_type_float {
137 struct lttng_ust_type_common parent;
138 uint32_t struct_size;
139 unsigned int exp_dig; /* exponent digits, in bits */
140 unsigned int mant_dig; /* mantissa digits, in bits */
141 unsigned short alignment; /* in bits */
142 unsigned int reverse_byte_order:1;
143 };
144
145 /*
146 * Only float and double are supported. long double is not supported at
147 * the moment.
148 */
149 #define _float_mant_dig(_type) \
150 (sizeof(_type) == sizeof(float) ? FLT_MANT_DIG \
151 : (sizeof(_type) == sizeof(double) ? DBL_MANT_DIG \
152 : 0))
153
154 #define lttng_ust_type_float_define(_type) \
155 ((struct lttng_ust_type_common *) __LTTNG_COMPOUND_LITERAL(struct lttng_ust_type_float, { \
156 .parent = { \
157 .type = lttng_ust_type_float, \
158 }, \
159 .struct_size = sizeof(struct lttng_ust_type_float), \
160 .exp_dig = sizeof(_type) * CHAR_BIT \
161 - _float_mant_dig(_type), \
162 .mant_dig = _float_mant_dig(_type), \
163 .alignment = lttng_alignof(_type) * CHAR_BIT, \
164 .reverse_byte_order = BYTE_ORDER != FLOAT_WORD_ORDER, \
165 }))
166
167
168 struct lttng_ust_type_string {
169 struct lttng_ust_type_common parent;
170 uint32_t struct_size;
171 enum lttng_ust_string_encoding encoding;
172 };
173
174 struct lttng_ust_type_enum {
175 struct lttng_ust_type_common parent;
176 uint32_t struct_size;
177 struct lttng_ust_enum_desc *desc; /* Enumeration mapping */
178 struct lttng_ust_type_common *container_type;
179 };
180
181 struct lttng_ust_type_array {
182 struct lttng_ust_type_common parent;
183 uint32_t struct_size;
184 struct lttng_ust_type_common *elem_type;
185 unsigned int length; /* Num. elems. */
186 unsigned int alignment;
187 enum lttng_ust_string_encoding encoding;
188 };
189
190 struct lttng_ust_type_sequence {
191 struct lttng_ust_type_common parent;
192 uint32_t struct_size;
193 const char *length_name; /* Length field name. */
194 struct lttng_ust_type_common *elem_type;
195 unsigned int alignment; /* Alignment before elements. */
196 enum lttng_ust_string_encoding encoding;
197 };
198
199 struct lttng_ust_type_struct {
200 struct lttng_ust_type_common parent;
201 uint32_t struct_size;
202 unsigned int nr_fields;
203 struct lttng_ust_event_field **fields; /* Array of pointers to fields. */
204 unsigned int alignment;
205 };
206
207 /*
208 * Enumeration description
209 *
210 * IMPORTANT: this structure is part of the ABI between the probe and
211 * UST. Fields need to be only added at the end, never reordered, never
212 * removed.
213 *
214 * The field @struct_size should be used to determine the size of the
215 * structure. It should be queried before using additional fields added
216 * at the end of the structure.
217 */
218
219 struct lttng_ust_enum_desc {
220 uint32_t struct_size;
221
222 const char *name;
223 struct lttng_ust_enum_entry **entries;
224 unsigned int nr_entries;
225
226 /* End of base ABI. Fields below should be used after checking struct_size. */
227 };
228
229 /*
230 * Event field description
231 *
232 * IMPORTANT: this structure is part of the ABI between the probe and
233 * UST. Fields need to be only added at the end, never reordered, never
234 * removed.
235 *
236 * The field @struct_size should be used to determine the size of the
237 * structure. It should be queried before using additional fields added
238 * at the end of the structure.
239 */
240
241 struct lttng_ust_event_field {
242 uint32_t struct_size;
243
244 const char *name;
245 struct lttng_ust_type_common *type;
246 unsigned int nowrite:1, /* do not write into trace */
247 nofilter:1; /* do not consider for filter */
248
249 /* End of base ABI. Fields below should be used after checking struct_size. */
250 };
251
252
253 /*
254 * IMPORTANT: this structure is part of the ABI between the probe and
255 * UST. Fields need to be only added at the end, never reordered, never
256 * removed.
257 *
258 * The field @struct_size should be used to determine the size of the
259 * structure. It should be queried before using additional fields added
260 * at the end of the structure.
261 */
262 struct lttng_ust_event_desc {
263 uint32_t struct_size; /* Size of this structure. */
264
265 const char *name;
266 void (*probe_callback)(void);
267 struct lttng_event_ctx *ctx; /* context */
268 struct lttng_ust_event_field **fields; /* event payload */
269 unsigned int nr_fields;
270 const int **loglevel;
271 const char *signature; /* Argument types/names received */
272 const char **model_emf_uri;
273
274 /* End of base ABI. Fields below should be used after checking struct_size. */
275 };
276
277 /*
278 * IMPORTANT: this structure is part of the ABI between the probe and
279 * UST. Fields need to be only added at the end, never reordered, never
280 * removed.
281 *
282 * The field @struct_size should be used to determine the size of the
283 * structure. It should be queried before using additional fields added
284 * at the end of the structure.
285 */
286 struct lttng_ust_probe_desc {
287 uint32_t struct_size; /* Size of this structure. */
288
289 const char *provider;
290 struct lttng_ust_event_desc **event_desc;
291 unsigned int nr_events;
292 struct cds_list_head head; /* chain registered probes */
293 struct cds_list_head lazy_init_head;
294 int lazy; /* lazy registration */
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 * Bytecode interpreter return value masks.
305 */
306 enum lttng_bytecode_interpreter_ret {
307 LTTNG_INTERPRETER_DISCARD = 0,
308 LTTNG_INTERPRETER_RECORD_FLAG = (1ULL << 0),
309 /* Other bits are kept for future use. */
310 };
311
312 struct lttng_interpreter_output;
313 struct lttng_ust_bytecode_runtime_private;
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_runtime {
325 uint32_t struct_size; /* Size of this structure. */
326
327 struct lttng_ust_bytecode_runtime_private *priv;
328 /* Associated bytecode */
329 union {
330 uint64_t (*filter)(void *interpreter_data,
331 const char *interpreter_stack_data);
332 uint64_t (*capture)(void *interpreter_data,
333 const char *interpreter_stack_data,
334 struct lttng_interpreter_output *interpreter_output);
335 } interpreter_funcs;
336 struct cds_list_head node; /* list of bytecode runtime in event */
337
338 /* End of base ABI. Fields below should be used after checking struct_size. */
339 };
340
341 /*
342 * lttng_event structure is referred to by the tracing fast path. It
343 * must be kept small.
344 *
345 * IMPORTANT: this structure is part of the ABI between the probe and
346 * UST. Fields need to be only added at the end, never reordered, never
347 * removed.
348 */
349
350 struct lttng_ust_ctx;
351 struct lttng_ust_event_common_private;
352
353 enum lttng_ust_event_type {
354 LTTNG_UST_EVENT_TYPE_RECORDER = 0,
355 LTTNG_UST_EVENT_TYPE_NOTIFIER = 1,
356 };
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_common is the common ancestor of the various
364 * public event actions. Inheritance is done by composition: The parent
365 * has a pointer to its child, and the child has a pointer to its
366 * parent. Inheritance of those public structures is done by composition
367 * to ensure both parent and child structures can be extended.
368 *
369 * The field @struct_size should be used to determine the size of the
370 * structure. It should be queried before using additional fields added
371 * at the end of the structure.
372 */
373 struct lttng_ust_event_common {
374 uint32_t struct_size; /* Size of this structure. */
375
376 struct lttng_ust_event_common_private *priv; /* Private event interface */
377
378 enum lttng_ust_event_type type;
379 void *child; /* Pointer to child, for inheritance by aggregation. */
380
381 int enabled;
382 int has_enablers_without_bytecode;
383 /* list of struct lttng_ust_bytecode_runtime, sorted by seqnum */
384 struct cds_list_head filter_bytecode_runtime_head;
385
386 /* End of base ABI. Fields below should be used after checking struct_size. */
387 };
388
389 struct lttng_ust_event_recorder_private;
390
391 /*
392 * IMPORTANT: this structure is part of the ABI between the probe and
393 * UST. Fields need to be only added at the end, never reordered, never
394 * removed.
395 *
396 * struct lttng_ust_event_recorder is the action for recording events
397 * into a ring buffer. It inherits from struct lttng_ust_event_common
398 * by composition to ensure both parent and child structure are
399 * extensible.
400 *
401 * The field @struct_size should be used to determine the size of the
402 * structure. It should be queried before using additional fields added
403 * at the end of the structure.
404 */
405 struct lttng_ust_event_recorder {
406 uint32_t struct_size; /* Size of this structure. */
407
408 struct lttng_ust_event_common *parent; /* Inheritance by aggregation. */
409 struct lttng_ust_event_recorder_private *priv; /* Private event record interface */
410
411 unsigned int id;
412 struct lttng_channel *chan;
413 struct lttng_ust_ctx *ctx;
414
415 /* End of base ABI. Fields below should be used after checking struct_size. */
416 };
417
418 struct lttng_ust_event_notifier_private;
419
420 /*
421 * IMPORTANT: this structure is part of the ABI between the probe and
422 * UST. Fields need to be only added at the end, never reordered, never
423 * removed.
424 *
425 * struct lttng_ust_event_notifier is the action for sending
426 * notifications. It inherits from struct lttng_ust_event_common
427 * by composition to ensure both parent and child structure are
428 * extensible.
429 *
430 * The field @struct_size should be used to determine the size of the
431 * structure. It should be queried before using additional fields added
432 * at the end of the structure.
433 */
434 struct lttng_ust_event_notifier {
435 uint32_t struct_size; /* Size of this structure. */
436
437 struct lttng_ust_event_common *parent; /* Inheritance by aggregation. */
438 struct lttng_ust_event_notifier_private *priv; /* Private event notifier interface */
439
440 void (*notification_send)(struct lttng_ust_event_notifier *event_notifier,
441 const char *stack_data);
442 struct cds_list_head capture_bytecode_runtime_head;
443
444 /* End of base ABI. Fields below should be used after checking struct_size. */
445 };
446
447 struct lttng_ust_lib_ring_buffer_channel;
448 struct lttng_ust_shm_handle;
449 struct lttng_ust_channel_ops_private;
450
451 /*
452 * IMPORTANT: this structure is part of the ABI between the probe and
453 * UST. Fields need to be only added at the end, never reordered, never
454 * removed.
455 *
456 * The field @struct_size should be used to determine the size of the
457 * structure. It should be queried before using additional fields added
458 * at the end of the structure.
459 */
460 struct lttng_ust_channel_ops {
461 uint32_t struct_size;
462
463 struct lttng_ust_channel_ops_private *priv; /* Private channel ops interface */
464
465 int (*event_reserve)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
466 uint32_t event_id);
467 void (*event_commit)(struct lttng_ust_lib_ring_buffer_ctx *ctx);
468 void (*event_write)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
469 const void *src, size_t len);
470 void (*event_strcpy)(struct lttng_ust_lib_ring_buffer_ctx *ctx,
471 const char *src, size_t len);
472
473 /* End of base ABI. Fields below should be used after checking struct_size. */
474 };
475
476 /*
477 * IMPORTANT: this structure is part of the ABI between the probe and
478 * UST. Fields need to be only added at the end, never reordered, never
479 * removed.
480 */
481 struct lttng_channel {
482 /*
483 * The pointers located in this private data are NOT safe to be
484 * dereferenced by the consumer. The only operations the
485 * consumer process is designed to be allowed to do is to read
486 * and perform subbuffer flush.
487 */
488 struct lttng_ust_lib_ring_buffer_channel *chan; /* Channel buffers */
489 int enabled;
490 struct lttng_ust_ctx *ctx;
491 /* Event ID management */
492 struct lttng_ust_session *session;
493 int objd; /* Object associated to channel */
494 struct cds_list_head node; /* Channel list in session */
495 struct lttng_ust_channel_ops *ops;
496 int header_type; /* 0: unset, 1: compact, 2: large */
497 struct lttng_ust_shm_handle *handle; /* shared-memory handle */
498
499 /* Channel ID */
500 unsigned int id;
501 enum lttng_ust_abi_chan_type type;
502 unsigned char uuid[LTTNG_UST_UUID_LEN]; /* Trace session unique ID */
503 int tstate:1; /* Transient enable state */
504 };
505
506 /*
507 * IMPORTANT: this structure is part of the ABI between the probe and
508 * UST. Fields need to be only added at the end, never reordered, never
509 * removed.
510 *
511 * The field @struct_size should be used to determine the size of the
512 * structure. It should be queried before using additional fields added
513 * at the end of the structure.
514 */
515 struct lttng_ust_stack_ctx {
516 uint32_t struct_size; /* Size of this structure */
517
518 struct lttng_ust_event_recorder *event_recorder;
519 struct lttng_ust_ctx *chan_ctx; /* RCU dereferenced. */
520 struct lttng_ust_ctx *event_ctx; /* RCU dereferenced. */
521
522 /* End of base ABI. Fields below should be used after checking struct_size. */
523 };
524
525 struct lttng_ust_session_private;
526
527 /*
528 * IMPORTANT: this structure is part of the ABI between the probe and
529 * UST. Fields need to be only added at the end, never reordered, never
530 * removed.
531 *
532 * The field @struct_size should be used to determine the size of the
533 * structure. It should be queried before using additional fields added
534 * at the end of the structure.
535 */
536 struct lttng_ust_session {
537 uint32_t struct_size; /* Size of this structure */
538
539 struct lttng_ust_session_private *priv; /* Private session interface */
540
541 int active; /* Is trace session active ? */
542
543 /* End of base ABI. Fields below should be used after checking struct_size. */
544 };
545
546 int lttng_ust_probe_register(struct lttng_ust_probe_desc *desc);
547 void lttng_ust_probe_unregister(struct lttng_ust_probe_desc *desc);
548
549 /*
550 * Applications that change their procname and need the new value to be
551 * reflected in the procname event context have to call this function to clear
552 * the internally cached value. This should not be called from a signal
553 * handler.
554 */
555 void lttng_ust_context_procname_reset(void);
556
557 #ifdef __cplusplus
558 }
559 #endif
560
561 #endif /* _LTTNG_UST_EVENTS_H */
This page took 0.058264 seconds and 5 git commands to generate.