include/babeltrace/ctf-ir/clock.h

   1 #ifndef BABELTRACE_CTF_IR_CLOCK_H
   2 #define BABELTRACE_CTF_IR_CLOCK_H
   3
   4 /*
   5  * BabelTrace - CTF IR: Clock
   6  *
   7  * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   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
  33 #include <stdint.h>
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 struct bt_ctf_clock;
  40
  41 /*
  42  * bt_ctf_clock_create: create a clock.
  43  *
  44  * Allocate a new clock setting its reference count to 1.
  45  *
  46  * @param name Name of the clock (will be copied); can be set to NULL
  47  *             for nameless clocks.
  48  *
  49  * Returns an allocated clock on success, NULL on error.
  50  */
  51 extern struct bt_ctf_clock *bt_ctf_clock_create(const char *name);
  52
  53 /*
  54  * bt_ctf_clock_get_name: get a clock's name.
  55  *
  56  * Get the clock's name.
  57  *
  58  * @param clock Clock instance.
  59  *
  60  * Returns the clock's name, NULL on error.
  61  */
  62 extern const char *bt_ctf_clock_get_name(struct bt_ctf_clock *clock);
  63
  64 /*
  65  * bt_ctf_clock_set_name: set a clock's name.
  66  *
  67  * Set a clock's name.
  68  *
  69  * @param name Name of the clock (will be copied).
  70  *
  71  * Returns 0 on success, a negative value on error.
  72  */
  73 extern int bt_ctf_clock_set_name(struct bt_ctf_clock *clock, const char *name);
  74
  75 /*
  76  * bt_ctf_clock_get_description: get a clock's description.
  77  *
  78  * Get the clock's description.
  79  *
  80  * @param clock Clock instance.
  81  *
  82  * Returns the clock's description, NULL if unset.
  83  */
  84 extern const char *bt_ctf_clock_get_description(struct bt_ctf_clock *clock);
  85
  86 /*
  87  * bt_ctf_clock_set_description: set a clock's description.
  88  *
  89  * Set the clock's description. The description appears in the clock's TSDL
  90  * meta-data.
  91  *
  92  * @param clock Clock instance.
  93  * @param desc Description of the clock.
  94  *
  95  * Returns 0 on success, a negative value on error.
  96  */
  97 extern int bt_ctf_clock_set_description(struct bt_ctf_clock *clock,
  98                 const char *desc);
  99
 100 /*
 101  * bt_ctf_clock_get_frequency: get a clock's frequency.
 102  *
 103  * Get the clock's frequency (Hz).
 104  *
 105  * @param clock Clock instance.
 106  *
 107  * Returns the clock's frequency, -1ULL on error.
 108  */
 109 extern uint64_t bt_ctf_clock_get_frequency(struct bt_ctf_clock *clock);
 110
 111 /*
 112  * bt_ctf_clock_set_frequency: set a clock's frequency.
 113  *
 114  * Set the clock's frequency (Hz).
 115  *
 116  * @param clock Clock instance.
 117  * @param freq Clock's frequency in Hz, defaults to 1 000 000 000 Hz (1ns).
 118  *
 119  * Returns 0 on success, a negative value on error.
 120  */
 121 extern int bt_ctf_clock_set_frequency(struct bt_ctf_clock *clock,
 122                 uint64_t freq);
 123
 124 /*
 125  * bt_ctf_clock_get_precision: get a clock's precision.
 126  *
 127  * Get the clock's precision (in clock ticks).
 128  *
 129  * @param clock Clock instance.
 130  *
 131  * Returns the clock's precision, -1ULL on error.
 132  */
 133 extern uint64_t bt_ctf_clock_get_precision(struct bt_ctf_clock *clock);
 134
 135 /*
 136  * bt_ctf_clock_set_precision: set a clock's precision.
 137  *
 138  * Set the clock's precision.
 139  *
 140  * @param clock Clock instance.
 141  * @param precision Clock's precision in clock ticks, defaults to 1.
 142  *
 143  * Returns 0 on success, a negative value on error.
 144  */
 145 extern int bt_ctf_clock_set_precision(struct bt_ctf_clock *clock,
 146                 uint64_t precision);
 147
 148 /*
 149  * bt_ctf_clock_get_offset_s: get a clock's offset in seconds.
 150  *
 151  * Get the clock's offset in seconds from POSIX.1 Epoch, 1970-01-01.
 152  *
 153  * @param clock Clock instance.
 154  * @param offset_s Pointer to clock offset in seconds (output).
 155  *
 156  * Returns 0 on success, a negative value on error.
 157  */
 158 extern int bt_ctf_clock_get_offset_s(struct bt_ctf_clock *clock,
 159                 int64_t *offset_s);
 160
 161 /*
 162  * bt_ctf_clock_set_offset_s: set a clock's offset in seconds.
 163  *
 164  * Set the clock's offset in seconds from POSIX.1 Epoch, 1970-01-01,
 165  * defaults to 0.
 166  *
 167  * @param clock Clock instance.
 168  * @param offset_s Clock's offset in seconds, defaults to 0.
 169  *
 170  * Returns 0 on success, a negative value on error.
 171  */
 172 extern int bt_ctf_clock_set_offset_s(struct bt_ctf_clock *clock,
 173                 int64_t offset_s);
 174
 175 /*
 176  * bt_ctf_clock_get_offset: get a clock's offset in ticks.
 177  *
 178  * Get the clock's offset in ticks from Epoch + offset_t.
 179  *
 180  * @param clock Clock instance.
 181  * @param offset Clock offset in ticks from Epoch + offset_s (output).
 182  *
 183  * Returns 0 on success, a negative value on error.
 184  */
 185 extern int bt_ctf_clock_get_offset(struct bt_ctf_clock *clock,
 186                 int64_t *offset);
 187
 188 /*
 189  * bt_ctf_clock_set_offset: set a clock's offset in ticks.
 190  *
 191  * Set the clock's offset in ticks from Epoch + offset_s.
 192  *
 193  * @param clock Clock instance.
 194  * @param offset Clock's offset in ticks from Epoch + offset_s, defaults to 0.
 195  *
 196  * Returns 0 on success, a negative value on error.
 197  */
 198 extern int bt_ctf_clock_set_offset(struct bt_ctf_clock *clock,
 199                 int64_t offset);
 200
 201 /*
 202  * bt_ctf_clock_get_is_absolute: get a clock's absolute attribute.
 203  *
 204  * Get the clock's absolute attribute. A clock is absolute if the clock is a
 205  * global reference across the trace's other clocks.
 206  *
 207  * @param clock Clock instance.
 208  *
 209  * Returns the clock's absolute attribute, a negative value on error.
 210  */
 211 extern int bt_ctf_clock_get_is_absolute(struct bt_ctf_clock *clock);
 212
 213 /*
 214  * bt_ctf_clock_set_is_absolute: set a clock's absolute attribute.
 215  *
 216  * Set the clock's absolute attribute. A clock is absolute if the clock is a
 217  * global reference across the trace's other clocks.
 218  *
 219  * @param clock Clock instance.
 220  * @param is_absolute Clock's absolute attribute, defaults to FALSE.
 221  *
 222  * Returns 0 on success, a negative value on error.
 223  */
 224 extern int bt_ctf_clock_set_is_absolute(struct bt_ctf_clock *clock,
 225                 int is_absolute);
 226
 227 /*
 228  * bt_ctf_clock_get_uuid: get a clock's UUID.
 229  *
 230  * Get the clock's UUID.
 231  *
 232  * @param clock Clock instance.
 233  *
 234  * Returns a pointer to the clock's UUID (16 byte array) on success,
 235  * NULL on error.
 236  */
 237 extern const unsigned char *bt_ctf_clock_get_uuid(struct bt_ctf_clock *clock);
 238
 239 /*
 240  * bt_ctf_clock_set_uuid: set a clock's UUID.
 241  *
 242  * Set a clock's UUID.
 243  *
 244  * @param clock Clock instance.
 245  * @param uuid A 16-byte array containing a UUID.
 246  *
 247  * Returns 0 on success, a negative value on error.
 248  */
 249 extern int bt_ctf_clock_set_uuid(struct bt_ctf_clock *clock,
 250                 const unsigned char *uuid);
 251
 252 extern int64_t bt_ctf_clock_ns_from_value(struct bt_ctf_clock *clock,
 253                 uint64_t value);
 254
 255 #ifdef __cplusplus
 256 }
 257 #endif
 258
 259 #endif /* BABELTRACE_CTF_IR_CLOCK_H */