include/babeltrace2-ctf-writer/clock.h

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