Rename: bt_put(), bt_get() -> bt_object_put_ref(), bt_object_get_ref()
[babeltrace.git] / include / babeltrace / ctf-writer / clock.h
CommitLineData
8c18d80b
PP
1#ifndef BABELTRACE_CTF_WRITER_CLOCK_H
2#define BABELTRACE_CTF_WRITER_CLOCK_H
3
46bd0f2b
JG
4/*
5 * BabelTrace - CTF Writer: Clock
6 *
de9dd397 7 * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
46bd0f2b
JG
8 *
9 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
10 *
11 * Permission is hereby granted, free of charge, to any person obtaining a copy
12 * of this software and associated documentation files (the "Software"), to deal
13 * in the Software without restriction, including without limitation the rights
14 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15 * copies of the Software, and to permit persons to whom the Software is
16 * furnished to do so, subject to the following conditions:
17 *
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
20 *
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27 * SOFTWARE.
28 *
29 * The Common Trace Format (CTF) Specification is available at
30 * http://www.efficios.com/ctf
31 */
32
ac0c6bdd 33#include <stdint.h>
8138bfe1 34#include <babeltrace/object.h>
8deee039 35#include <babeltrace/types.h>
8c18d80b
PP
36
37#ifdef __cplusplus
38extern "C" {
39#endif
40
ac0c6bdd 41struct bt_ctf_clock;
8deee039 42struct bt_ctf_clock_class;
ac0c6bdd
PP
43
44/*
45 * bt_ctf_clock_create: create a clock.
46 *
47 * Allocate a new clock setting its reference count to 1.
48 *
49 * @param name Name of the clock (will be copied); can be set to NULL
50 * for nameless clocks.
51 *
52 * Returns an allocated clock on success, NULL on error.
53 */
54extern struct bt_ctf_clock *bt_ctf_clock_create(const char *name);
55
56/*
57 * bt_ctf_clock_get_name: get a clock's name.
58 *
59 * Get the clock's name.
60 *
61 * @param clock Clock instance.
62 *
63 * Returns the clock's name, NULL on error.
64 */
65extern const char *bt_ctf_clock_get_name(struct bt_ctf_clock *clock);
66
67/*
68 * bt_ctf_clock_get_description: get a clock's description.
69 *
70 * Get the clock's description.
71 *
72 * @param clock Clock instance.
73 *
74 * Returns the clock's description, NULL if unset.
75 */
76extern const char *bt_ctf_clock_get_description(struct bt_ctf_clock *clock);
77
78/*
79 * bt_ctf_clock_set_description: set a clock's description.
80 *
81 * Set the clock's description. The description appears in the clock's TSDL
82 * meta-data.
83 *
84 * @param clock Clock instance.
85 * @param desc Description of the clock.
86 *
87 * Returns 0 on success, a negative value on error.
88 */
89extern int bt_ctf_clock_set_description(struct bt_ctf_clock *clock,
90 const char *desc);
91
92/*
93 * bt_ctf_clock_get_frequency: get a clock's frequency.
94 *
95 * Get the clock's frequency (Hz).
96 *
97 * @param clock Clock instance.
98 *
99 * Returns the clock's frequency, -1ULL on error.
100 */
101extern uint64_t bt_ctf_clock_get_frequency(struct bt_ctf_clock *clock);
102
103/*
104 * bt_ctf_clock_set_frequency: set a clock's frequency.
105 *
106 * Set the clock's frequency (Hz).
107 *
108 * @param clock Clock instance.
109 * @param freq Clock's frequency in Hz, defaults to 1 000 000 000 Hz (1ns).
110 *
111 * Returns 0 on success, a negative value on error.
112 */
113extern int bt_ctf_clock_set_frequency(struct bt_ctf_clock *clock,
114 uint64_t freq);
115
116/*
117 * bt_ctf_clock_get_precision: get a clock's precision.
118 *
119 * Get the clock's precision (in clock ticks).
120 *
121 * @param clock Clock instance.
122 *
123 * Returns the clock's precision, -1ULL on error.
124 */
125extern uint64_t bt_ctf_clock_get_precision(struct bt_ctf_clock *clock);
126
127/*
128 * bt_ctf_clock_set_precision: set a clock's precision.
129 *
130 * Set the clock's precision.
131 *
132 * @param clock Clock instance.
133 * @param precision Clock's precision in clock ticks, defaults to 1.
134 *
135 * Returns 0 on success, a negative value on error.
136 */
137extern int bt_ctf_clock_set_precision(struct bt_ctf_clock *clock,
138 uint64_t precision);
139
140/*
141 * bt_ctf_clock_get_offset_s: get a clock's offset in seconds.
142 *
143 * Get the clock's offset in seconds from POSIX.1 Epoch, 1970-01-01.
144 *
145 * @param clock Clock instance.
146 * @param offset_s Pointer to clock offset in seconds (output).
147 *
148 * Returns 0 on success, a negative value on error.
149 */
150extern int bt_ctf_clock_get_offset_s(struct bt_ctf_clock *clock,
151 int64_t *offset_s);
152
153/*
154 * bt_ctf_clock_set_offset_s: set a clock's offset in seconds.
155 *
156 * Set the clock's offset in seconds from POSIX.1 Epoch, 1970-01-01,
157 * defaults to 0.
158 *
159 * @param clock Clock instance.
160 * @param offset_s Clock's offset in seconds, defaults to 0.
161 *
162 * Returns 0 on success, a negative value on error.
163 */
164extern int bt_ctf_clock_set_offset_s(struct bt_ctf_clock *clock,
165 int64_t offset_s);
166
167/*
168 * bt_ctf_clock_get_offset: get a clock's offset in ticks.
169 *
170 * Get the clock's offset in ticks from Epoch + offset_t.
171 *
172 * @param clock Clock instance.
173 * @param offset Clock offset in ticks from Epoch + offset_s (output).
174 *
175 * Returns 0 on success, a negative value on error.
176 */
177extern int bt_ctf_clock_get_offset(struct bt_ctf_clock *clock,
178 int64_t *offset);
179
180/*
181 * bt_ctf_clock_set_offset: set a clock's offset in ticks.
182 *
183 * Set the clock's offset in ticks from Epoch + offset_s.
184 *
185 * @param clock Clock instance.
186 * @param offset Clock's offset in ticks from Epoch + offset_s, defaults to 0.
187 *
188 * Returns 0 on success, a negative value on error.
189 */
190extern int bt_ctf_clock_set_offset(struct bt_ctf_clock *clock,
191 int64_t offset);
192
193/*
194 * bt_ctf_clock_get_is_absolute: get a clock's absolute attribute.
195 *
196 * Get the clock's absolute attribute. A clock is absolute if the clock is a
197 * global reference across the trace's other clocks.
198 *
199 * @param clock Clock instance.
200 *
201 * Returns the clock's absolute attribute, a negative value on error.
202 */
203extern int bt_ctf_clock_get_is_absolute(struct bt_ctf_clock *clock);
204
205/*
206 * bt_ctf_clock_set_is_absolute: set a clock's absolute attribute.
207 *
208 * Set the clock's absolute attribute. A clock is absolute if the clock is a
209 * global reference across the trace's other clocks.
210 *
211 * @param clock Clock instance.
212 * @param is_absolute Clock's absolute attribute, defaults to FALSE.
213 *
214 * Returns 0 on success, a negative value on error.
215 */
216extern int bt_ctf_clock_set_is_absolute(struct bt_ctf_clock *clock,
217 int is_absolute);
218
219/*
220 * bt_ctf_clock_get_uuid: get a clock's UUID.
221 *
222 * Get the clock's UUID.
223 *
224 * @param clock Clock instance.
225 *
226 * Returns a pointer to the clock's UUID (16 byte array) on success,
227 * NULL on error.
228 */
229extern const unsigned char *bt_ctf_clock_get_uuid(struct bt_ctf_clock *clock);
230
231/*
232 * bt_ctf_clock_set_uuid: set a clock's UUID.
233 *
234 * Set a clock's UUID.
235 *
236 * @param clock Clock instance.
237 * @param uuid A 16-byte array containing a UUID.
238 *
239 * Returns 0 on success, a negative value on error.
240 */
241extern int bt_ctf_clock_set_uuid(struct bt_ctf_clock *clock,
242 const unsigned char *uuid);
243
64cf1d3a
PP
244/*
245 * bt_ctf_clock_set_time: set a clock's current time value.
246 *
247 * Set the current time in nanoseconds since the clock's origin (offset and
248 * offset_s attributes). Defaults to 0.
249 *
250 * Returns 0 on success, a negative value on error.
251 */
252extern int bt_ctf_clock_set_time(struct bt_ctf_clock *clock,
253 int64_t time);
254
8c18d80b
PP
255/*
256 * bt_ctf_clock_get and bt_ctf_clock_put: increment and decrement the
257 * refcount of the clock
258 *
259 * You may also use bt_ctf_get() and bt_ctf_put() with clock objects.
260 *
261 * These functions ensure that the clock won't be destroyed when it
262 * is in use. The same number of get and put (plus one extra put to
263 * release the initial reference done at creation) has to be done to
264 * destroy a clock.
265 *
266 * When the clock refcount is decremented to 0 by a bt_ctf_clock_put,
267 * the clock is freed.
268 *
269 * @param clock Clock instance.
270 */
8deee039
PP
271
272/* Pre-2.0 CTF writer compatibility */
273static inline
274void bt_ctf_clock_get(struct bt_ctf_clock *clock)
275{
8138bfe1 276 bt_object_get_ref(clock);
8deee039
PP
277}
278
279/* Pre-2.0 CTF writer compatibility */
280static inline
281void bt_ctf_clock_put(struct bt_ctf_clock *clock)
282{
8138bfe1 283 bt_object_put_ref(clock);
8deee039
PP
284}
285
286extern struct bt_ctf_clock_class *bt_ctf_clock_class_create(const char *name,
287 uint64_t freq);
288
289extern const char *bt_ctf_clock_class_get_name(
290 struct bt_ctf_clock_class *clock_class);
291
292extern int bt_ctf_clock_class_set_name(struct bt_ctf_clock_class *clock_class,
293 const char *name);
294
295extern const char *bt_ctf_clock_class_get_description(
296 struct bt_ctf_clock_class *clock_class);
297
298extern int bt_ctf_clock_class_set_description(
299 struct bt_ctf_clock_class *clock_class,
300 const char *desc);
301
302extern uint64_t bt_ctf_clock_class_get_frequency(
303 struct bt_ctf_clock_class *clock_class);
304
305extern int bt_ctf_clock_class_set_frequency(
306 struct bt_ctf_clock_class *clock_class, uint64_t freq);
307
308extern uint64_t bt_ctf_clock_class_get_precision(
309 struct bt_ctf_clock_class *clock_class);
310
311extern int bt_ctf_clock_class_set_precision(
312 struct bt_ctf_clock_class *clock_class, uint64_t precision);
313
314extern int bt_ctf_clock_class_get_offset_s(
315 struct bt_ctf_clock_class *clock_class, int64_t *seconds);
316
317extern int bt_ctf_clock_class_set_offset_s(
318 struct bt_ctf_clock_class *clock_class, int64_t seconds);
319
320extern int bt_ctf_clock_class_get_offset_cycles(
321 struct bt_ctf_clock_class *clock_class, int64_t *cycles);
322
323extern int bt_ctf_clock_class_set_offset_cycles(
324 struct bt_ctf_clock_class *clock_class, int64_t cycles);
325
326extern bt_bool bt_ctf_clock_class_is_absolute(
327 struct bt_ctf_clock_class *clock_class);
328
329extern int bt_ctf_clock_class_set_is_absolute(
330 struct bt_ctf_clock_class *clock_class, bt_bool is_absolute);
331
332extern const unsigned char *bt_ctf_clock_class_get_uuid(
333 struct bt_ctf_clock_class *clock_class);
334
335extern int bt_ctf_clock_class_set_uuid(struct bt_ctf_clock_class *clock_class,
336 const unsigned char *uuid);
8c18d80b
PP
337
338#ifdef __cplusplus
339}
340#endif
341
342#endif /* BABELTRACE_CTF_WRITER_CLOCK_H */
This page took 0.061117 seconds and 4 git commands to generate.