include/babeltrace/ctf/events-internal.h

   1 #ifndef _BABELTRACE_CTF_EVENTS_INTERNAL_H
   2 #define _BABELTRACE_CTF_EVENTS_INTERNAL_H
   3
   4 /*
   5  * BabelTrace
   6  *
   7  * CTF events API (internal)
   8  *
   9  * Copyright 2011-2012 EfficiOS Inc. and Linux Foundation
  10  *
  11  * Author: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
  12  *         Julien Desfossez <julien.desfossez@efficios.com>
  13  *
  14  * Permission is hereby granted, free of charge, to any person obtaining
  15  * a copy of this software and associated documentation files (the
  16  * "Software"), to deal in the Software without restriction, including
  17  * without limitation the rights to use, copy, modify, merge, publish,
  18  * distribute, sublicense, and/or sell copies of the Software, and to
  19  * permit persons to whom the Software is furnished to do so, subject to
  20  * the following conditions:
  21  *
  22  * The above copyright notice and this permission notice shall be
  23  * included in all copies or substantial portions of the Software.
  24  *
  25  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  26  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  27  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  28  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  29  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  30  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  31  * SOFTWARE.
  32  */
  33
  34 #include <babeltrace/iterator-internal.h>
  35 #include <babeltrace/ctf/callbacks.h>
  36 #include <babeltrace/ctf/callbacks-internal.h>
  37 #include <babeltrace/ctf-ir/metadata.h>
  38 #include <babeltrace/ctf-ir/field-types.h>
  39 #include <glib.h>
  40
  41 struct ctf_stream_definition;
  42
  43 /*
  44  * These structures are public mappings to internal ctf_event structures.
  45  */
  46 struct bt_ctf_event {
  47         struct ctf_event_definition *parent;
  48 };
  49
  50 struct bt_ctf_event_decl {
  51         struct ctf_event_declaration parent;
  52         GPtrArray *context_decl;
  53         GPtrArray *fields_decl;
  54         GPtrArray *packet_header_decl;
  55         GPtrArray *event_context_decl;
  56         GPtrArray *event_header_decl;
  57         GPtrArray *packet_context_decl;
  58 };
  59
  60 struct bt_ctf_iter {
  61         struct bt_iter parent;
  62         struct bt_ctf_event current_ctf_event;  /* last read event */
  63         GArray *callbacks;                              /* Array of struct bt_stream_callbacks */
  64         struct bt_callback_chain main_callbacks;        /* For all events */
  65         /*
  66          * Flag indicating if dependency graph needs to be recalculated.
  67          * Set by bt_iter_add_callback(), and checked (and
  68          * cleared) by upon entry into bt_iter_read_event().
  69          * bt_iter_read_event() is responsible for calling dep
  70          * graph calculation if it sees this flag set.
  71          */
  72         int recalculate_dep_graph;
  73         /*
  74          * Array of pointers to struct bt_dependencies, for garbage
  75          * collection. We're not using a linked list here because each
  76          * struct bt_dependencies can belong to more than one
  77          * bt_iter.
  78          */
  79         GPtrArray *dep_gc;
  80         uint64_t events_lost;
  81 };
  82
  83 struct bt_definition;
  84 struct bt_declaration;
  85 struct bt_ctf_event;
  86 struct bt_ctf_event_decl;
  87 struct bt_ctf_field_decl;
  88
  89 /*
  90  * the top-level scopes in CTF
  91  */
  92 enum ctf_scope {
  93         BT_TRACE_PACKET_HEADER          = 0,
  94         BT_STREAM_PACKET_CONTEXT        = 1,
  95         BT_STREAM_EVENT_HEADER          = 2,
  96         BT_STREAM_EVENT_CONTEXT         = 3,
  97         BT_EVENT_CONTEXT                = 4,
  98         BT_EVENT_FIELDS                 = 5,
  99 };
 100
 101 /*
 102  * bt_ctf_get_top_level_scope: return a definition of the top-level scope
 103  *
 104  * Top-level scopes are defined in the ctf_scope enum.
 105  * In order to get a field or a field list, the user needs to pass a
 106  * scope as argument, this scope can be a top-level scope or a scope
 107  * relative to an arbitrary field. This function provides the mapping
 108  * between the enum and the actual definition of top-level scopes.
 109  * On error return NULL.
 110  */
 111 const struct bt_definition *bt_ctf_get_top_level_scope(const struct bt_ctf_event *event,
 112                 enum ctf_scope scope);
 113
 114 /*
 115  * bt_ctf_event_get_name: returns the name of the event or NULL on error
 116  */
 117 const char *bt_ctf_event_name(const struct bt_ctf_event *event);
 118
 119 /*
 120  * bt_ctf_get_cycles: returns the timestamp of the event as written
 121  * in the packet (in cycles) or -1ULL on error.
 122  */
 123 uint64_t bt_ctf_get_cycles(const struct bt_ctf_event *event);
 124
 125 /*
 126  * bt_ctf_get_timestamp: get the timestamp of the event offsetted
 127  * with the system clock source (in ns) in *timestamp.
 128  *
 129  * Return 0 on success, or -1ULL on error.
 130  */
 131 int bt_ctf_get_timestamp(const struct bt_ctf_event *event, int64_t *timestamp);
 132
 133 /*
 134  * bt_ctf_get_field_list: obtain the list of fields for compound type
 135  *
 136  * This function can be used to obtain the list of fields contained
 137  * within a top-level scope of an event or a compound type: array,
 138  * sequence, structure, or variant.
 139
 140  * This function sets the "list" pointer to an array of definition
 141  * pointers and set count to the number of elements in the array.
 142  * Return 0 on success and a negative value on error.
 143  *
 144  * The content pointed to by "list" should *not* be freed. It stays
 145  * valid as long as the event is unchanged (as long as the iterator
 146  * from which the event is extracted is unchanged).
 147  */
 148 int bt_ctf_get_field_list(const struct bt_ctf_event *event,
 149                 const struct bt_definition *scope,
 150                 struct bt_definition const * const **list,
 151                 unsigned int *count);
 152
 153 /*
 154  * bt_ctf_get_field: returns the definition of a specific field
 155  */
 156 const struct bt_definition *bt_ctf_get_field(const struct bt_ctf_event *event,
 157                 const struct bt_definition *scope,
 158                 const char *field);
 159
 160 /*
 161  * bt_ctf_get_index: if the field is an array or a sequence, return the element
 162  * at position index, otherwise return NULL;
 163  */
 164 const struct bt_definition *bt_ctf_get_index(const struct bt_ctf_event *event,
 165                 const struct bt_definition *field,
 166                 unsigned int index);
 167
 168 /*
 169  * bt_ctf_field_name: returns the name of a field or NULL on error
 170  */
 171 const char *bt_ctf_field_name(const struct bt_definition *def);
 172
 173 /*
 174  * bt_ctf_get_decl_from_def: return the declaration of a field from
 175  * its definition or NULL on error
 176  */
 177 const struct bt_declaration *bt_ctf_get_decl_from_def(const struct bt_definition *def);
 178
 179 /*
 180  * bt_ctf_get_decl_from_field_decl: return the declaration of a field from
 181  * a field_decl or NULL on error
 182  */
 183 const struct bt_declaration *bt_ctf_get_decl_from_field_decl(
 184                 const struct bt_ctf_field_decl *field);
 185
 186 /*
 187  * bt_ctf_field_type: returns the type of a field or -1 if unknown
 188  */
 189 enum ctf_type_id bt_ctf_field_type(const struct bt_declaration *decl);
 190
 191 /*
 192  * bt_ctf_get_int_signedness: return the signedness of an integer
 193  *
 194  * return 0 if unsigned
 195  * return 1 if signed
 196  * return -1 on error
 197  */
 198 int bt_ctf_get_int_signedness(const struct bt_declaration *decl);
 199
 200 /*
 201  * bt_ctf_get_int_base: return the base of an int or a negative value on error
 202  */
 203 int bt_ctf_get_int_base(const struct bt_declaration *decl);
 204
 205 /*
 206  * bt_ctf_get_int_byte_order: return the byte order of an int or a negative
 207  * value on error
 208  */
 209 int bt_ctf_get_int_byte_order(const struct bt_declaration *decl);
 210
 211 /*
 212  * bt_ctf_get_int_len: return the size, in bits, of an int or a negative
 213  * value on error
 214  */
 215 ssize_t bt_ctf_get_int_len(const struct bt_declaration *decl);
 216
 217 /*
 218  * bt_ctf_get_encoding: return the encoding of an int, a string, or of
 219  * the integer contained in a char array or a sequence.
 220  * return a negative value on error
 221  */
 222 enum ctf_string_encoding bt_ctf_get_encoding(const struct bt_declaration *decl);
 223
 224 /*
 225  * bt_ctf_get_array_len: return the len of an array or a negative
 226  * value on error
 227  */
 228 int bt_ctf_get_array_len(const struct bt_declaration *decl);
 229
 230 /*
 231  * bt_ctf_get_struct_field_count: return the number of fields in a structure.
 232  * Returns a negative value on error.
 233  */
 234 uint64_t bt_ctf_get_struct_field_count(const struct bt_definition *field);
 235
 236 /*
 237  * Field access functions
 238  *
 239  * These functions return the value associated with the field passed in
 240  * parameter.
 241  *
 242  * If the field does not exist or is not of the type requested, the value
 243  * returned is undefined. To check if an error occured, use the
 244  * bt_ctf_field_get_error() function after accessing a field.
 245  *
 246  * bt_ctf_get_enum_int gets the integer field of an enumeration.
 247  * bt_ctf_get_enum_str gets the string matching the current enumeration
 248  * value, or NULL if the current value does not match any string.
 249  */
 250 uint64_t bt_ctf_get_uint64(const struct bt_definition *field);
 251 int64_t bt_ctf_get_int64(const struct bt_definition *field);
 252 const struct bt_definition *bt_ctf_get_enum_int(const struct bt_definition *field);
 253 const char *bt_ctf_get_enum_str(const struct bt_definition *field);
 254 char *bt_ctf_get_char_array(const struct bt_definition *field);
 255 char *bt_ctf_get_string(const struct bt_definition *field);
 256 double bt_ctf_get_float(const struct bt_definition *field);
 257 const struct bt_definition *bt_ctf_get_variant(const struct bt_definition *field);
 258 const struct bt_definition *bt_ctf_get_struct_field_index(
 259                 const struct bt_definition *field, uint64_t i);
 260
 261 /*
 262  * bt_ctf_field_get_error: returns the last error code encountered while
 263  * accessing a field and reset the error flag.
 264  * Return 0 if no error, a negative value otherwise.
 265  */
 266 int bt_ctf_field_get_error(void);
 267
 268 /*
 269  * bt_ctf_get_event_decl_list: get a list of all the event declarations in
 270  * a trace.
 271  *
 272  * The list array is pointed to the array of event declarations.
 273  * The number of events in the array is written in count.
 274  *
 275  * Return 0 on success and a negative value on error.
 276  *
 277  * The content pointed to by "list" should *not* be freed. It stays
 278  * valid as long as the trace is opened.
 279  */
 280 int bt_ctf_get_event_decl_list(int handle_id, struct bt_context *ctx,
 281                 struct bt_ctf_event_decl * const **list,
 282                 unsigned int *count);
 283
 284 /*
 285  * bt_ctf_get_decl_event_name: return the name of the event or NULL on error
 286  */
 287 const char *bt_ctf_get_decl_event_name(const struct bt_ctf_event_decl *event);
 288
 289 /*
 290  * bt_ctf_get_decl_event_id: return the event-ID of the event or -1ULL on error
 291  */
 292 uint64_t bt_ctf_get_decl_event_id(const struct bt_ctf_event_decl *event);
 293
 294 /*
 295  * bt_ctf_get_decl_fields: get all field declarations in a scope of an event
 296  *
 297  * The list array is pointed to the array of field declaration.
 298  * The number of field declaration in the array is written in count.
 299  *
 300  * Returns 0 on success and a negative value on error
 301  *
 302  * The content pointed to by "list" should *not* be freed. It stays
 303  * valid as long as the trace is opened.
 304  */
 305 int bt_ctf_get_decl_fields(struct bt_ctf_event_decl *event_decl,
 306                 enum ctf_scope scope,
 307                 struct bt_ctf_field_decl const * const **list,
 308                 unsigned int *count);
 309
 310 /*
 311  * bt_ctf_get_decl_field_name: return the name of a field decl or NULL on error
 312  */
 313 const char *bt_ctf_get_decl_field_name(const struct bt_ctf_field_decl *field);
 314 int ctf_find_tc_stream_packet_intersection_union(struct bt_context *ctx,
 315                 int64_t *ts_begin, int64_t *ts_end);
 316
 317 void ctf_update_current_packet_index(struct ctf_stream_definition *stream,
 318                 struct packet_index *prev_index,
 319                 struct packet_index *cur_index);
 320
 321 int ctf_tc_set_stream_intersection_mode(struct bt_context *ctx);
 322
 323 #endif /*_BABELTRACE_CTF_EVENTS_INTERNAL_H */