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