Generate and export the sequence number
[lttng-ust.git] / include / lttng / ust-ctl.h
... / ...
CommitLineData
1/*
2 * Copyright (C) 2011 - Julien Desfossez <julien.desfossez@polymtl.ca>
3 * Copyright (C) 2011-2013 - Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; version 2 of the License only.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License along
15 * with this program; if not, write to the Free Software Foundation, Inc.,
16 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
17 */
18
19#ifndef _LTTNG_UST_CTL_H
20#define _LTTNG_UST_CTL_H
21
22#include <lttng/ust-abi.h>
23#include <sys/types.h>
24#include <limits.h>
25
26#ifndef LTTNG_UST_UUID_LEN
27#define LTTNG_UST_UUID_LEN 16
28#endif
29
30/* Default unix socket path */
31#define LTTNG_UST_SOCK_FILENAME \
32 "lttng-ust-sock-" \
33 __ust_stringify(LTTNG_UST_ABI_MAJOR_VERSION)
34
35/*
36 * Shared memory files path are automatically related to shm root, e.g.
37 * /dev/shm under linux.
38 */
39#define LTTNG_UST_WAIT_FILENAME \
40 "lttng-ust-wait-" \
41 __ust_stringify(LTTNG_UST_ABI_MAJOR_VERSION)
42
43struct lttng_ust_shm_handle;
44struct lttng_ust_lib_ring_buffer;
45
46struct ustctl_consumer_channel_attr {
47 enum lttng_ust_chan_type type;
48 uint64_t subbuf_size; /* bytes */
49 uint64_t num_subbuf; /* power of 2 */
50 int overwrite; /* 1: overwrite, 0: discard */
51 unsigned int switch_timer_interval; /* usec */
52 unsigned int read_timer_interval; /* usec */
53 enum lttng_ust_output output; /* splice, mmap */
54 uint32_t chan_id; /* channel ID */
55 unsigned char uuid[LTTNG_UST_UUID_LEN]; /* Trace session unique ID */
56} LTTNG_PACKED;
57
58/*
59 * API used by sessiond.
60 */
61
62struct lttng_ust_context_attr {
63 enum lttng_ust_context_type ctx;
64 union {
65 struct lttng_ust_perf_counter_ctx perf_counter;
66 struct {
67 char *provider_name;
68 char *ctx_name;
69 } app_ctx;
70 } u;
71};
72
73/*
74 * Error values: all the following functions return:
75 * >= 0: Success (LTTNG_UST_OK)
76 * < 0: error code.
77 */
78int ustctl_register_done(int sock);
79int ustctl_create_session(int sock);
80int ustctl_create_event(int sock, struct lttng_ust_event *ev,
81 struct lttng_ust_object_data *channel_data,
82 struct lttng_ust_object_data **event_data);
83int ustctl_add_context(int sock, struct lttng_ust_context_attr *ctx,
84 struct lttng_ust_object_data *obj_data,
85 struct lttng_ust_object_data **context_data);
86int ustctl_set_filter(int sock, struct lttng_ust_filter_bytecode *bytecode,
87 struct lttng_ust_object_data *obj_data);
88int ustctl_set_exclusion(int sock, struct lttng_ust_event_exclusion *exclusion,
89 struct lttng_ust_object_data *obj_data);
90
91int ustctl_enable(int sock, struct lttng_ust_object_data *object);
92int ustctl_disable(int sock, struct lttng_ust_object_data *object);
93int ustctl_start_session(int sock, int handle);
94int ustctl_stop_session(int sock, int handle);
95
96/*
97 * ustctl_tracepoint_list returns a tracepoint list handle, or negative
98 * error value.
99 */
100int ustctl_tracepoint_list(int sock);
101
102/*
103 * ustctl_tracepoint_list_get is used to iterate on the tp list
104 * handle. End is iteration is reached when -LTTNG_UST_ERR_NOENT is
105 * returned.
106 */
107int ustctl_tracepoint_list_get(int sock, int tp_list_handle,
108 struct lttng_ust_tracepoint_iter *iter);
109
110/*
111 * ustctl_tracepoint_field_list returns a tracepoint field list handle,
112 * or negative error value.
113 */
114int ustctl_tracepoint_field_list(int sock);
115
116/*
117 * ustctl_tracepoint_field_list_get is used to iterate on the tp field
118 * list handle. End is iteration is reached when -LTTNG_UST_ERR_NOENT is
119 * returned.
120 */
121int ustctl_tracepoint_field_list_get(int sock, int tp_field_list_handle,
122 struct lttng_ust_field_iter *iter);
123
124int ustctl_tracer_version(int sock, struct lttng_ust_tracer_version *v);
125int ustctl_wait_quiescent(int sock);
126
127int ustctl_sock_flush_buffer(int sock, struct lttng_ust_object_data *object);
128
129int ustctl_calibrate(int sock, struct lttng_ust_calibrate *calibrate);
130
131/* Release object created by members of this API. */
132int ustctl_release_object(int sock, struct lttng_ust_object_data *data);
133/* Release handle returned by create session. */
134int ustctl_release_handle(int sock, int handle);
135
136int ustctl_recv_channel_from_consumer(int sock,
137 struct lttng_ust_object_data **channel_data);
138int ustctl_recv_stream_from_consumer(int sock,
139 struct lttng_ust_object_data **stream_data);
140int ustctl_send_channel_to_ust(int sock, int session_handle,
141 struct lttng_ust_object_data *channel_data);
142int ustctl_send_stream_to_ust(int sock,
143 struct lttng_ust_object_data *channel_data,
144 struct lttng_ust_object_data *stream_data);
145
146/*
147 * ustctl_duplicate_ust_object_data allocated a new object in "dest" if
148 * it succeeds (returns 0). It must be released using
149 * ustctl_release_object() and then freed with free().
150 */
151int ustctl_duplicate_ust_object_data(struct lttng_ust_object_data **dest,
152 struct lttng_ust_object_data *src);
153
154/*
155 * API used by consumer.
156 */
157
158struct ustctl_consumer_channel;
159struct ustctl_consumer_stream;
160struct ustctl_consumer_channel_attr;
161
162int ustctl_get_nr_stream_per_channel(void);
163
164struct ustctl_consumer_channel *
165 ustctl_create_channel(struct ustctl_consumer_channel_attr *attr,
166 const int *stream_fds, int nr_stream_fds);
167/*
168 * Each stream created needs to be destroyed before calling
169 * ustctl_destroy_channel().
170 */
171void ustctl_destroy_channel(struct ustctl_consumer_channel *chan);
172
173int ustctl_send_channel_to_sessiond(int sock,
174 struct ustctl_consumer_channel *channel);
175int ustctl_channel_close_wait_fd(struct ustctl_consumer_channel *consumer_chan);
176int ustctl_channel_close_wakeup_fd(struct ustctl_consumer_channel *consumer_chan);
177int ustctl_channel_get_wait_fd(struct ustctl_consumer_channel *consumer_chan);
178int ustctl_channel_get_wakeup_fd(struct ustctl_consumer_channel *consumer_chan);
179
180int ustctl_write_metadata_to_channel(
181 struct ustctl_consumer_channel *channel,
182 const char *metadata_str, /* NOT null-terminated */
183 size_t len); /* metadata length */
184ssize_t ustctl_write_one_packet_to_channel(
185 struct ustctl_consumer_channel *channel,
186 const char *metadata_str, /* NOT null-terminated */
187 size_t len); /* metadata length */
188
189/*
190 * Send a NULL stream to finish iteration over all streams of a given
191 * channel.
192 */
193int ustctl_send_stream_to_sessiond(int sock,
194 struct ustctl_consumer_stream *stream);
195int ustctl_stream_close_wait_fd(struct ustctl_consumer_stream *stream);
196int ustctl_stream_close_wakeup_fd(struct ustctl_consumer_stream *stream);
197int ustctl_stream_get_wait_fd(struct ustctl_consumer_stream *stream);
198int ustctl_stream_get_wakeup_fd(struct ustctl_consumer_stream *stream);
199
200/* Create/destroy stream buffers for read */
201struct ustctl_consumer_stream *
202 ustctl_create_stream(struct ustctl_consumer_channel *channel,
203 int cpu);
204void ustctl_destroy_stream(struct ustctl_consumer_stream *stream);
205
206/* For mmap mode, readable without "get" operation */
207int ustctl_get_mmap_len(struct ustctl_consumer_stream *stream,
208 unsigned long *len);
209int ustctl_get_max_subbuf_size(struct ustctl_consumer_stream *stream,
210 unsigned long *len);
211
212/*
213 * For mmap mode, operate on the current packet (between get/put or
214 * get_next/put_next).
215 */
216void *ustctl_get_mmap_base(struct ustctl_consumer_stream *stream);
217int ustctl_get_mmap_read_offset(struct ustctl_consumer_stream *stream,
218 unsigned long *off);
219int ustctl_get_subbuf_size(struct ustctl_consumer_stream *stream,
220 unsigned long *len);
221int ustctl_get_padded_subbuf_size(struct ustctl_consumer_stream *stream,
222 unsigned long *len);
223int ustctl_get_next_subbuf(struct ustctl_consumer_stream *stream);
224int ustctl_put_next_subbuf(struct ustctl_consumer_stream *stream);
225
226/* snapshot */
227
228int ustctl_snapshot(struct ustctl_consumer_stream *stream);
229int ustctl_snapshot_get_consumed(struct ustctl_consumer_stream *stream,
230 unsigned long *pos);
231int ustctl_snapshot_get_produced(struct ustctl_consumer_stream *stream,
232 unsigned long *pos);
233int ustctl_get_subbuf(struct ustctl_consumer_stream *stream,
234 unsigned long *pos);
235int ustctl_put_subbuf(struct ustctl_consumer_stream *stream);
236
237void ustctl_flush_buffer(struct ustctl_consumer_stream *stream,
238 int producer_active);
239
240/* index */
241int ustctl_get_timestamp_begin(struct ustctl_consumer_stream *stream,
242 uint64_t *timestamp_begin);
243int ustctl_get_timestamp_end(struct ustctl_consumer_stream *stream,
244 uint64_t *timestamp_end);
245int ustctl_get_events_discarded(struct ustctl_consumer_stream *stream,
246 uint64_t *events_discarded);
247int ustctl_get_content_size(struct ustctl_consumer_stream *stream,
248 uint64_t *content_size);
249int ustctl_get_packet_size(struct ustctl_consumer_stream *stream,
250 uint64_t *packet_size);
251int ustctl_get_stream_id(struct ustctl_consumer_stream *stream,
252 uint64_t *stream_id);
253int ustctl_get_current_timestamp(struct ustctl_consumer_stream *stream,
254 uint64_t *ts);
255int ustctl_get_sequence_number(struct ustctl_consumer_stream *stream,
256 uint64_t *seq);
257
258/* returns whether UST has perf counters support. */
259int ustctl_has_perf_counters(void);
260
261/* event registry management */
262
263enum ustctl_socket_type {
264 USTCTL_SOCKET_CMD = 0,
265 USTCTL_SOCKET_NOTIFY = 1,
266};
267
268enum ustctl_notify_cmd {
269 USTCTL_NOTIFY_CMD_EVENT = 0,
270 USTCTL_NOTIFY_CMD_CHANNEL = 1,
271 USTCTL_NOTIFY_CMD_ENUM = 2,
272};
273
274enum ustctl_channel_header {
275 USTCTL_CHANNEL_HEADER_UNKNOWN = 0,
276 USTCTL_CHANNEL_HEADER_COMPACT = 1,
277 USTCTL_CHANNEL_HEADER_LARGE = 2,
278};
279
280/* event type structures */
281
282enum ustctl_abstract_types {
283 ustctl_atype_integer,
284 ustctl_atype_enum,
285 ustctl_atype_array,
286 ustctl_atype_sequence,
287 ustctl_atype_string,
288 ustctl_atype_float,
289 ustctl_atype_variant,
290 ustctl_atype_struct,
291 NR_USTCTL_ABSTRACT_TYPES,
292};
293
294enum ustctl_string_encodings {
295 ustctl_encode_none = 0,
296 ustctl_encode_UTF8 = 1,
297 ustctl_encode_ASCII = 2,
298 NR_USTCTL_STRING_ENCODINGS,
299};
300
301#define USTCTL_UST_INTEGER_TYPE_PADDING 24
302struct ustctl_integer_type {
303 uint32_t size; /* in bits */
304 uint32_t signedness;
305 uint32_t reverse_byte_order;
306 uint32_t base; /* 2, 8, 10, 16, for pretty print */
307 enum ustctl_string_encodings encoding;
308 uint16_t alignment; /* in bits */
309 char padding[USTCTL_UST_INTEGER_TYPE_PADDING];
310} LTTNG_PACKED;
311
312#define USTCTL_UST_FLOAT_TYPE_PADDING 24
313struct ustctl_float_type {
314 uint32_t exp_dig; /* exponent digits, in bits */
315 uint32_t mant_dig; /* mantissa digits, in bits */
316 uint32_t reverse_byte_order;
317 uint16_t alignment; /* in bits */
318 char padding[USTCTL_UST_FLOAT_TYPE_PADDING];
319} LTTNG_PACKED;
320
321#define USTCTL_UST_ENUM_ENTRY_PADDING 32
322struct ustctl_enum_entry {
323 uint64_t start, end; /* start and end are inclusive */
324 char string[LTTNG_UST_SYM_NAME_LEN];
325 char padding[USTCTL_UST_ENUM_ENTRY_PADDING];
326};
327
328#define USTCTL_UST_BASIC_TYPE_PADDING 296
329union _ustctl_basic_type {
330 struct ustctl_integer_type integer;
331 struct {
332 char name[LTTNG_UST_SYM_NAME_LEN];
333 struct ustctl_integer_type container_type;
334 uint64_t id; /* enum ID in sessiond. */
335 } enumeration;
336 struct {
337 enum ustctl_string_encodings encoding;
338 } string;
339 struct ustctl_float_type _float;
340 char padding[USTCTL_UST_BASIC_TYPE_PADDING];
341} LTTNG_PACKED;
342
343struct ustctl_basic_type {
344 enum ustctl_abstract_types atype;
345 union {
346 union _ustctl_basic_type basic;
347 } u;
348} LTTNG_PACKED;
349
350#define USTCTL_UST_TYPE_PADDING 128
351struct ustctl_type {
352 enum ustctl_abstract_types atype;
353 union {
354 union _ustctl_basic_type basic;
355 struct {
356 struct ustctl_basic_type elem_type;
357 uint32_t length; /* num. elems. */
358 } array;
359 struct {
360 struct ustctl_basic_type length_type;
361 struct ustctl_basic_type elem_type;
362 } sequence;
363 struct {
364 uint32_t nr_choices;
365 char tag_name[LTTNG_UST_SYM_NAME_LEN];
366 /* Followed by nr_choices struct ustctl_field. */
367 } variant;
368 struct {
369 uint32_t nr_fields;
370 /* Followed by nr_fields struct ustctl_field. */
371 } _struct;
372 char padding[USTCTL_UST_TYPE_PADDING];
373 } u;
374} LTTNG_PACKED;
375
376#define USTCTL_UST_FIELD_PADDING 28
377struct ustctl_field {
378 char name[LTTNG_UST_SYM_NAME_LEN];
379 struct ustctl_type type;
380 char padding[USTCTL_UST_FIELD_PADDING];
381} LTTNG_PACKED;
382
383/*
384 * Returns 0 on success, negative error value on error.
385 * If an error other than -LTTNG_UST_ERR_UNSUP_MAJOR is returned,
386 * the output fields are not populated.
387 */
388int ustctl_recv_reg_msg(int sock,
389 enum ustctl_socket_type *type,
390 uint32_t *major,
391 uint32_t *minor,
392 uint32_t *pid,
393 uint32_t *ppid,
394 uint32_t *uid,
395 uint32_t *gid,
396 uint32_t *bits_per_long,
397 uint32_t *uint8_t_alignment,
398 uint32_t *uint16_t_alignment,
399 uint32_t *uint32_t_alignment,
400 uint32_t *uint64_t_alignment,
401 uint32_t *long_alignment,
402 int *byte_order,
403 char *name); /* size LTTNG_UST_ABI_PROCNAME_LEN */
404
405/*
406 * Returns 0 on success, negative UST or system error value on error.
407 * Receive the notification command. The "notify_cmd" can then be used
408 * by the caller to find out which ustctl_recv_* function should be
409 * called to receive the notification, and which ustctl_reply_* is
410 * appropriate.
411 */
412int ustctl_recv_notify(int sock, enum ustctl_notify_cmd *notify_cmd);
413
414/*
415 * Returns 0 on success, negative UST or system error value on error.
416 */
417int ustctl_recv_register_event(int sock,
418 int *session_objd, /* session descriptor (output) */
419 int *channel_objd, /* channel descriptor (output) */
420 char *event_name, /*
421 * event name (output,
422 * size LTTNG_UST_SYM_NAME_LEN)
423 */
424 int *loglevel,
425 char **signature, /*
426 * event signature
427 * (output, dynamically
428 * allocated, must be free(3)'d
429 * by the caller if function
430 * returns success.)
431 */
432 size_t *nr_fields,
433 struct ustctl_field **fields,
434 char **model_emf_uri);
435
436/*
437 * Returns 0 on success, negative error value on error.
438 */
439int ustctl_reply_register_event(int sock,
440 uint32_t id, /* event id (input) */
441 int ret_code); /* return code. 0 ok, negative error */
442
443/*
444 * Returns 0 on success, negative UST or system error value on error.
445 */
446int ustctl_recv_register_enum(int sock,
447 int *session_objd,
448 char *enum_name,
449 struct ustctl_enum_entry **entries,
450 size_t *nr_entries);
451
452/*
453 * Returns 0 on success, negative error value on error.
454 */
455int ustctl_reply_register_enum(int sock,
456 uint64_t id, /* enum id (input) */
457 int ret_code);
458
459/*
460 * Returns 0 on success, negative UST or system error value on error.
461 */
462int ustctl_recv_register_channel(int sock,
463 int *session_objd, /* session descriptor (output) */
464 int *channel_objd, /* channel descriptor (output) */
465 size_t *nr_fields, /* context fields */
466 struct ustctl_field **fields);
467
468/*
469 * Returns 0 on success, negative error value on error.
470 */
471int ustctl_reply_register_channel(int sock,
472 uint32_t chan_id,
473 enum ustctl_channel_header header_type,
474 int ret_code); /* return code. 0 ok, negative error */
475
476#endif /* _LTTNG_UST_CTL_H */
This page took 0.027419 seconds and 4 git commands to generate.