bindings/python/babeltrace.i.in

   1 /*
   2  * babeltrace.i.in
   3  *
   4  * Babeltrace Python Module interface file
   5  *
   6  * Copyright 2012 EfficiOS Inc.
   7  *
   8  * Author: Danny Serres <danny.serres@efficios.com>
   9  *
  10  * Permission is hereby granted, free of charge, to any person obtaining a copy
  11  * of this software and associated documentation files (the "Software"), to deal
  12  * in the Software without restriction, including without limitation the rights
  13  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  14  * copies of the Software, and to permit persons to whom the Software is
  15  * furnished to do so, subject to the following conditions:
  16  *
  17  * The above copyright notice and this permission notice shall be included in
  18  * all copies or substantial portions of the Software.
  19  */
  20
  21
  22 %define DOCSTRING
  23 "BABELTRACE_VERSION_STR
  24
  25 Babeltrace  is a trace viewer and converter reading and writing the
  26 Common Trace Format (CTF). Its main use is to pretty-print CTF
  27 traces into a human-readable text output.
  28
  29 To use this module, the first step is to create a Context and add a
  30 trace to it."
  31 %enddef
  32
  33 %module(docstring=DOCSTRING) babeltrace
  34
  35 %include "typemaps.i"
  36 %{
  37 #define SWIG_FILE_WITH_INIT
  38 #include <babeltrace/babeltrace.h>
  39 #include <babeltrace/babeltrace-internal.h>
  40 #include <babeltrace/trace-handle.h>
  41 #include <babeltrace/trace-handle-internal.h>
  42 #include <babeltrace/context.h>
  43 #include <babeltrace/context-internal.h>
  44 #include <babeltrace/iterator.h>
  45 #include <babeltrace/iterator-internal.h>
  46 #include <babeltrace/format.h>
  47 #include <babeltrace/list.h>
  48 #include <babeltrace/types.h>
  49 #include <babeltrace/ctf/iterator.h>
  50 #include "python-complements.h"
  51 %}
  52
  53 typedef unsigned long long uint64_t;
  54 typedef long long int64_t;
  55 typedef int bt_intern_str;
  56
  57 /* =================================================================
  58                 CONTEXT.H, CONTEXT-INTERNAL.H
  59                 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  60 */
  61
  62 %rename("_bt_context_create") bt_context_create(void);
  63 %rename("_bt_context_add_trace") bt_context_add_trace(
  64                 struct bt_context *ctx, const char *path, const char *format,
  65                 void (*packet_seek)(struct bt_stream_pos *pos, size_t index, int whence),
  66                 struct bt_mmap_stream_list *stream_list, FILE *metadata);
  67 %rename("_bt_context_remove_trace") bt_context_remove_trace(
  68                 struct bt_context *ctx, int trace_id);
  69 %rename("_bt_context_get") bt_context_get(struct bt_context *ctx);
  70 %rename("_bt_context_put") bt_context_put(struct bt_context *ctx);
  71 %rename("_bt_ctf_event_get_context") bt_ctf_event_get_context(
  72                 const struct bt_ctf_event *event);
  73
  74 struct bt_context *bt_context_create(void);
  75 int bt_context_add_trace(struct bt_context *ctx, const char *path, const char *format,
  76                 void (*packet_seek)(struct bt_stream_pos *pos, size_t index, int whence),
  77                 struct bt_mmap_stream_list *stream_list, FILE *metadata);
  78 void bt_context_remove_trace(struct bt_context *ctx, int trace_id);
  79 void bt_context_get(struct bt_context *ctx);
  80 void bt_context_put(struct bt_context *ctx);
  81 struct bt_context *bt_ctf_event_get_context(const struct bt_ctf_event *event);
  82
  83 // class Context to prevent direct access to struct bt_context
  84 %pythoncode%{
  85 class Context:
  86         """
  87         The context represents the object in which a trace_collection is
  88         open. As long as this structure is allocated, the trace_collection
  89         is open and the traces it contains can be read and seeked by the
  90         iterators and callbacks.
  91         """
  92
  93         def __init__(self):
  94                 self._c = _bt_context_create()
  95
  96         def __del__(self):
  97                 _bt_context_put(self._c)
  98
  99         def add_trace(self, path, format_str,
 100                         packet_seek=None, stream_list=None, metadata=None):
 101                 """
 102                 Add a trace by path to the context.
 103
 104                 Open a trace.
 105
 106                 path is the path to the trace, it is not recursive.
 107                 If "path" is None, stream_list is used instead as a list
 108                 of mmap streams to open for the trace.
 109
 110                 format is a string containing the format name in which the trace was
 111                 produced.
 112
 113                 packet_seek is not implemented for Python.  Should be left None to
 114                 use the default packet_seek handler provided by the trace format.
 115
 116                 stream_list is a linked list of streams, it is used to open a trace
 117                 where the trace data is located in memory mapped areas instead of
 118                 trace files, this argument should be None when path is not None.
 119
 120                 The metadata parameter acts as a metadata override when not None,
 121                 otherwise the format handles the metadata opening.
 122
 123                 Return: the corresponding TraceHandle on success or None on error.
 124                 """
 125                 if metadata is not None:
 126                         metadata = metadata._file
 127
 128                 ret = _bt_context_add_trace(self._c, path, format_str, packet_seek,
 129                         stream_list, metadata)
 130                 if ret < 0:
 131                         return None
 132
 133                 th = TraceHandle.__new__(TraceHandle)
 134                 th._id = ret
 135                 return th
 136
 137         def add_traces_recursive(self, path, format_str):
 138                 """
 139                 Open a trace recursively.
 140
 141                 Find each trace present in the subdirectory starting from the given
 142                 path, and add them to the context.
 143
 144                 Return a dict of TraceHandle instances (the full path is the key).
 145                 Return None on error.
 146                 """
 147
 148                 import os
 149
 150                 trace_handles = {}
 151
 152                 noTrace = True
 153                 error = False
 154
 155                 for fullpath, dirs, files in os.walk(path):
 156                         if "metadata" in files:
 157                                 trace_handle = self.add_trace(fullpath, format_str)
 158                                 if trace_handle is None:
 159                                         error = True
 160                                         continue
 161
 162                                 trace_handles[fullpath] = trace_handle
 163                                 noTrace = False
 164
 165                 if noTrace and error:
 166                         return None
 167                 return trace_handles
 168
 169         def remove_trace(self, trace_handle):
 170                 """
 171                 Remove a trace from the context.
 172                 Effectively closing the trace.
 173                 """
 174                 try:
 175                         _bt_context_remove_trace(self._c, trace_handle._id)
 176                 except AttributeError:
 177                         raise TypeError("in remove_trace, "
 178                                 "argument 2 must be a TraceHandle instance")
 179 %}
 180
 181
 182
 183 /* =================================================================
 184                 FORMAT.H, REGISTRY
 185                 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
 186 */
 187
 188 %rename("lookup_format") bt_lookup_format(bt_intern_str qname);
 189 %rename("_bt_print_format_list") bt_fprintf_format_list(FILE *fp);
 190 %rename("register_format") bt_register_format(struct format *format);
 191 %rename("unregister_format") bt_unregister_format(struct bt_format *format);
 192
 193 extern struct format *bt_lookup_format(bt_intern_str qname);
 194 extern void bt_fprintf_format_list(FILE *fp);
 195 extern int bt_register_format(struct bt_format *format);
 196 extern void bt_unregister_format(struct bt_format *format);
 197
 198 %pythoncode %{
 199
 200 def print_format_list(babeltrace_file):
 201         """
 202         Print a list of available formats to file.
 203
 204         babeltrace_file must be a File instance opened in write mode.
 205         """
 206         try:
 207                 if babeltrace_file._file is not None:
 208                         _bt_print_format_list(babeltrace_file._file)
 209         except AttributeError:
 210                 raise TypeError("in print_format_list, "
 211                         "argument 1 must be a File instance")
 212
 213 %}
 214
 215
 216 /* =================================================================
 217                 ITERATOR.H, ITERATOR-INTERNAL.H
 218                 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
 219 */
 220
 221 %rename("_bt_iter_create") bt_iter_create(struct bt_context *ctx,
 222                 const struct bt_iter_pos *begin_pos, const struct bt_iter_pos *end_pos);
 223 %rename("_bt_iter_destroy") bt_iter_destroy(struct bt_iter *iter);
 224 %rename("_bt_iter_next") bt_iter_next(struct bt_iter *iter);
 225 %rename("_bt_iter_get_pos") bt_iter_get_pos(struct bt_iter *iter);
 226 %rename("_bt_iter_free_pos") bt_iter_free_pos(struct bt_iter_pos *pos);
 227 %rename("_bt_iter_set_pos") bt_iter_set_pos(struct bt_iter *iter,
 228                 const struct bt_iter_pos *pos);
 229 %rename("_bt_iter_create_time_pos") bt_iter_create_time_pos(struct bt_iter *iter,
 230                 uint64_t timestamp);
 231
 232 struct bt_iter *bt_iter_create(struct bt_context *ctx,
 233                 const struct bt_iter_pos *begin_pos, const struct bt_iter_pos *end_pos);
 234 void bt_iter_destroy(struct bt_iter *iter);
 235 int bt_iter_next(struct bt_iter *iter);
 236 struct bt_iter_pos *bt_iter_get_pos(struct bt_iter *iter);
 237 void bt_iter_free_pos(struct bt_iter_pos *pos);
 238 int bt_iter_set_pos(struct bt_iter *iter, const struct bt_iter_pos *pos);
 239 struct bt_iter_pos *bt_iter_create_time_pos(struct bt_iter *iter, uint64_t timestamp);
 240
 241 %rename("_bt_iter_pos") bt_iter_pos;
 242 %rename("SEEK_TIME") BT_SEEK_TIME;
 243 %rename("SEEK_RESTORE") BT_SEEK_RESTORE;
 244 %rename("SEEK_CUR") BT_SEEK_CUR;
 245 %rename("SEEK_BEGIN") BT_SEEK_BEGIN;
 246 %rename("SEEK_LAST") BT_SEEK_LAST;
 247
 248 // This struct is taken from iterator.h
 249 // All changes to the struct must also be made here
 250 struct bt_iter_pos {
 251         enum {
 252                 BT_SEEK_TIME,           /* uses u.seek_time */
 253                 BT_SEEK_RESTORE,        /* uses u.restore */
 254                 BT_SEEK_CUR,
 255                 BT_SEEK_BEGIN,
 256                 BT_SEEK_LAST
 257         } type;
 258         union {
 259                 uint64_t seek_time;
 260                 struct bt_saved_pos *restore;
 261         } u;
 262 };
 263
 264
 265 %pythoncode%{
 266
 267 class IterPos:
 268         """This class represents the position where to set an iterator."""
 269
 270         __can_access = False
 271
 272         def __init__(self, seek_type, seek_time = None):
 273                 """
 274                 seek_type represents the type of seek to use.
 275                 seek_time is the timestamp to seek to when using SEEK_TIME, it
 276                 is expressed in nanoseconds
 277                 Only use SEEK_RESTORE on IterPos obtained from the get_pos function
 278                 in Iter class.
 279                 """
 280
 281                 self._pos = _bt_iter_pos()
 282                 self._pos.type = seek_type
 283                 if seek_time and seek_type == SEEK_TIME:
 284                         self._pos.u.seek_time = seek_time
 285                 self.__can_access = True
 286
 287         def __del__(self):
 288                 if not self.__can_access:
 289                         _bt_iter_free_pos(self._pos)
 290
 291         def _get_type(self):
 292                 if not __can_access:
 293                         raise AttributeError("seek_type is not available")
 294                 return self._pos.type
 295
 296         def _set_type(self, seek_type):
 297                 if not __can_access:
 298                         raise AttributeError("seek_type is not available")
 299                 self._pos.type = seek_type
 300
 301         def _get_time(self):
 302                 if not __can_access:
 303                         raise AttributeError("seek_time is not available")
 304
 305                 elif self._pos.type is not SEEK_TIME:
 306                         raise TypeError("seek_type is not SEEK_TIME")
 307
 308                 return self._pos.u.seek_time
 309
 310         def _set_time(self, time):
 311                 if not __can_access:
 312                         raise AttributeError("seek_time is not available")
 313
 314                 elif self._pos.type is not SEEK_TIME:
 315                         raise TypeError("seek_type is not SEEK_TIME")
 316
 317                 self._pos.u.seek_time = time
 318
 319         def _get_pos(self):
 320                 return self._pos
 321
 322
 323         seek_type = property(_get_type, _set_type)
 324         seek_time = property(_get_time, _set_time)
 325
 326
 327 class Iterator:
 328
 329         __with_init = False
 330
 331         def __init__(self, context, begin_pos = None, end_pos = None, _no_init = None):
 332                 """
 333                 Allocate a trace collection iterator.
 334
 335                 begin_pos and end_pos are optional parameters to specify the
 336                 position at which the trace collection should be seeked upon
 337                 iterator creation, and the position  at which iteration will
 338                 start returning "EOF".
 339
 340                 By default, if begin_pos is None, a BT_SEEK_CUR is performed at
 341                 creation. By default, if end_pos is None, a BT_SEEK_END (end of
 342                 trace) is the EOF criterion.
 343                 """
 344                 if _no_init is None:
 345                         if begin_pos is None:
 346                                 bp = None
 347                         else:
 348                                 try:
 349                                         bp = begin_pos._pos
 350                                 except AttributeError:
 351                                         raise TypeError("in __init__, "
 352                                                 "argument 3 must be a IterPos instance")
 353
 354                         if end_pos is None:
 355                                 ep = None
 356                         else:
 357                                 try:
 358                                         ep = end_pos._pos
 359                                 except AttributeError:
 360                                         raise TypeError("in __init__, "
 361                                                 "argument 4 must be a IterPos instance")
 362
 363                         try:
 364                                 self._bi = _bt_iter_create(context._c, bp, ep)
 365                         except AttributeError:
 366                                 raise TypeError("in __init__, "
 367                                         "argument 2 must be a Context instance")
 368
 369                         self.__with_init = True
 370
 371                 else:
 372                         self._bi = _no_init
 373
 374         def __del__(self):
 375                 if self.__with_init:
 376                         _bt_iter_destroy(self._bi)
 377
 378         def next(self):
 379                 """
 380                 Move trace collection position to the next event.
 381                 Returns 0 on success, a negative value on error.
 382                 """
 383                 return _bt_iter_next(self._bi)
 384
 385         def get_pos(self):
 386                 """Return a IterPos class of the current iterator position."""
 387                 ret = IterPos(0)
 388                 ret.__can_access = False
 389                 ret._pos = _bt_iter_get_pos(self._bi)
 390                 return ret
 391
 392         def set_pos(self, pos):
 393                 """
 394                 Move the iterator to a given position.
 395
 396                 On error, the stream_heap is reinitialized and returned empty.
 397                 Return 0 for success.
 398                 Return EOF if the position requested is after the last event of the
 399                 trace collection.
 400                 Return -EINVAL when called with invalid parameter.
 401                 Return -ENOMEM if the stream_heap could not be properly initialized.
 402                 """
 403                 try:
 404                         return _bt_iter_set_pos(self._bi, pos._pos)
 405                 except AttributeError:
 406                         raise TypeError("in set_pos, "
 407                                 "argument 2 must be a IterPos instance")
 408
 409         def create_time_pos(self, timestamp):
 410                 """
 411                 Create a position based on time
 412                 This function allocates and returns a new IterPos to be able to
 413                 restore an iterator position based on a timestamp.
 414                 """
 415
 416                 if timestamp < 0:
 417                         raise TypeError("timestamp must be an unsigned int")
 418
 419                 ret = IterPos(0)
 420                 ret.__can_access = False
 421                 ret._pos = _bt_iter_create_time_pos(self._bi, timestamp)
 422                 return ret
 423 %}
 424
 425
 426 /* =================================================================
 427                 CLOCK-TYPE.H
 428                 ¯¯¯¯¯¯¯¯¯¯¯¯
 429         *** Enum copied from clock-type.h
 430                 All changes must also be made here
 431 */
 432 %rename("CLOCK_CYCLES") BT_CLOCK_CYCLES;
 433 %rename("CLOCK_REAL") BT_CLOCK_REAL;
 434
 435 enum bt_clock_type {
 436         BT_CLOCK_CYCLES = 0,
 437         BT_CLOCK_REAL
 438 };
 439
 440 /* =================================================================
 441                 TRACE-HANDLE.H, TRACE-HANDLE-INTERNAL.H
 442                 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
 443 */
 444
 445 %rename("_bt_trace_handle_create") bt_trace_handle_create(struct bt_context *ctx);
 446 %rename("_bt_trace_handle_destroy") bt_trace_handle_destroy(struct bt_trace_handle *bt);
 447 struct bt_trace_handle *bt_trace_handle_create(struct bt_context *ctx);
 448 void bt_trace_handle_destroy(struct bt_trace_handle *bt);
 449
 450 %rename("_bt_trace_handle_get_path") bt_trace_handle_get_path(struct bt_context *ctx,
 451                 int handle_id);
 452 %rename("_bt_trace_handle_get_timestamp_begin") bt_trace_handle_get_timestamp_begin(
 453                 struct bt_context *ctx, int handle_id, enum bt_clock_type type);
 454 %rename("_bt_trace_handle_get_timestamp_end") bt_trace_handle_get_timestamp_end(
 455                 struct bt_context *ctx, int handle_id, enum bt_clock_type type);
 456 const char *bt_trace_handle_get_path(struct bt_context *ctx, int handle_id);
 457 uint64_t bt_trace_handle_get_timestamp_begin(struct bt_context *ctx, int handle_id,
 458                 enum bt_clock_type type);
 459 uint64_t bt_trace_handle_get_timestamp_end(struct bt_context *ctx, int handle_id,
 460                 enum bt_clock_type type);
 461
 462 %rename("_bt_ctf_event_get_handle_id") bt_ctf_event_get_handle_id(
 463                 const struct bt_ctf_event *event);
 464 int bt_ctf_event_get_handle_id(const struct bt_ctf_event *event);
 465
 466
 467 %pythoncode%{
 468
 469 class TraceHandle(object):
 470         """
 471         The TraceHandle allows the user to manipulate a trace file directly.
 472         It is a unique identifier representing a trace file.
 473         Do not instantiate.
 474         """
 475
 476         def __init__(self):
 477                 raise NotImplementedError("TraceHandle cannot be instantiated")
 478
 479         def __repr__(self):
 480                 return "Babeltrace TraceHandle: trace_id('{0}')".format(self._id)
 481
 482         def get_id(self):
 483                 """Return the TraceHandle id."""
 484                 return self._id
 485
 486         def get_path(self, context):
 487                 """Return the path of a TraceHandle."""
 488                 try:
 489                         return _bt_trace_handle_get_path(context._c, self._id)
 490                 except AttributeError:
 491                         raise TypeError("in get_path, "
 492                                 "argument 2 must be a Context instance")
 493
 494         def get_timestamp_begin(self, context, clock_type):
 495                 """Return the creation time of the buffers of a trace."""
 496                 try:
 497                         return _bt_trace_handle_get_timestamp_begin(
 498                                 context._c, self._id,clock_type)
 499                 except AttributeError:
 500                         raise TypeError("in get_timestamp_begin, "
 501                                 "argument 2 must be a Context instance")
 502
 503         def get_timestamp_end(self, context, clock_type):
 504                 """Return the destruction timestamp of the buffers of a trace."""
 505                 try:
 506                         return _bt_trace_handle_get_timestamp_end(
 507                                 context._c, self._id, clock_type)
 508                 except AttributeError:
 509                         raise TypeError("in get_timestamp_end, "
 510                                 "argument 2 must be a Context instance")
 511
 512 %}
 513
 514
 515
 516 // =================================================================
 517 //                              CTF
 518 // =================================================================
 519
 520 /* =================================================================
 521                 ITERATOR.H, EVENTS.H
 522                 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
 523 */
 524
 525 //Iterator
 526 %rename("_bt_ctf_iter_create") bt_ctf_iter_create(struct bt_context *ctx,
 527                 const struct bt_iter_pos *begin_pos,
 528                 const struct bt_iter_pos *end_pos);
 529 %rename("_bt_ctf_get_iter") bt_ctf_get_iter(struct bt_ctf_iter *iter);
 530 %rename("_bt_ctf_iter_destroy") bt_ctf_iter_destroy(struct bt_ctf_iter *iter);
 531 %rename("_bt_ctf_iter_read_event") bt_ctf_iter_read_event(struct bt_ctf_iter *iter);
 532
 533 struct bt_ctf_iter *bt_ctf_iter_create(struct bt_context *ctx,
 534                 const struct bt_iter_pos *begin_pos,
 535                 const struct bt_iter_pos *end_pos);
 536 struct bt_iter *bt_ctf_get_iter(struct bt_ctf_iter *iter);
 537 void bt_ctf_iter_destroy(struct bt_ctf_iter *iter);
 538 struct bt_ctf_event *bt_ctf_iter_read_event(struct bt_ctf_iter *iter);
 539
 540
 541 //Events
 542
 543 %rename("_bt_ctf_get_top_level_scope") bt_ctf_get_top_level_scope(const struct
 544                 bt_ctf_event *event, enum bt_ctf_scope scope);
 545 %rename("_bt_ctf_event_name") bt_ctf_event_name(const struct bt_ctf_event *ctf_event);
 546 %rename("_bt_ctf_get_timestamp") bt_ctf_get_timestamp(
 547                 const struct bt_ctf_event *ctf_event);
 548 %rename("_bt_ctf_get_cycles") bt_ctf_get_cycles(
 549                 const struct bt_ctf_event *ctf_event);
 550
 551 %rename("_bt_ctf_get_field") bt_ctf_get_field(const struct bt_ctf_event *ctf_event,
 552                 const struct bt_definition *scope,      const char *field);
 553 %rename("_bt_ctf_get_index") bt_ctf_get_index(const struct bt_ctf_event *ctf_event,
 554                 const struct bt_definition *field,      unsigned int index);
 555 %rename("_bt_ctf_field_name") bt_ctf_field_name(const struct bt_definition *field);
 556 %rename("_bt_ctf_field_type") bt_ctf_field_type(const struct bt_declaration *field);
 557 %rename("_bt_ctf_get_int_signedness") bt_ctf_get_int_signedness(
 558                 const struct bt_declaration *field);
 559 %rename("_bt_ctf_get_int_base") bt_ctf_get_int_base(const struct bt_declaration *field);
 560 %rename("_bt_ctf_get_int_byte_order") bt_ctf_get_int_byte_order(
 561                 const struct bt_declaration *field);
 562 %rename("_bt_ctf_get_int_len") bt_ctf_get_int_len(const struct bt_declaration *field);
 563 %rename("_bt_ctf_get_enum_int") bt_ctf_get_enum_int(const struct bt_definition *field);
 564 %rename("_bt_ctf_get_enum_str") bt_ctf_get_enum_str(const struct bt_definition *field);
 565 %rename("_bt_ctf_get_encoding") bt_ctf_get_encoding(const struct bt_declaration *field);
 566 %rename("_bt_ctf_get_array_len") bt_ctf_get_array_len(const struct bt_declaration *field);
 567 %rename("_bt_ctf_get_uint64") bt_ctf_get_uint64(const struct bt_definition *field);
 568 %rename("_bt_ctf_get_int64") bt_ctf_get_int64(const struct bt_definition *field);
 569 %rename("_bt_ctf_get_char_array") bt_ctf_get_char_array(const struct bt_definition *field);
 570 %rename("_bt_ctf_get_string") bt_ctf_get_string(const struct bt_definition *field);
 571 %rename("_bt_ctf_field_get_error") bt_ctf_field_get_error(void);
 572 %rename("_bt_ctf_get_decl_event_name") bt_ctf_get_decl_event_name(const struct
 573                 bt_ctf_event_decl *event);
 574 %rename("_bt_ctf_get_decl_field_name") bt_ctf_get_decl_field_name(
 575                 const struct bt_ctf_field_decl *field);
 576 %rename("_bt_ctf_get_decl_from_def") bt_ctf_get_decl_from_def(
 577                 const struct bt_definition *field);
 578 %rename("_bt_array_index") bt_array_index(struct definition_array *array, uint64_t i);
 579
 580 const struct bt_definition *bt_ctf_get_top_level_scope(const struct bt_ctf_event *ctf_event,
 581                 enum bt_ctf_scope scope);
 582 const char *bt_ctf_event_name(const struct bt_ctf_event *ctf_event);
 583 uint64_t bt_ctf_get_timestamp(const struct bt_ctf_event *ctf_event);
 584 uint64_t bt_ctf_get_cycles(const struct bt_ctf_event *ctf_event);
 585 const struct bt_definition *bt_ctf_get_field(const struct bt_ctf_event *ctf_event,
 586                 const struct bt_definition *scope,
 587                 const char *field);
 588 const struct bt_definition *bt_ctf_get_index(const struct bt_ctf_event *ctf_event,
 589                 const struct bt_definition *field,
 590                 unsigned int index);
 591 const char *bt_ctf_field_name(const struct bt_definition *field);
 592 enum ctf_type_id bt_ctf_field_type(const struct bt_declaration *field);
 593 int bt_ctf_get_int_signedness(const struct bt_declaration *field);
 594 int bt_ctf_get_int_base(const struct bt_declaration *field);
 595 int bt_ctf_get_int_byte_order(const struct bt_declaration *field);
 596 ssize_t bt_ctf_get_int_len(const struct bt_declaration *field);
 597 const struct bt_definition *bt_ctf_get_enum_int(const struct bt_definition *field);
 598 const char *bt_ctf_get_enum_str(const struct bt_definition *field);
 599 enum ctf_string_encoding bt_ctf_get_encoding(const struct bt_declaration *field);
 600 int bt_ctf_get_array_len(const struct bt_declaration *field);
 601 struct bt_definition *bt_array_index(struct definition_array *array, uint64_t i);
 602 uint64_t bt_ctf_get_uint64(const struct bt_definition *field);
 603 int64_t bt_ctf_get_int64(const struct bt_definition *field);
 604 char *bt_ctf_get_char_array(const struct bt_definition *field);
 605 char *bt_ctf_get_string(const struct bt_definition *field);
 606 int bt_ctf_field_get_error(void);
 607 const char *bt_ctf_get_decl_event_name(const struct bt_ctf_event_decl *event);
 608 const char *bt_ctf_get_decl_field_name(const struct bt_ctf_field_decl *field);
 609 const struct bt_declaration *bt_ctf_get_decl_from_def(const struct bt_definition *field);
 610
 611 %pythoncode%{
 612
 613 class ctf:
 614
 615         #enum equivalent, accessible constants
 616         #These are taken directly from ctf/events.h
 617         #All changes to enums must also be made here
 618         class type_id:
 619                 UNKNOWN = 0
 620                 INTEGER = 1
 621                 FLOAT = 2
 622                 ENUM = 3
 623                 STRING = 4
 624                 STRUCT = 5
 625                 UNTAGGED_VARIANT = 6
 626                 VARIANT = 7
 627                 ARRAY = 8
 628                 SEQUENCE = 9
 629                 NR_CTF_TYPES = 10
 630
 631         class scope:
 632                 TRACE_PACKET_HEADER = 0
 633                 STREAM_PACKET_CONTEXT = 1
 634                 STREAM_EVENT_HEADER = 2
 635                 STREAM_EVENT_CONTEXT = 3
 636                 EVENT_CONTEXT = 4
 637                 EVENT_FIELDS = 5
 638
 639         class string_encoding:
 640                 NONE = 0
 641                 UTF8 = 1
 642                 ASCII = 2
 643                 UNKNOWN = 3
 644
 645         class Iterator(Iterator, object):
 646                 """
 647                 Allocate a CTF trace collection iterator.
 648
 649                 begin_pos and end_pos are optional parameters to specify the
 650                 position at which the trace collection should be seeked upon
 651                 iterator creation, and the position at which iteration will
 652                 start returning "EOF".
 653
 654                 By default, if begin_pos is None, a SEEK_CUR is performed at
 655                 creation. By default, if end_pos is None, a SEEK_END (end of
 656                 trace) is the EOF criterion.
 657
 658                 Only one iterator can be created against a context. If more than one
 659                 iterator is being created for the same context, the second creation
 660                 will return None. The previous iterator must be destroyed before
 661                 creation of the new iterator for this function to succeed.
 662                 """
 663
 664                 def __new__(cls, context, begin_pos = None, end_pos = None):
 665                         # __new__ is used to control the return value
 666                         # as the ctf.Iterator class should return None
 667                         # if bt_ctf_iter_create returns NULL
 668
 669                         if begin_pos is None:
 670                                 bp = None
 671                         else:
 672                                 bp = begin_pos._pos
 673                         if end_pos is None:
 674                                 ep = None
 675                         else:
 676                                 ep = end_pos._pos
 677                         try:
 678                                 it = _bt_ctf_iter_create(context._c, bp, ep)
 679                         except AttributeError:
 680                                 raise TypeError("in __init__, "
 681                                         "argument 2 must be a Context instance")
 682                         if it is None:
 683                                 return None
 684
 685                         ret_class = super(ctf.Iterator, cls).__new__(cls)
 686                         ret_class._i = it
 687                         return ret_class
 688
 689                 def __init__(self, context, begin_pos = None, end_pos = None):
 690                         Iterator.__init__(self, None, None, None,
 691                                 _bt_ctf_get_iter(self._i))
 692
 693                 def __del__(self):
 694                         _bt_ctf_iter_destroy(self._i)
 695
 696                 def read_event(self):
 697                         """
 698                         Read the iterator's current event data.
 699                         Return current event on success, None on end of trace.
 700                         """
 701                         ret = _bt_ctf_iter_read_event(self._i)
 702                         if ret is None:
 703                                 return ret
 704                         ev = ctf.Event.__new__(ctf.Event)
 705                         ev._e = ret
 706                         return ev
 707
 708
 709         class Event(object):
 710                 """
 711                 This class represents an event from the trace.
 712                 It is obtained with read_event() from ctf.Iterator.
 713                 Do not instantiate.
 714                 """
 715
 716                 def __init__(self):
 717                         raise NotImplementedError("ctf.Event cannot be instantiated")
 718
 719                 def get_top_level_scope(self, scope):
 720                         """
 721                         Return a definition of the top-level scope
 722                         Top-level scopes are defined in ctf.scope.
 723                         In order to get a field or a field list, the user needs to pass a
 724                         scope as argument, this scope can be a top-level scope or a scope
 725                         relative to an arbitrary field. This function provides the mapping
 726                         between the scope and the actual definition of top-level scopes.
 727                         On error return None.
 728                         """
 729                         evDef = ctf.Definition.__new__(ctf.Definition)
 730                         evDef._d = _bt_ctf_get_top_level_scope(self._e, scope)
 731                         if evDef._d is None:
 732                                 return None
 733                         return evDef
 734
 735                 def get_name(self):
 736                         """Return the name of the event or None on error."""
 737                         return _bt_ctf_event_name(self._e)
 738
 739                 def get_cycles(self):
 740                         """
 741                         Return the timestamp of the event as written in
 742                         the packet (in cycles) or -1ULL on error.
 743                         """
 744                         return _bt_ctf_get_cycles(self._e)
 745
 746                 def get_timestamp(self):
 747                         """
 748                         Return the timestamp of the event offsetted with the
 749                         system clock source or -1ULL on error.
 750                         """
 751                         return _bt_ctf_get_timestamp(self._e)
 752
 753                 def get_field_with_scope(self, scope, field):
 754                         """
 755                         Return the definition of a specific field.
 756                         Return None on error.
 757                         """
 758                         evDef = ctf.Definition.__new__(ctf.Definition)
 759                         try:
 760                                 evDef._d = _bt_ctf_get_field(self._e, scope._d, field)
 761                         except AttributeError:
 762                                 raise TypeError("in get_field, argument 2 must be a "
 763                                         "Definition (scope) instance")
 764                         if evDef._d is None:
 765                                 return None
 766                         evDef._s = scope
 767                         return evDef
 768
 769                 def get_field(self, field):
 770                         """
 771                         Return the definition of fields by a name
 772                         Return None on error
 773                         """
 774                         eventScope = self.get_top_level_scope(ctf.scope.EVENT_FIELDS)
 775                         streamScope = self.get_top_level_scope(ctf.scope.STREAM_EVENT_CONTEXT)
 776                         fields_by_name = []
 777
 778                         if eventScope is not None:
 779                                 evDef = self.get_field_with_scope(eventScope, field)
 780                                 if evDef is not None:
 781                                         fields_by_name.append(evDef)
 782
 783                         if streamScope is not None:
 784                                 evDef = self.get_field_with_scope(streamScope, field)
 785                                 if evDef is not None:
 786                                         fields_by_name.append(evDef);
 787
 788                         if not fields_by_name:
 789                                 return None
 790                         return fields_by_name
 791
 792                 def get_field_list_with_scope(self, scope):
 793                         """
 794                         Return a list of Definitions associated with the scope
 795                         Return None on error.
 796                         """
 797                         try:
 798                                 field_lc = _bt_python_field_listcaller(self._e, scope._d)
 799                         except AttributeError:
 800                                 raise TypeError("in get_field_list, argument 2 must be a "
 801                                         "Definition (scope) instance")
 802
 803                         if field_lc is None:
 804                                 return None
 805
 806                         def_list = []
 807                         i = 0
 808                         while True:
 809                                 tmp = ctf.Definition.__new__(ctf.Definition)
 810                                 tmp._d = _bt_python_field_one_from_list(field_lc, i)
 811
 812                                 if tmp._d is None:
 813                                         #Last item of list is None, assured in
 814                                         #_bt_python_field_listcaller
 815                                         break
 816
 817                                 tmp._s = scope
 818                                 def_list.append(tmp)
 819                                 i += 1
 820                         return def_list
 821
 822                 def get_field_list(self):
 823                         """Return a list of Definitions or None on error."""
 824                         eventScope = self.get_top_level_scope(ctf.scope.EVENT_FIELDS)
 825                         streamScope = self.get_top_level_scope(ctf.scope.STREAM_EVENT_CONTEXT)
 826
 827                         def_list = []
 828                         if eventScope is not None:
 829                                 event_field_list = self.get_field_list_with_scope(eventScope)
 830                                 if event_field_list is not None:
 831                                         def_list = event_field_list
 832
 833                         if streamScope is not None:
 834                                 event_field_list = self.get_field_list_with_scope(streamScope)
 835                                 if event_field_list is not None:
 836                                         def_list.extend(event_field_list)
 837
 838                         if not def_list:
 839                                 return None
 840                         return def_list
 841
 842                 def get_index(self, field, index):
 843                         """
 844                         If the field is an array or a sequence, return the element
 845                         at position index, otherwise return None
 846                         """
 847                         evDef = ctf.Definition.__new__(ctf.Definition)
 848                         try:
 849                                 evDef._d = _bt_ctf_get_index(self._e, field._d, index)
 850                         except AttributeError:
 851                                 raise TypeError("in get_index, argument 2 must be a "
 852                                         "Definition (field) instance")
 853
 854                         if evDef._d is None:
 855                                 return None
 856                         return evDef
 857
 858                 def get_handle(self):
 859                         """
 860                         Get the TraceHandle associated with an event
 861                         Return None on error
 862                         """
 863                         ret = _bt_ctf_event_get_handle_id(self._e)
 864                         if ret < 0:
 865                                 return None
 866
 867                         th = TraceHandle.__new__(TraceHandle)
 868                         th._id = ret
 869                         return th
 870
 871                 def get_context(self):
 872                         """
 873                         Get the context associated with an event.
 874                         Return None on error.
 875                         """
 876                         ctx = Context()
 877                         ctx._c = _bt_ctf_event_get_context(self._e);
 878                         if ctx._c is None:
 879                                 return None
 880                         else:
 881                                 return ctx
 882
 883
 884         class Definition(object):
 885                 """Definition class.  Do not instantiate."""
 886
 887                 def __init__(self):
 888                         raise NotImplementedError("ctf.Definition cannot be instantiated")
 889
 890                 def __repr__(self):
 891                         return "Babeltrace Definition: name('{0}'), type({1})".format(
 892                                 self.field_name(), self.field_type())
 893
 894                 def field_name(self):
 895                         """Return the name of a field or None on error."""
 896                         return _bt_ctf_field_name(self._d)
 897
 898                 def field_type(self):
 899                         """Return the type of a field or -1 if unknown."""
 900                         return _bt_ctf_field_type(_bt_ctf_get_decl_from_def(self._d))
 901
 902                 def get_int_signedness(self):
 903                         """
 904                         Return the signedness of an integer:
 905                         0 if unsigned; 1 if signed; -1 on error.
 906                         """
 907                         return _bt_ctf_get_int_signedness(_bt_ctf_get_decl_from_def(self._d))
 908
 909                 def get_int_base(self):
 910                         """Return the base of an int or a negative value on error."""
 911                         return _bt_ctf_get_int_base(_bt_ctf_get_decl_from_def(self._d))
 912
 913                 def get_int_byte_order(self):
 914                         """
 915                         Return the byte order of an int or a negative
 916                         value on error.
 917                         """
 918                         return _bt_ctf_get_int_byte_order(_bt_ctf_get_decl_from_def(self._d))
 919
 920                 def get_int_len(self):
 921                         """
 922                         Return the size, in bits, of an int or a negative
 923                         value on error.
 924                         """
 925                         return _bt_ctf_get_int_len(_bt_ctf_get_decl_from_def(self._d))
 926
 927                 def get_enum_str(self):
 928                         """
 929                         Return the string matching the current enumeration.
 930                         Return None on error.
 931                         """
 932                         return _bt_ctf_get_enum_str(self._d)
 933
 934                 def get_encoding(self):
 935                         """
 936                         Return the encoding of an int or a string.
 937                         Return a negative value on error.
 938                         """
 939                         return _bt_ctf_get_encoding(_bt_ctf_get_decl_from_def(self._d))
 940
 941                 def get_array_len(self):
 942                         """
 943                         Return the len of an array or a negative
 944                         value on error.
 945                         """
 946                         return _bt_ctf_get_array_len(_bt_ctf_get_decl_from_def(self._d))
 947
 948                 def get_array_element_at(self, index):
 949                         """
 950                         Return the array's element at position index.
 951                         Return None on error
 952                         """
 953                         array = _bt_python_get_array_from_def(self._d)
 954                         if array is None:
 955                                 return None
 956
 957                         element = ctf.Definition.__new__(ctf.Definition)
 958                         element._d =  _bt_array_index(array, index)
 959                         if element._d is None:
 960                                 return None
 961                         return element
 962
 963                 def get_uint64(self):
 964                         """
 965                         Return the value associated with the field.
 966                         If the field does not exist or is not of the type requested,
 967                         the value returned is undefined. To check if an error occured,
 968                         use the ctf.field_error() function after accessing a field.
 969                         """
 970                         return _bt_ctf_get_uint64(self._d)
 971
 972                 def get_int64(self):
 973                         """
 974                         Return the value associated with the field.
 975                         If the field does not exist or is not of the type requested,
 976                         the value returned is undefined. To check if an error occured,
 977                         use the ctf.field_error() function after accessing a field.
 978                         """
 979                         return _bt_ctf_get_int64(self._d)
 980
 981                 def get_char_array(self):
 982                         """
 983                         Return the value associated with the field.
 984                         If the field does not exist or is not of the type requested,
 985                         the value returned is undefined. To check if an error occured,
 986                         use the ctf.field_error() function after accessing a field.
 987                         """
 988                         return _bt_ctf_get_char_array(self._d)
 989
 990                 def get_str(self):
 991                         """
 992                         Return the value associated with the field.
 993                         If the field does not exist or is not of the type requested,
 994                         the value returned is undefined. To check if an error occured,
 995                         use the ctf.field_error() function after accessing a field.
 996                         """
 997                         return _bt_ctf_get_string(self._d)
 998
 999                 def get_value(self):
1000                         """
1001                         Return the value associated with the field according to its type.
1002                         Return None on error.
1003                         """
1004                         id = self.field_type()
1005                         if id == ctf.type_id.STRING:
1006                                 return self.get_str()
1007                         if id == ctf.type_id.ARRAY:
1008                                 array = []
1009                                 for i in range(self.get_array_len()):
1010                                         element = self.get_array_element_at(i)
1011                                         array.append(element.get_value())
1012                                 return array
1013                         if id == ctf.type_id.INTEGER:
1014                                 if self.get_int_signedness() == 0:
1015                                         return self.get_uint64()
1016                                 else:
1017                                         return self.get_int64()
1018                         if id == ctf.type_id.ENUM:
1019                                 return self.get_enum_str()
1020                         return None
1021
1022                 def get_scope(self):
1023                         """Return the scope of a field or None on error."""
1024                         return self._s
1025
1026         class EventDecl(object):
1027                 """Event declaration class.  Do not instantiate."""
1028
1029                 def __init__(self):
1030                         raise NotImplementedError("ctf.EventDecl cannot be instantiated")
1031
1032                 def __repr__(self):
1033                         return "Babeltrace EventDecl: name {0}".format(self.get_name())
1034
1035                 def get_name(self):
1036                         """Return the name of the event or None on error"""
1037                         return _bt_ctf_get_decl_event_name(self._d)
1038
1039                 def get_decl_fields(self, scope):
1040                         """
1041                         Return a list of ctf.FieldDecl
1042                         Return None on error.
1043                         """
1044                         ptr_list = _by_python_field_decl_listcaller(self._d, scope)
1045
1046                         if ptr_list is None:
1047                                 return None
1048
1049                         decl_list = []
1050                         i = 0
1051                         while True:
1052                                 tmp = ctf.FieldDecl.__new__(ctf.FieldDecl)
1053                                 tmp._d =  _bt_python_field_decl_one_from_list(
1054                                         ptr_list, i)
1055
1056                                 if tmp._d is None:
1057                                         #Last item of list is None
1058                                         break
1059
1060                                 decl_list.append(tmp)
1061                                 i += 1
1062                         return decl_list
1063
1064
1065         class FieldDecl(object):
1066                 """Field declaration class.  Do not instantiate."""
1067
1068                 def __init__(self):
1069                         raise NotImplementedError("ctf.FieldDecl cannot be instantiated")
1070
1071                 def __repr__(self):
1072                         return "Babeltrace FieldDecl: name {0}".format(self.get_name())
1073
1074                 def get_name(self):
1075                         """Return the name of a FieldDecl or None on error"""
1076                         return _bt_ctf_get_decl_field_name(self._d)
1077
1078
1079         @staticmethod
1080         def field_error():
1081                 """
1082                 Return the last error code encountered while
1083                 accessing a field and reset the error flag.
1084                 Return 0 if no error, a negative value otherwise.
1085                 """
1086                 return _bt_ctf_field_get_error()
1087
1088         @staticmethod
1089         def get_event_decl_list(trace_handle, context):
1090                 """
1091                 Return a list of ctf.EventDecl
1092                 Return None on error.
1093                 """
1094                 try:
1095                         handle_id = trace_handle._id
1096                 except AttributeError:
1097                                 raise TypeError("in get_event_decl_list, "
1098                                         "argument 1 must be a TraceHandle instance")
1099                 try:
1100                         ptr_list = _bt_python_event_decl_listcaller(handle_id, context._c)
1101                 except AttributeError:
1102                                 raise TypeError("in get_event_decl_list, "
1103                                         "argument 2 must be a Context instance")
1104
1105                 if ptr_list is None:
1106                         return None
1107
1108                 decl_list = []
1109                 i = 0
1110                 while True:
1111                         tmp = ctf.EventDecl.__new__(ctf.EventDecl)
1112                         tmp._d =  _bt_python_decl_one_from_list(ptr_list, i)
1113
1114                         if tmp._d is None:
1115                                 #Last item of list is None
1116                                 break
1117
1118                         decl_list.append(tmp)
1119                         i += 1
1120                 return decl_list
1121
1122 %}
1123
1124
1125
1126 // =================================================================
1127 //                            NEW FUNCTIONS
1128 //                         File and list-related
1129 //                         python-complements.h
1130 // =================================================================
1131
1132 %include python-complements.c
1133
1134 %pythoncode %{
1135
1136 class File(object):
1137         """
1138         Open a file for babeltrace.
1139
1140         file_path is a string containing the path or None to use the
1141         standard output in writing mode.
1142
1143         The mode can be 'r', 'w' or 'a' for reading (default), writing or
1144         appending.  The file will be created if it doesn't exist when
1145         opened for writing or appending; it will be truncated when opened
1146         for writing.  Add a 'b' to the mode for binary files.  Add a '+'
1147         to the mode to allow simultaneous reading and writing.
1148         """
1149
1150         def __new__(cls, file_path, mode='r'):
1151                 # __new__ is used to control the return value
1152                 # as the File class should return None
1153                 # if _bt_file_open returns NULL
1154
1155                 # Type check
1156                 if file_path is not None and type(file_path) is not str:
1157                         raise TypeError("in method __init__, argument 2 of type 'str'")
1158                 if type(mode) is not str:
1159                         raise TypeError("in method __init__, argument 3 of type 'str'")
1160
1161                 # Opening file
1162                 file_ptr = _bt_file_open(file_path, mode)
1163                 if file_ptr is None:
1164                         return None
1165
1166                 # Class instantiation
1167                 file_inst = super(File, cls).__new__(cls)
1168                 file_inst._file = file_ptr
1169                 return file_inst
1170
1171         def __init__(self, file_path, mode='r'):
1172                 self._opened = True
1173                 self._use_stdout = False
1174
1175                 if file_path is None:
1176                         # use stdout
1177                         file_path = "stdout"
1178                         mode = 'w'
1179                         self._use_stdout = True
1180
1181                 self._file_path = file_path
1182                 self._mode = mode
1183
1184         def __del__(self):
1185                 self.close()
1186
1187         def __repr__(self):
1188                 if self._opened:
1189                         stat = 'opened'
1190                 else:
1191                         stat = 'closed'
1192                 return "{0} babeltrace File; file_path('{1}'), mode('{2}')".format(
1193                         stat, self._file_path, self._mode)
1194
1195         def close(self):
1196                 """Close the file.  Is also called using del."""
1197                 if self._opened and not self._use_stdout:
1198                         _bt_file_close(self._file)
1199                         self._opened = False
1200 %}