2 * SPDX-License-Identifier: GPL-2.0-only
4 * Copyright (C) 2011 Julien Desfossez <julien.desfossez@polymtl.ca>
5 * Copyright (C) 2011-2013 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
8 #ifndef _LTTNG_UST_CTL_H
9 #define _LTTNG_UST_CTL_H
15 #include <sys/types.h>
17 #include <lttng/ust-abi.h>
20 #error "LTTNG_PACKED should be defined"
23 #ifndef LTTNG_UST_UUID_LEN
24 #define LTTNG_UST_UUID_LEN 16
27 /* Default unix socket path */
28 #define LTTNG_UST_SOCK_FILENAME \
30 __ust_stringify(LTTNG_UST_ABI_MAJOR_VERSION)
33 * Shared memory files path are automatically related to shm root, e.g.
34 * /dev/shm under linux.
36 #define LTTNG_UST_WAIT_FILENAME \
38 __ust_stringify(LTTNG_UST_ABI_MAJOR_VERSION)
40 struct lttng_ust_shm_handle
;
41 struct lttng_ust_lib_ring_buffer
;
43 struct ustctl_consumer_channel_attr
{
44 enum lttng_ust_chan_type type
;
45 uint64_t subbuf_size
; /* bytes */
46 uint64_t num_subbuf
; /* power of 2 */
47 int overwrite
; /* 1: overwrite, 0: discard */
48 unsigned int switch_timer_interval
; /* usec */
49 unsigned int read_timer_interval
; /* usec */
50 enum lttng_ust_output output
; /* splice, mmap */
51 uint32_t chan_id
; /* channel ID */
52 unsigned char uuid
[LTTNG_UST_UUID_LEN
]; /* Trace session unique ID */
53 int64_t blocking_timeout
; /* Blocking timeout (usec) */
57 * API used by sessiond.
60 struct lttng_ust_context_attr
{
61 enum lttng_ust_context_type ctx
;
63 struct lttng_ust_perf_counter_ctx perf_counter
;
72 * Error values: all the following functions return:
73 * >= 0: Success (LTTNG_UST_OK)
76 int ustctl_register_done(int sock
);
77 int ustctl_create_session(int sock
);
78 int ustctl_create_event(int sock
, struct lttng_ust_event
*ev
,
79 struct lttng_ust_object_data
*channel_data
,
80 struct lttng_ust_object_data
**event_data
);
81 int ustctl_add_context(int sock
, struct lttng_ust_context_attr
*ctx
,
82 struct lttng_ust_object_data
*obj_data
,
83 struct lttng_ust_object_data
**context_data
);
84 int ustctl_set_filter(int sock
, struct lttng_ust_filter_bytecode
*bytecode
,
85 struct lttng_ust_object_data
*obj_data
);
86 int ustctl_set_capture(int sock
, struct lttng_ust_capture_bytecode
*bytecode
,
87 struct lttng_ust_object_data
*obj_data
);
88 int ustctl_set_exclusion(int sock
, struct lttng_ust_event_exclusion
*exclusion
,
89 struct lttng_ust_object_data
*obj_data
);
91 int ustctl_enable(int sock
, struct lttng_ust_object_data
*object
);
92 int ustctl_disable(int sock
, struct lttng_ust_object_data
*object
);
93 int ustctl_start_session(int sock
, int handle
);
94 int ustctl_stop_session(int sock
, int handle
);
97 * ustctl_create_event notifier_group creates a event notifier group. It
98 * establishes the connection with the application by providing a file
99 * descriptor of the pipe to be used by the application when a event notifier
100 * of that group is fired. It returns a handle to be used when creating event
101 * notifier in that group.
103 int ustctl_create_event_notifier_group(int sock
, int pipe_fd
,
104 struct lttng_ust_object_data
**event_notifier_group
);
107 * ustctl_create_event notifier creates a event notifier in a event notifier
108 * group giving a event notifier description and a event notifier group handle.
109 * It returns a event notifier handle to be used when enabling the event
110 * notifier, attaching filter, attaching exclusion, and disabling the event
113 int ustctl_create_event_notifier(int sock
,
114 struct lttng_ust_event_notifier
*event_notifier
,
115 struct lttng_ust_object_data
*event_notifier_group
,
116 struct lttng_ust_object_data
**event_notifier_data
);
119 * ustctl_tracepoint_list returns a tracepoint list handle, or negative
122 int ustctl_tracepoint_list(int sock
);
125 * ustctl_tracepoint_list_get is used to iterate on the tp list
126 * handle. End is iteration is reached when -LTTNG_UST_ERR_NOENT is
129 int ustctl_tracepoint_list_get(int sock
, int tp_list_handle
,
130 struct lttng_ust_tracepoint_iter
*iter
);
133 * ustctl_tracepoint_field_list returns a tracepoint field list handle,
134 * or negative error value.
136 int ustctl_tracepoint_field_list(int sock
);
139 * ustctl_tracepoint_field_list_get is used to iterate on the tp field
140 * list handle. End is iteration is reached when -LTTNG_UST_ERR_NOENT is
143 int ustctl_tracepoint_field_list_get(int sock
, int tp_field_list_handle
,
144 struct lttng_ust_field_iter
*iter
);
146 int ustctl_tracer_version(int sock
, struct lttng_ust_tracer_version
*v
);
147 int ustctl_wait_quiescent(int sock
);
149 int ustctl_sock_flush_buffer(int sock
, struct lttng_ust_object_data
*object
);
151 int ustctl_calibrate(int sock
, struct lttng_ust_calibrate
*calibrate
);
153 /* Release object created by members of this API. */
154 int ustctl_release_object(int sock
, struct lttng_ust_object_data
*data
);
155 /* Release handle returned by create session. */
156 int ustctl_release_handle(int sock
, int handle
);
158 int ustctl_recv_channel_from_consumer(int sock
,
159 struct lttng_ust_object_data
**channel_data
);
160 int ustctl_recv_stream_from_consumer(int sock
,
161 struct lttng_ust_object_data
**stream_data
);
162 int ustctl_send_channel_to_ust(int sock
, int session_handle
,
163 struct lttng_ust_object_data
*channel_data
);
164 int ustctl_send_stream_to_ust(int sock
,
165 struct lttng_ust_object_data
*channel_data
,
166 struct lttng_ust_object_data
*stream_data
);
169 * ustctl_duplicate_ust_object_data allocated a new object in "dest" if
170 * it succeeds (returns 0). It must be released using
171 * ustctl_release_object() and then freed with free().
173 int ustctl_duplicate_ust_object_data(struct lttng_ust_object_data
**dest
,
174 struct lttng_ust_object_data
*src
);
177 * API used by consumer.
180 struct ustctl_consumer_channel
;
181 struct ustctl_consumer_stream
;
182 struct ustctl_consumer_channel_attr
;
184 int ustctl_get_nr_stream_per_channel(void);
186 struct ustctl_consumer_channel
*
187 ustctl_create_channel(struct ustctl_consumer_channel_attr
*attr
,
188 const int *stream_fds
, int nr_stream_fds
);
190 * Each stream created needs to be destroyed before calling
191 * ustctl_destroy_channel().
193 void ustctl_destroy_channel(struct ustctl_consumer_channel
*chan
);
195 int ustctl_send_channel_to_sessiond(int sock
,
196 struct ustctl_consumer_channel
*channel
);
197 int ustctl_channel_close_wait_fd(struct ustctl_consumer_channel
*consumer_chan
);
198 int ustctl_channel_close_wakeup_fd(struct ustctl_consumer_channel
*consumer_chan
);
199 int ustctl_channel_get_wait_fd(struct ustctl_consumer_channel
*consumer_chan
);
200 int ustctl_channel_get_wakeup_fd(struct ustctl_consumer_channel
*consumer_chan
);
202 int ustctl_write_metadata_to_channel(
203 struct ustctl_consumer_channel
*channel
,
204 const char *metadata_str
, /* NOT null-terminated */
205 size_t len
); /* metadata length */
206 ssize_t
ustctl_write_one_packet_to_channel(
207 struct ustctl_consumer_channel
*channel
,
208 const char *metadata_str
, /* NOT null-terminated */
209 size_t len
); /* metadata length */
212 * Send a NULL stream to finish iteration over all streams of a given
215 int ustctl_send_stream_to_sessiond(int sock
,
216 struct ustctl_consumer_stream
*stream
);
217 int ustctl_stream_close_wait_fd(struct ustctl_consumer_stream
*stream
);
218 int ustctl_stream_close_wakeup_fd(struct ustctl_consumer_stream
*stream
);
219 int ustctl_stream_get_wait_fd(struct ustctl_consumer_stream
*stream
);
220 int ustctl_stream_get_wakeup_fd(struct ustctl_consumer_stream
*stream
);
222 /* Create/destroy stream buffers for read */
223 struct ustctl_consumer_stream
*
224 ustctl_create_stream(struct ustctl_consumer_channel
*channel
,
226 void ustctl_destroy_stream(struct ustctl_consumer_stream
*stream
);
228 /* For mmap mode, readable without "get" operation */
229 int ustctl_get_mmap_len(struct ustctl_consumer_stream
*stream
,
231 int ustctl_get_max_subbuf_size(struct ustctl_consumer_stream
*stream
,
235 * For mmap mode, operate on the current packet (between get/put or
236 * get_next/put_next).
238 void *ustctl_get_mmap_base(struct ustctl_consumer_stream
*stream
);
239 int ustctl_get_mmap_read_offset(struct ustctl_consumer_stream
*stream
,
241 int ustctl_get_subbuf_size(struct ustctl_consumer_stream
*stream
,
243 int ustctl_get_padded_subbuf_size(struct ustctl_consumer_stream
*stream
,
245 int ustctl_get_next_subbuf(struct ustctl_consumer_stream
*stream
);
246 int ustctl_put_next_subbuf(struct ustctl_consumer_stream
*stream
);
250 int ustctl_snapshot(struct ustctl_consumer_stream
*stream
);
251 int ustctl_snapshot_sample_positions(struct ustctl_consumer_stream
*stream
);
252 int ustctl_snapshot_get_consumed(struct ustctl_consumer_stream
*stream
,
254 int ustctl_snapshot_get_produced(struct ustctl_consumer_stream
*stream
,
256 int ustctl_get_subbuf(struct ustctl_consumer_stream
*stream
,
258 int ustctl_put_subbuf(struct ustctl_consumer_stream
*stream
);
260 void ustctl_flush_buffer(struct ustctl_consumer_stream
*stream
,
261 int producer_active
);
262 void ustctl_clear_buffer(struct ustctl_consumer_stream
*stream
);
267 * Getters which need to be used on the current packet (between get/put
268 * or get_next/put_next.
271 int ustctl_get_timestamp_begin(struct ustctl_consumer_stream
*stream
,
272 uint64_t *timestamp_begin
);
273 int ustctl_get_timestamp_end(struct ustctl_consumer_stream
*stream
,
274 uint64_t *timestamp_end
);
275 int ustctl_get_events_discarded(struct ustctl_consumer_stream
*stream
,
276 uint64_t *events_discarded
);
277 int ustctl_get_content_size(struct ustctl_consumer_stream
*stream
,
278 uint64_t *content_size
);
279 int ustctl_get_packet_size(struct ustctl_consumer_stream
*stream
,
280 uint64_t *packet_size
);
281 int ustctl_get_sequence_number(struct ustctl_consumer_stream
*stream
,
285 * Getter returning state invariant for the stream, which can be used
286 * without "get" operation.
289 int ustctl_get_stream_id(struct ustctl_consumer_stream
*stream
,
290 uint64_t *stream_id
);
291 int ustctl_get_instance_id(struct ustctl_consumer_stream
*stream
,
295 * Getter returning the current timestamp as perceived from the
298 int ustctl_get_current_timestamp(struct ustctl_consumer_stream
*stream
,
301 /* returns whether UST has perf counters support. */
302 int ustctl_has_perf_counters(void);
304 /* Regenerate the statedump. */
305 int ustctl_regenerate_statedump(int sock
, int handle
);
307 /* event registry management */
309 enum ustctl_socket_type
{
310 USTCTL_SOCKET_CMD
= 0,
311 USTCTL_SOCKET_NOTIFY
= 1,
314 enum ustctl_notify_cmd
{
315 USTCTL_NOTIFY_CMD_EVENT
= 0,
316 USTCTL_NOTIFY_CMD_CHANNEL
= 1,
317 USTCTL_NOTIFY_CMD_ENUM
= 2,
320 enum ustctl_channel_header
{
321 USTCTL_CHANNEL_HEADER_UNKNOWN
= 0,
322 USTCTL_CHANNEL_HEADER_COMPACT
= 1,
323 USTCTL_CHANNEL_HEADER_LARGE
= 2,
326 /* event type structures */
328 enum ustctl_abstract_types
{
329 ustctl_atype_integer
,
330 ustctl_atype_enum
, /* legacy */
331 ustctl_atype_array
, /* legacy */
332 ustctl_atype_sequence
, /* legacy */
335 ustctl_atype_variant
, /* legacy */
336 ustctl_atype_struct
, /* legacy */
337 ustctl_atype_enum_nestable
,
338 ustctl_atype_array_nestable
,
339 ustctl_atype_sequence_nestable
,
340 ustctl_atype_struct_nestable
,
341 ustctl_atype_variant_nestable
,
342 NR_USTCTL_ABSTRACT_TYPES
,
345 enum ustctl_string_encodings
{
346 ustctl_encode_none
= 0,
347 ustctl_encode_UTF8
= 1,
348 ustctl_encode_ASCII
= 2,
349 NR_USTCTL_STRING_ENCODINGS
,
352 #define USTCTL_UST_INTEGER_TYPE_PADDING 24
353 struct ustctl_integer_type
{
354 uint32_t size
; /* in bits */
356 uint32_t reverse_byte_order
;
357 uint32_t base
; /* 2, 8, 10, 16, for pretty print */
358 int32_t encoding
; /* enum ustctl_string_encodings */
359 uint16_t alignment
; /* in bits */
360 char padding
[USTCTL_UST_INTEGER_TYPE_PADDING
];
363 #define USTCTL_UST_FLOAT_TYPE_PADDING 24
364 struct ustctl_float_type
{
365 uint32_t exp_dig
; /* exponent digits, in bits */
366 uint32_t mant_dig
; /* mantissa digits, in bits */
367 uint32_t reverse_byte_order
;
368 uint16_t alignment
; /* in bits */
369 char padding
[USTCTL_UST_FLOAT_TYPE_PADDING
];
372 #define USTCTL_UST_ENUM_VALUE_PADDING 15
373 struct ustctl_enum_value
{
376 char padding
[USTCTL_UST_ENUM_VALUE_PADDING
];
379 enum ustctl_ust_enum_entry_options
{
380 USTCTL_UST_ENUM_ENTRY_OPTION_IS_AUTO
= 1U << 0,
383 #define USTCTL_UST_ENUM_ENTRY_PADDING 32
384 struct ustctl_enum_entry
{
385 struct ustctl_enum_value start
, end
; /* start and end are inclusive */
386 char string
[LTTNG_UST_SYM_NAME_LEN
];
390 } LTTNG_PACKED extra
;
391 char padding
[USTCTL_UST_ENUM_ENTRY_PADDING
];
396 #define USTCTL_UST_BASIC_TYPE_PADDING 296
397 union _ustctl_basic_type
{
398 struct ustctl_integer_type integer
;
400 char name
[LTTNG_UST_SYM_NAME_LEN
];
401 struct ustctl_integer_type container_type
;
402 uint64_t id
; /* enum ID in sessiond. */
405 int32_t encoding
; /* enum ustctl_string_encodings */
407 struct ustctl_float_type _float
;
408 char padding
[USTCTL_UST_BASIC_TYPE_PADDING
];
412 struct ustctl_basic_type
{
413 enum ustctl_abstract_types atype
;
415 union _ustctl_basic_type basic
;
420 * Padding is derived from largest member: u.legacy.sequence which
421 * contains two basic types, each with USTCTL_UST_BASIC_TYPE_PADDING.
423 #define USTCTL_UST_TYPE_PADDING (2 * USTCTL_UST_BASIC_TYPE_PADDING)
425 enum ustctl_abstract_types atype
;
427 struct ustctl_integer_type integer
;
428 struct ustctl_float_type _float
;
430 int32_t encoding
; /* enum ustctl_string_encodings */
433 char name
[LTTNG_UST_SYM_NAME_LEN
];
434 uint64_t id
; /* enum ID in sessiond. */
435 /* container_type follows after this struct ustctl_field. */
438 uint32_t length
; /* num. elems. */
440 /* elem_type follows after this struct ustctl_field. */
443 char length_name
[LTTNG_UST_SYM_NAME_LEN
];
444 uint32_t alignment
; /* Alignment before elements. */
445 /* elem_type follows after the length_type. */
450 /* Followed by nr_fields struct ustctl_field. */
454 char tag_name
[LTTNG_UST_SYM_NAME_LEN
];
456 /* Followed by nr_choices struct ustctl_field. */
461 union _ustctl_basic_type basic
;
463 struct ustctl_basic_type elem_type
;
464 uint32_t length
; /* num. elems. */
467 struct ustctl_basic_type length_type
;
468 struct ustctl_basic_type elem_type
;
472 /* Followed by nr_fields struct ustctl_field. */
476 char tag_name
[LTTNG_UST_SYM_NAME_LEN
];
477 /* Followed by nr_choices struct ustctl_field. */
480 char padding
[USTCTL_UST_TYPE_PADDING
];
484 #define USTCTL_UST_FIELD_PADDING 28
485 struct ustctl_field
{
486 char name
[LTTNG_UST_SYM_NAME_LEN
];
487 struct ustctl_type type
;
488 char padding
[USTCTL_UST_FIELD_PADDING
];
492 * Returns 0 on success, negative error value on error.
493 * If an error other than -LTTNG_UST_ERR_UNSUP_MAJOR is returned,
494 * the output fields are not populated.
496 int ustctl_recv_reg_msg(int sock
,
497 enum ustctl_socket_type
*type
,
504 uint32_t *bits_per_long
,
505 uint32_t *uint8_t_alignment
,
506 uint32_t *uint16_t_alignment
,
507 uint32_t *uint32_t_alignment
,
508 uint32_t *uint64_t_alignment
,
509 uint32_t *long_alignment
,
511 char *name
); /* size LTTNG_UST_ABI_PROCNAME_LEN */
514 * Returns 0 on success, negative UST or system error value on error.
515 * Receive the notification command. The "notify_cmd" can then be used
516 * by the caller to find out which ustctl_recv_* function should be
517 * called to receive the notification, and which ustctl_reply_* is
520 int ustctl_recv_notify(int sock
, enum ustctl_notify_cmd
*notify_cmd
);
523 * Returns 0 on success, negative UST or system error value on error.
525 int ustctl_recv_register_event(int sock
,
526 int *session_objd
, /* session descriptor (output) */
527 int *channel_objd
, /* channel descriptor (output) */
529 * event name (output,
530 * size LTTNG_UST_SYM_NAME_LEN)
535 * (output, dynamically
536 * allocated, must be free(3)'d
537 * by the caller if function
541 struct ustctl_field
**fields
,
542 char **model_emf_uri
);
545 * Returns 0 on success, negative error value on error.
547 int ustctl_reply_register_event(int sock
,
548 uint32_t id
, /* event id (input) */
549 int ret_code
); /* return code. 0 ok, negative error */
552 * Returns 0 on success, negative UST or system error value on error.
554 int ustctl_recv_register_enum(int sock
,
557 struct ustctl_enum_entry
**entries
,
561 * Returns 0 on success, negative error value on error.
563 int ustctl_reply_register_enum(int sock
,
564 uint64_t id
, /* enum id (input) */
568 * Returns 0 on success, negative UST or system error value on error.
570 int ustctl_recv_register_channel(int sock
,
571 int *session_objd
, /* session descriptor (output) */
572 int *channel_objd
, /* channel descriptor (output) */
573 size_t *nr_fields
, /* context fields */
574 struct ustctl_field
**fields
);
577 * Returns 0 on success, negative error value on error.
579 int ustctl_reply_register_channel(int sock
,
581 enum ustctl_channel_header header_type
,
582 int ret_code
); /* return code. 0 ok, negative error */
588 enum ustctl_counter_bitness
{
589 USTCTL_COUNTER_BITNESS_32
= 0,
590 USTCTL_COUNTER_BITNESS_64
= 1,
593 enum ustctl_counter_arithmetic
{
594 USTCTL_COUNTER_ARITHMETIC_MODULAR
= 0,
595 USTCTL_COUNTER_ARITHMETIC_SATURATION
= 1,
598 /* Used as alloc flags. */
599 enum ustctl_counter_alloc
{
600 USTCTL_COUNTER_ALLOC_PER_CPU
= (1 << 0),
601 USTCTL_COUNTER_ALLOC_GLOBAL
= (1 << 1),
604 struct ustctl_daemon_counter
;
606 int ustctl_get_nr_cpu_per_counter(void);
608 struct ustctl_counter_dimension
{
610 uint64_t underflow_index
;
611 uint64_t overflow_index
;
612 uint8_t has_underflow
;
613 uint8_t has_overflow
;
616 struct ustctl_daemon_counter
*
617 ustctl_create_counter(size_t nr_dimensions
,
618 const struct ustctl_counter_dimension
*dimensions
,
619 int64_t global_sum_step
,
620 int global_counter_fd
,
621 int nr_counter_cpu_fds
,
622 const int *counter_cpu_fds
,
623 enum ustctl_counter_bitness bitness
,
624 enum ustctl_counter_arithmetic arithmetic
,
625 uint32_t alloc_flags
);
627 int ustctl_create_counter_data(struct ustctl_daemon_counter
*counter
,
628 struct lttng_ust_object_data
**counter_data
);
630 int ustctl_create_counter_global_data(struct ustctl_daemon_counter
*counter
,
631 struct lttng_ust_object_data
**counter_global_data
);
632 int ustctl_create_counter_cpu_data(struct ustctl_daemon_counter
*counter
, int cpu
,
633 struct lttng_ust_object_data
**counter_cpu_data
);
636 * Each counter data and counter cpu data created need to be destroyed
637 * before calling ustctl_destroy_counter().
639 void ustctl_destroy_counter(struct ustctl_daemon_counter
*counter
);
641 int ustctl_send_counter_data_to_ust(int sock
, int parent_handle
,
642 struct lttng_ust_object_data
*counter_data
);
643 int ustctl_send_counter_global_data_to_ust(int sock
,
644 struct lttng_ust_object_data
*counter_data
,
645 struct lttng_ust_object_data
*counter_global_data
);
646 int ustctl_send_counter_cpu_data_to_ust(int sock
,
647 struct lttng_ust_object_data
*counter_data
,
648 struct lttng_ust_object_data
*counter_cpu_data
);
650 int ustctl_counter_read(struct ustctl_daemon_counter
*counter
,
651 const size_t *dimension_indexes
,
652 int cpu
, int64_t *value
,
653 bool *overflow
, bool *underflow
);
654 int ustctl_counter_aggregate(struct ustctl_daemon_counter
*counter
,
655 const size_t *dimension_indexes
,
657 bool *overflow
, bool *underflow
);
658 int ustctl_counter_clear(struct ustctl_daemon_counter
*counter
,
659 const size_t *dimension_indexes
);
661 #endif /* _LTTNG_UST_CTL_H */