include/babeltrace/ctf-ir/trace.h

   1 #ifndef BABELTRACE_CTF_IR_TRACE_H
   2 #define BABELTRACE_CTF_IR_TRACE_H
   3
   4 /*
   5  * BabelTrace - CTF IR: Trace
   6  *
   7  * Copyright 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 <babeltrace/ctf-ir/field-types.h>
  34 #include <babeltrace/values.h>
  35 #include <babeltrace/babeltrace-internal.h>
  36 #include <stdint.h>
  37
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #endif
  41
  42 struct bt_ctf_trace;
  43 struct bt_ctf_stream;
  44 struct bt_ctf_stream_class;
  45 struct bt_ctf_clock;
  46
  47 /*
  48  * bt_ctf_trace_create: create a trace instance.
  49  *
  50  * Allocate a new trace.
  51  *
  52  * A trace's default packet header is a structure initialized with the following
  53  * fields:
  54  *      - uint32_t magic
  55  *      - uint8_t  uuid[16]
  56  *      - uint32_t stream_id
  57  *
  58  * Returns a new trace on success, NULL on error.
  59  */
  60 BT_HIDDEN
  61 struct bt_ctf_trace *bt_ctf_trace_create(void);
  62
  63 /*
  64  * bt_ctf_trace_set_environment_field: sets an environment field to the
  65  *      trace.
  66  *
  67  * Sets an environment field to the trace. The name parameter is
  68  * copied, whereas the value parameter's reference count is incremented
  69  * (if the function succeeds).
  70  *
  71  * If a value exists in the environment for the specified name, it is
  72  * replaced by the new value.
  73  *
  74  * The value parameter _must_ be either an integer value object or a
  75  * string value object. Other object types are not supported.
  76  *
  77  * @param trace Trace instance.
  78  * @param name Name of the environment field (will be copied).
  79  * @param value Value of the environment field.
  80  *
  81  * Returns 0 on success, a negative value on error.
  82  */
  83 BT_HIDDEN
  84 int bt_ctf_trace_set_environment_field(
  85                 struct bt_ctf_trace *trace, const char *name,
  86                 struct bt_value *value);
  87
  88 /*
  89  * bt_ctf_trace_set_environment_field_string: sets a string environment
  90  *      field to the trace.
  91  *
  92  * Sets a string environment field to the trace. This is a helper
  93  * function which corresponds to calling
  94  * bt_ctf_trace_set_environment_field() with a string object.
  95  *
  96  * @param trace Trace instance.
  97  * @param name Name of the environment field (will be copied).
  98  * @param value Value of the environment field (will be copied).
  99  *
 100  * Returns 0 on success, a negative value on error.
 101  */
 102 BT_HIDDEN
 103 int bt_ctf_trace_set_environment_field_string(
 104                 struct bt_ctf_trace *trace, const char *name,
 105                 const char *value);
 106
 107 /*
 108  * bt_ctf_trace_set_environment_field_integer: sets an integer environment
 109  *      field to the trace.
 110  *
 111  * Sets an integer environment field to the trace. This is a helper
 112  * function which corresponds to calling
 113  * bt_ctf_trace_set_environment_field() with an integer object.
 114  *
 115  * @param trace Trace instance.
 116  * @param name Name of the environment field (will be copied).
 117  * @param value Value of the environment field.
 118  *
 119  * Returns 0 on success, a negative value on error.
 120  */
 121 BT_HIDDEN
 122 int bt_ctf_trace_set_environment_field_integer(
 123                 struct bt_ctf_trace *trace, const char *name,
 124                 int64_t value);
 125
 126 /*
 127  * bt_ctf_trace_get_environment_field_count: get environment field count.
 128  *
 129  * Get the trace's environment field count.
 130  *
 131  * @param trace Trace instance.
 132  *
 133  * Returns the environment field count, a negative value on error.
 134  */
 135 BT_HIDDEN
 136 int bt_ctf_trace_get_environment_field_count(
 137                 struct bt_ctf_trace *trace);
 138
 139 /*
 140  * bt_ctf_trace_get_environment_field_name: get environment field name.
 141  *
 142  * Get an environment field's name. The string's ownership is not
 143  * transferred to the caller. The string data is valid as long as
 144  * this trace's environment is not modified.
 145  *
 146  * @param trace Trace instance.
 147  * @param index Index of the environment field.
 148  *
 149  * Returns the environment field's name, NULL on error.
 150  */
 151 BT_HIDDEN
 152 const char *
 153 bt_ctf_trace_get_environment_field_name(struct bt_ctf_trace *trace,
 154                 int index);
 155
 156 /*
 157  * bt_ctf_trace_get_environment_field_value: get environment
 158  *      field value (an object).
 159  *
 160  * Get an environment field's value (an object). The returned object's
 161  * reference count is incremented. When done with the object, the caller
 162  * must call bt_value_put() on it.
 163  *
 164  * @param trace Trace instance.
 165  * @param index Index of the environment field.
 166  *
 167  * Returns the environment field's object value, NULL on error.
 168  */
 169 BT_HIDDEN
 170 struct bt_value *
 171 bt_ctf_trace_get_environment_field_value(struct bt_ctf_trace *trace,
 172                 int index);
 173
 174 /*
 175  * bt_ctf_trace_get_environment_field_value_by_name: get environment
 176  *      field value (an object) by name.
 177  *
 178  * Get an environment field's value (an object) by its field name. The
 179  * returned object's reference count is incremented. When done with the
 180  * object, the caller must call bt_value_put() on it.
 181  *
 182  * @param trace Trace instance.
 183  * @param name Environment field's name
 184  *
 185  * Returns the environment field's object value, NULL on error.
 186  */
 187 BT_HIDDEN
 188 struct bt_value *
 189 bt_ctf_trace_get_environment_field_value_by_name(struct bt_ctf_trace *trace,
 190                 const char *name);
 191
 192 /*
 193  * bt_ctf_trace_add_clock: add a clock to the trace.
 194  *
 195  * Add a clock to the trace. Clocks assigned to stream classes must be
 196  * added to the trace beforehand.
 197  *
 198  * @param trace Trace instance.
 199  * @param clock Clock to add to the trace.
 200  *
 201  * Returns 0 on success, a negative value on error.
 202  */
 203 BT_HIDDEN
 204 int bt_ctf_trace_add_clock(struct bt_ctf_trace *trace,
 205                 struct bt_ctf_clock *clock);
 206
 207 /*
 208  * bt_ctf_trace_get_clock_count: get the number of clocks
 209  *      associated with the trace.
 210  *
 211  * @param trace Trace instance.
 212  *
 213  * Returns the clock count on success, a negative value on error.
 214  */
 215 BT_HIDDEN
 216 int bt_ctf_trace_get_clock_count(struct bt_ctf_trace *trace);
 217
 218 /*
 219  * bt_ctf_trace_get_clock: get a trace's clock at index.
 220  *
 221  * @param trace Trace instance.
 222  * @param index Index of the clock in the given trace.
 223  *
 224  * Return a clock instance on success, NULL on error.
 225  */
 226 BT_HIDDEN
 227 struct bt_ctf_clock *bt_ctf_trace_get_clock(
 228                 struct bt_ctf_trace *trace, int index);
 229
 230 /*
 231  * bt_ctf_trace_add_stream_class: add a stream_class to the trace.
 232  *
 233  * Add a stream class to the trace.
 234  *
 235  * @param trace Trace instance.
 236  * @param stream_class Stream class to add to the trace.
 237  *
 238  * Returns 0 on success, a negative value on error.
 239  */
 240 BT_HIDDEN
 241 int bt_ctf_trace_add_stream_class(struct bt_ctf_trace *trace,
 242                 struct bt_ctf_stream_class *stream_class);
 243
 244 /*
 245  * bt_ctf_trace_get_stream_class_count: get the number of stream classes
 246  *      associated with the trace.
 247  *
 248  * @param trace Trace instance.
 249  *
 250  * Returns the stream class count on success, a negative value on error.
 251  */
 252 BT_HIDDEN
 253 int bt_ctf_trace_get_stream_class_count(struct bt_ctf_trace *trace);
 254
 255 /*
 256  * bt_ctf_trace_get_stream_class: get a trace's stream class at index.
 257  *
 258  * @param trace Trace instance.
 259  * @param index Index of the stream class in the given trace.
 260  *
 261  * Return a stream class on success, NULL on error.
 262  */
 263 BT_HIDDEN
 264 struct bt_ctf_stream_class *bt_ctf_trace_get_stream_class(
 265                 struct bt_ctf_trace *trace, int index);
 266
 267 /*
 268  * bt_ctf_trace_get_stream_class_by_id: get a trace's stream class by ID.
 269  *
 270  * @param trace Trace instance.
 271  * @param index ID of the stream class in the given trace.
 272  *
 273  * Return a stream class on success, NULL on error.
 274  */
 275 BT_HIDDEN
 276 struct bt_ctf_stream_class *bt_ctf_trace_get_stream_class_by_id(
 277                 struct bt_ctf_trace *trace, uint32_t id);
 278
 279 /*
 280  * bt_ctf_trace_get_clock_by_name: get a trace's clock by name
 281  *
 282  * @param trace Trace instance.
 283  * @param name Name of the clock in the given trace.
 284  *
 285  * Return a clock instance on success, NULL on error.
 286  */
 287 BT_HIDDEN
 288 struct bt_ctf_clock *bt_ctf_trace_get_clock_by_name(
 289                 struct bt_ctf_trace *trace, const char *name);
 290
 291 /*
 292  * bt_ctf_trace_get_metadata_string: get metadata string.
 293  *
 294  * Get the trace's TSDL metadata. The caller assumes the ownership of the
 295  * returned string.
 296  *
 297  * @param trace Trace instance.
 298  *
 299  * Returns the metadata string on success, NULL on error.
 300  */
 301 BT_HIDDEN
 302 char *bt_ctf_trace_get_metadata_string(struct bt_ctf_trace *trace);
 303
 304 /*
 305  * bt_ctf_trace_get_byte_order: get a trace's byte order.
 306  *
 307  * Get the trace's byte order.
 308  *
 309  * @param trace Trace instance.
 310  *
 311  * Returns the trace's endianness, BT_CTF_BYTE_ORDER_UNKNOWN on error.
 312  */
 313 BT_HIDDEN
 314 enum bt_ctf_byte_order bt_ctf_trace_get_byte_order(
 315                 struct bt_ctf_trace *trace);
 316
 317 /*
 318  * bt_ctf_trace_set_byte_order: set a trace's byte order.
 319  *
 320  * Set the trace's byte order. Defaults to the current host's endianness.
 321  *
 322  * @param trace Trace instance.
 323  * @param byte_order Trace's byte order.
 324  *
 325  * Returns 0 on success, a negative value on error.
 326  *
 327  * Note: byte_order must not be BT_CTF_BYTE_ORDER_NATIVE since, according
 328  * to the CTF specification, is defined as "the byte order described in the
 329  * trace description".
 330  */
 331 BT_HIDDEN
 332 int bt_ctf_trace_set_byte_order(struct bt_ctf_trace *trace,
 333                 enum bt_ctf_byte_order byte_order);
 334
 335 /*
 336  * bt_ctf_trace_get_packet_header_type: get a trace's packet header type.
 337  *
 338  * Get the trace's packet header type.
 339  *
 340  * @param trace Trace instance.
 341  *
 342  * Returns the trace's packet header type (a structure) on success, NULL on
 343  *      error.
 344  */
 345 BT_HIDDEN
 346 struct bt_ctf_field_type *bt_ctf_trace_get_packet_header_type(
 347                 struct bt_ctf_trace *trace);
 348
 349 /*
 350  * bt_ctf_trace_set_packet_header_type: set a trace's packet header type.
 351  *
 352  * Set the trace's packet header type.
 353  *
 354  * @param trace Trace instance.
 355  * @param packet_header_type Packet header field type (must be a structure).
 356  *
 357  * Returns 0 on success, a negative value on error.
 358  */
 359 BT_HIDDEN
 360 int bt_ctf_trace_set_packet_header_type(struct bt_ctf_trace *trace,
 361                 struct bt_ctf_field_type *packet_header_type);
 362
 363 #ifdef __cplusplus
 364 }
 365 #endif
 366
 367 #endif /* BABELTRACE_CTF_IR_TRACE_H */