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