include/babeltrace2-ctf-writer/clock.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
   5  */
   6
   7 #ifndef BABELTRACE2_CTF_WRITER_CLOCK_H
   8 #define BABELTRACE2_CTF_WRITER_CLOCK_H
   9
  10 #include <stdint.h>
  11 #include <babeltrace2-ctf-writer/object.h>
  12 #include <babeltrace2-ctf-writer/types.h>
  13
  14 #ifdef __cplusplus
  15 extern "C" {
  16 #endif
  17
  18 struct bt_ctf_clock;
  19 struct bt_ctf_clock_class;
  20
  21 /*
  22  * bt_ctf_clock_create: create a clock.
  23  *
  24  * Allocate a new clock setting its reference count to 1.
  25  *
  26  * @param name Name of the clock (will be copied); can be set to NULL
  27  *             for nameless clocks.
  28  *
  29  * Returns an allocated clock on success, NULL on error.
  30  */
  31 extern struct bt_ctf_clock *bt_ctf_clock_create(const char *name);
  32
  33 /*
  34  * bt_ctf_clock_get_name: get a clock's name.
  35  *
  36  * Get the clock's name.
  37  *
  38  * @param clock Clock instance.
  39  *
  40  * Returns the clock's name, NULL on error.
  41  */
  42 extern const char *bt_ctf_clock_get_name(struct bt_ctf_clock *clock);
  43
  44 /*
  45  * bt_ctf_clock_get_description: get a clock's description.
  46  *
  47  * Get the clock's description.
  48  *
  49  * @param clock Clock instance.
  50  *
  51  * Returns the clock's description, NULL if unset.
  52  */
  53 extern const char *bt_ctf_clock_get_description(struct bt_ctf_clock *clock);
  54
  55 /*
  56  * bt_ctf_clock_set_description: set a clock's description.
  57  *
  58  * Set the clock's description. The description appears in the clock's TSDL
  59  * meta-data.
  60  *
  61  * @param clock Clock instance.
  62  * @param desc Description of the clock.
  63  *
  64  * Returns 0 on success, a negative value on error.
  65  */
  66 extern int bt_ctf_clock_set_description(struct bt_ctf_clock *clock,
  67         const char *desc);
  68
  69 /*
  70  * bt_ctf_clock_get_frequency: get a clock's frequency.
  71  *
  72  * Get the clock's frequency (Hz).
  73  *
  74  * @param clock Clock instance.
  75  *
  76  * Returns the clock's frequency, -1ULL on error.
  77  */
  78 extern uint64_t bt_ctf_clock_get_frequency(struct bt_ctf_clock *clock);
  79
  80 /*
  81  * bt_ctf_clock_set_frequency: set a clock's frequency.
  82  *
  83  * Set the clock's frequency (Hz).
  84  *
  85  * @param clock Clock instance.
  86  * @param freq Clock's frequency in Hz, defaults to 1 000 000 000 Hz (1ns).
  87  *
  88  * Returns 0 on success, a negative value on error.
  89  */
  90 extern int bt_ctf_clock_set_frequency(struct bt_ctf_clock *clock,
  91         uint64_t freq);
  92
  93 /*
  94  * bt_ctf_clock_get_precision: get a clock's precision.
  95  *
  96  * Get the clock's precision (in clock ticks).
  97  *
  98  * @param clock Clock instance.
  99  *
 100  * Returns the clock's precision, -1ULL on error.
 101  */
 102 extern uint64_t bt_ctf_clock_get_precision(struct bt_ctf_clock *clock);
 103
 104 /*
 105  * bt_ctf_clock_set_precision: set a clock's precision.
 106  *
 107  * Set the clock's precision.
 108  *
 109  * @param clock Clock instance.
 110  * @param precision Clock's precision in clock ticks, defaults to 1.
 111  *
 112  * Returns 0 on success, a negative value on error.
 113  */
 114 extern int bt_ctf_clock_set_precision(struct bt_ctf_clock *clock,
 115         uint64_t precision);
 116
 117 /*
 118  * bt_ctf_clock_get_offset_s: get a clock's offset in seconds.
 119  *
 120  * Get the clock's offset in seconds from POSIX.1 Epoch, 1970-01-01.
 121  *
 122  * @param clock Clock instance.
 123  * @param offset_s Pointer to clock offset in seconds (output).
 124  *
 125  * Returns 0 on success, a negative value on error.
 126  */
 127 extern int bt_ctf_clock_get_offset_s(struct bt_ctf_clock *clock,
 128         int64_t *offset_s);
 129
 130 /*
 131  * bt_ctf_clock_set_offset_s: set a clock's offset in seconds.
 132  *
 133  * Set the clock's offset in seconds from POSIX.1 Epoch, 1970-01-01,
 134  * defaults to 0.
 135  *
 136  * @param clock Clock instance.
 137  * @param offset_s Clock's offset in seconds, defaults to 0.
 138  *
 139  * Returns 0 on success, a negative value on error.
 140  */
 141 extern int bt_ctf_clock_set_offset_s(struct bt_ctf_clock *clock,
 142         int64_t offset_s);
 143
 144 /*
 145  * bt_ctf_clock_get_offset: get a clock's offset in ticks.
 146  *
 147  * Get the clock's offset in ticks from Epoch + offset_t.
 148  *
 149  * @param clock Clock instance.
 150  * @param offset Clock offset in ticks from Epoch + offset_s (output).
 151  *
 152  * Returns 0 on success, a negative value on error.
 153  */
 154 extern int bt_ctf_clock_get_offset(struct bt_ctf_clock *clock,
 155         int64_t *offset);
 156
 157 /*
 158  * bt_ctf_clock_set_offset: set a clock's offset in ticks.
 159  *
 160  * Set the clock's offset in ticks from Epoch + offset_s.
 161  *
 162  * @param clock Clock instance.
 163  * @param offset Clock's offset in ticks from Epoch + offset_s, defaults to 0.
 164  *
 165  * Returns 0 on success, a negative value on error.
 166  */
 167 extern int bt_ctf_clock_set_offset(struct bt_ctf_clock *clock,
 168         int64_t offset);
 169
 170 /*
 171  * bt_ctf_clock_get_is_absolute: get a clock's absolute attribute.
 172  *
 173  * Get the clock's absolute attribute. A clock is absolute if the clock is a
 174  * global reference across the trace's other clocks.
 175  *
 176  * @param clock Clock instance.
 177  *
 178  * Returns the clock's absolute attribute, a negative value on error.
 179  */
 180 extern int bt_ctf_clock_get_is_absolute(struct bt_ctf_clock *clock);
 181
 182 /*
 183  * bt_ctf_clock_set_is_absolute: set a clock's absolute attribute.
 184  *
 185  * Set the clock's absolute attribute. A clock is absolute if the clock is a
 186  * global reference across the trace's other clocks.
 187  *
 188  * @param clock Clock instance.
 189  * @param is_absolute Clock's absolute attribute, defaults to FALSE.
 190  *
 191  * Returns 0 on success, a negative value on error.
 192  */
 193 extern int bt_ctf_clock_set_is_absolute(struct bt_ctf_clock *clock,
 194         int is_absolute);
 195
 196 /*
 197  * bt_ctf_clock_get_uuid: get a clock's UUID.
 198  *
 199  * Get the clock's UUID.
 200  *
 201  * @param clock Clock instance.
 202  *
 203  * Returns a pointer to the clock's UUID (16 byte array) on success,
 204  * NULL on error.
 205  */
 206 extern const uint8_t *bt_ctf_clock_get_uuid(struct bt_ctf_clock *clock);
 207
 208 /*
 209  * bt_ctf_clock_set_uuid: set a clock's UUID.
 210  *
 211  * Set a clock's UUID.
 212  *
 213  * @param clock Clock instance.
 214  * @param uuid A 16-byte array containing a UUID.
 215  *
 216  * Returns 0 on success, a negative value on error.
 217  */
 218 extern int bt_ctf_clock_set_uuid(struct bt_ctf_clock *clock,
 219         const uint8_t *uuid);
 220
 221 /*
 222  * bt_ctf_clock_set_time: set a clock's current time value.
 223  *
 224  * Set the current time in nanoseconds since the clock's origin (offset and
 225  * offset_s attributes). Defaults to 0.
 226  *
 227  * Returns 0 on success, a negative value on error.
 228  */
 229 extern int bt_ctf_clock_set_time(struct bt_ctf_clock *clock,
 230                 int64_t time);
 231
 232 /*
 233  * bt_ctf_clock_get and bt_ctf_clock_put: increment and decrement the
 234  * refcount of the clock
 235  *
 236  * You may also use bt_ctf_get() and bt_ctf_put() with clock objects.
 237  *
 238  * These functions ensure that the clock won't be destroyed when it
 239  * is in use. The same number of get and put (plus one extra put to
 240  * release the initial reference done at creation) has to be done to
 241  * destroy a clock.
 242  *
 243  * When the clock refcount is decremented to 0 by a bt_ctf_clock_put,
 244  * the clock is freed.
 245  *
 246  * @param clock Clock instance.
 247  */
 248
 249 /* Pre-2.0 CTF writer compatibility */
 250 static inline
 251 void bt_ctf_clock_get(struct bt_ctf_clock *clock)
 252 {
 253         bt_ctf_object_get_ref(clock);
 254 }
 255
 256 /* Pre-2.0 CTF writer compatibility */
 257 static inline
 258 void bt_ctf_clock_put(struct bt_ctf_clock *clock)
 259 {
 260         bt_ctf_object_put_ref(clock);
 261 }
 262 #ifdef __cplusplus
 263 }
 264 #endif
 265
 266 #endif /* BABELTRACE2_CTF_WRITER_CLOCK_H */