include/babeltrace/ctf/events.h

   1 #ifndef _BABELTRACE_CTF_EVENTS_H
   2 #define _BABELTRACE_CTF_EVENTS_H
   3
   4 /*
   5  * BabelTrace
   6  *
   7  * CTF events API
   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
  26 #include <stdint.h>
  27 #include <babeltrace/context.h>
  28 #include <babeltrace/clock-types.h>
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 struct definition;
  35 struct declaration;
  36 struct bt_ctf_event;
  37 struct bt_ctf_event_decl;
  38 struct bt_ctf_field_decl;
  39
  40 /*
  41  * the top-level scopes in CTF
  42  */
  43 enum bt_ctf_scope {
  44         BT_TRACE_PACKET_HEADER          = 0,
  45         BT_STREAM_PACKET_CONTEXT        = 1,
  46         BT_STREAM_EVENT_HEADER          = 2,
  47         BT_STREAM_EVENT_CONTEXT         = 3,
  48         BT_EVENT_CONTEXT                = 4,
  49         BT_EVENT_FIELDS                 = 5,
  50 };
  51
  52 /*
  53  * the supported CTF types
  54  */
  55 enum ctf_type_id {
  56         CTF_TYPE_UNKNOWN = 0,
  57         CTF_TYPE_INTEGER,
  58         CTF_TYPE_FLOAT,
  59         CTF_TYPE_ENUM,
  60         CTF_TYPE_STRING,
  61         CTF_TYPE_STRUCT,
  62         CTF_TYPE_UNTAGGED_VARIANT,
  63         CTF_TYPE_VARIANT,
  64         CTF_TYPE_ARRAY,
  65         CTF_TYPE_SEQUENCE,
  66         NR_CTF_TYPES,
  67 };
  68
  69 /*
  70  * the supported CTF string encodings
  71  */
  72 enum ctf_string_encoding {
  73         CTF_STRING_NONE = 0,
  74         CTF_STRING_UTF8,
  75         CTF_STRING_ASCII,
  76         CTF_STRING_UNKNOWN,
  77 };
  78
  79 /*
  80  * bt_ctf_get_top_level_scope: return a definition of the top-level scope
  81  *
  82  * Top-level scopes are defined in the bt_ctf_scope enum.
  83  * In order to get a field or a field list, the user needs to pass a
  84  * scope as argument, this scope can be a top-level scope or a scope
  85  * relative to an arbitrary field. This function provides the mapping
  86  * between the enum and the actual definition of top-level scopes.
  87  * On error return NULL.
  88  */
  89 const struct definition *bt_ctf_get_top_level_scope(const struct bt_ctf_event *event,
  90                 enum bt_ctf_scope scope);
  91
  92 /*
  93  * bt_ctf_event_get_name: returns the name of the event or NULL on error
  94  */
  95 const char *bt_ctf_event_name(const struct bt_ctf_event *event);
  96
  97 /*
  98  * bt_ctf_get_cycles: returns the timestamp of the event as written
  99  * in the packet (in cycles) or -1ULL on error.
 100  */
 101 uint64_t bt_ctf_get_cycles(const struct bt_ctf_event *event);
 102
 103 /*
 104  * bt_ctf_get_timestamp: returns the timestamp of the event offsetted
 105  * with the system clock source (in ns) or -1ULL on error
 106  */
 107 uint64_t bt_ctf_get_timestamp(const struct bt_ctf_event *event);
 108
 109 /*
 110  * bt_ctf_get_field_list: obtain the list of fields for compound type
 111  *
 112  * This function can be used to obtain the list of fields
 113  * contained within a compound type: array, sequence,
 114  * structure, or variant.
 115
 116  * This function sets the "list" pointer to an array of definition
 117  * pointers and set count to the number of elements in the array.
 118  * Return 0 on success and a negative value on error.
 119  *
 120  * The content pointed to by "list" should *not* be freed. It stays
 121  * valid as long as the event is unchanged (as long as the iterator
 122  * from which the event is extracted is unchanged).
 123  */
 124 int bt_ctf_get_field_list(const struct bt_ctf_event *event,
 125                 const struct definition *scope,
 126                 struct definition const * const **list,
 127                 unsigned int *count);
 128
 129 /*
 130  * bt_ctf_get_field: returns the definition of a specific field
 131  */
 132 const struct definition *bt_ctf_get_field(const struct bt_ctf_event *event,
 133                 const struct definition *scope,
 134                 const char *field);
 135
 136 /*
 137  * bt_ctf_get_index: if the field is an array or a sequence, return the element
 138  * at position index, otherwise return NULL;
 139  */
 140 const struct definition *bt_ctf_get_index(const struct bt_ctf_event *event,
 141                 const struct definition *field,
 142                 unsigned int index);
 143
 144 /*
 145  * bt_ctf_field_name: returns the name of a field or NULL on error
 146  */
 147 const char *bt_ctf_field_name(const struct definition *def);
 148
 149 /*
 150  * bt_ctf_get_field_decl: return the declaration of a field or NULL
 151  * on error
 152  */
 153 const struct declaration *bt_ctf_get_field_decl(const struct definition *def);
 154
 155 /*
 156  * bt_ctf_field_type: returns the type of a field or -1 if unknown
 157  */
 158 enum ctf_type_id bt_ctf_field_type(const struct declaration *decl);
 159
 160 /*
 161  * bt_ctf_get_int_signedness: return the signedness of an integer
 162  *
 163  * return 0 if unsigned
 164  * return 1 if signed
 165  * return -1 on error
 166  */
 167 int bt_ctf_get_int_signedness(const struct declaration *decl);
 168
 169 /*
 170  * bt_ctf_get_int_base: return the base of an int or a negative value on error
 171  */
 172 int bt_ctf_get_int_base(const struct declaration *decl);
 173
 174 /*
 175  * bt_ctf_get_int_byte_order: return the byte order of an int or a negative
 176  * value on error
 177  */
 178 int bt_ctf_get_int_byte_order(const struct declaration *decl);
 179
 180 /*
 181  * bt_ctf_get_int_len: return the size, in bits, of an int or a negative
 182  * value on error
 183  */
 184 ssize_t bt_ctf_get_int_len(const struct declaration *decl);
 185
 186 /*
 187  * bt_ctf_get_encoding: return the encoding of an int or a string.
 188  * return a negative value on error
 189  */
 190 enum ctf_string_encoding bt_ctf_get_encoding(const struct declaration *decl);
 191
 192 /*
 193  * bt_ctf_get_array_len: return the len of an array or a negative
 194  * value on error
 195  */
 196 int bt_ctf_get_array_len(const struct declaration *decl);
 197
 198 /*
 199  * Field access functions
 200  *
 201  * These functions return the value associated with the field passed in
 202  * parameter.
 203  *
 204  * If the field does not exist or is not of the type requested, the value
 205  * returned is undefined. To check if an error occured, use the
 206  * bt_ctf_field_get_error() function after accessing a field.
 207  *
 208  * bt_ctf_get_enum_int gets the integer field of an enumeration.
 209  * bt_ctf_get_enum_str gets the string matching the current enumeration
 210  * value, or NULL if the current value does not match any string.
 211  */
 212 uint64_t bt_ctf_get_uint64(const struct definition *field);
 213 int64_t bt_ctf_get_int64(const struct definition *field);
 214 const struct definition *bt_ctf_get_enum_int(const struct definition *field);
 215 const char *bt_ctf_get_enum_str(const struct definition *field);
 216 char *bt_ctf_get_char_array(const struct definition *field);
 217 char *bt_ctf_get_string(const struct definition *field);
 218
 219 /*
 220  * bt_ctf_field_get_error: returns the last error code encountered while
 221  * accessing a field and reset the error flag.
 222  * Return 0 if no error, a negative value otherwise.
 223  */
 224 int bt_ctf_field_get_error(void);
 225
 226 /*
 227  * bt_ctf_get_event_decl_list: set list pointer to an array of bt_ctf_event_decl
 228  * pointers and set count to the number of elements in the array.
 229  *
 230  * Return 0 on success and a negative value on error.
 231  */
 232 int bt_ctf_get_event_decl_list(int handle_id, struct bt_context *ctx,
 233                 struct bt_ctf_event_decl * const **list,
 234                 unsigned int *count);
 235
 236 /*
 237  * bt_ctf_get_decl_event_name: return the name of the event or NULL on error
 238  */
 239 const char *bt_ctf_get_decl_event_name(const struct bt_ctf_event_decl *event);
 240
 241 /*
 242  * bt_ctf_get_decl_fields: set list pointer to an array of bt_ctf_field_decl
 243  * pointers and set count to the number of elements in the array.
 244  *
 245  * Returns 0 on success and a negative value on error
 246  */
 247 int bt_ctf_get_decl_fields(struct bt_ctf_event_decl *event_decl,
 248                 enum bt_ctf_scope scope,
 249                 struct bt_ctf_field_decl const * const **list,
 250                 unsigned int *count);
 251
 252 /*
 253  * bt_ctf_get_decl_field_name: return the name of a field decl or NULL on error
 254  */
 255 const char *bt_ctf_get_decl_field_name(const struct bt_ctf_field_decl *field);
 256
 257 #ifdef __cplusplus
 258 }
 259 #endif
 260
 261 #endif /* _BABELTRACE_CTF_EVENTS_H */