API documentation
authorDanny Serres <danny.serres@efficios.com>
Fri, 24 Aug 2012 01:08:51 +0000 (21:08 -0400)
committerMathieu Desnoyers <mathieu.desnoyers@efficios.com>
Fri, 24 Aug 2012 01:08:51 +0000 (21:08 -0400)
Signed-off-by: Danny Serres <danny.serres@efficios.com>
Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
doc/API.txt [new file with mode: 0644]
doc/Makefile.am

diff --git a/doc/API.txt b/doc/API.txt
new file mode 100644 (file)
index 0000000..f1780f0
--- /dev/null
@@ -0,0 +1,247 @@
+Babeltrace API documentation
+
+Babeltrace provides trace read and write libraries, as well as a trace
+converter. A plugin can be created for any trace format to allow its
+conversion to/from another trace format.
+
+The main format expected to be converted to/from is the Common Trace
+Format (CTF). The latest version of the CTF specification can be found at:
+       git tree:   git://git.efficios.com/ctf.git
+       gitweb:     http://git.efficios.com/?p=ctf.git
+
+This document describes the main concepts to use the libbabeltrace,
+which exposes the Babeltrace trace reading capability.
+
+
+TERMINOLOGY
+¯¯¯¯¯¯¯¯¯¯¯
+
+* A "callback" is a reference to a piece of executable code (such as a
+  function) that is passed as an argument to another piece of code
+  (like another function).
+
+* A "context" is a structure that represents an object in which a trace
+  collection is opened.
+
+* An "iterator" is a structure that enables the user to traverse a trace.
+
+* A "trace handle" is a unique identifier representing a trace file.
+  It allows the user to manipulate a trace directly.
+
+
+
+USAGE
+¯¯¯¯¯¯
+
+Context:
+
+In order to use libbabeltrace to read a trace, the first step is to create a
+context structure and to add a trace to it. This is done using the
+bt_context_create() and bt_context_add_trace() functions. As long as this
+context structure is allocated and the trace is valid, the trace can be
+manipulated by the library.
+
+The context can be destroyed by calling one more bt_context_put() than
+bt_context_get(), functions which respectively decrement and increment the
+refcount of the context. These functions ensures that the context won't be
+destroyed when it is in use.
+
+Once a trace is added to the context, it can be read and seeked using iterators
+and callbacks.
+
+
+Iterator:
+
+An iterator can be created using the bt_iter_create() function. As of now, only
+ctf iterator are supported. These are used to traverse a ctf-formatted trace.
+Such iterators can be created with bt_ctf_iter_create().
+
+While creating an iterator, a begin and an end position may be specified. To do
+so, one or two struct bt_iter_pos must be passed. Such struct have two
+attributes: type and u. "type" is the seek type, can be either:
+       BT_SEEK_TIME
+       BT_SEEK_RESTORE
+       BT_SEEK_CUR
+       BT_SEEK_BEGIN
+       BT_SEEK_END
+and "u" is a union of the seek time (if using BT_SEEK_TIME) and the restore
+position (if using BT_SEEK_RESTORE).
+
+Once the iterator is created, various functions become available. We have
+bt_ctf_iter_read_event() which returns the ctf event of the trace where the
+iterator is set. There is also bt_ctf_iter_destroy() which frees the iterator.
+Note that only one iterator can be created in a context at the same time. If
+more than one iterator is being created for the same context, the second
+creation will return NULL. The previous iterator must be destroyed before
+creation of the new iterator. In the future, creation of multiples iterators
+will be allowed.
+
+Finally, we have the bt_ctf_get_iter() function which returns a struct bt_iter
+with which the iterator can be moved using one of these functions:
+       bt_iter_next(),         moves the iterator to the next event
+       bt_iter_set_pos(),      moves the iterator to the specified position
+
+To get the current position (struct bt_iter_pos) of the iterator, the function
+bt_iter_get_pos() must be used. To create an arbitrary position based on a
+specific time, bt_iter_create_time_pos() is the function to use. The
+bt_iter_pos structure returned by these two functions must be freed with
+bt_iter_free_pos() after use.
+
+
+CTF Event:
+
+A CTF event is obtained from an iterator via the bt_ctf_iter_read_event()
+function or via the call_data parameter of a callback. To read the data of a
+CTF event :
+       * bt_ctf_event_name()           returns the name of the event;
+       * bt_ctf_get_timestamp()        returns the timestamp of the event
+                                       offsetted with the system clock
+                                       source (in ns);
+       * bt_ctf_get_cycles()           returns the timestamp of the event as
+                                       written in the packet (in cycles).
+
+The payload of an event is divided in various scopes depending on the type of
+information. There are six top-level scopes (defined in the bt_ctf_scope enum)
+which can be accessed by the bt_ctf_get_top_level_scope() function :
+       BT_TRACE_PACKET_HEADER          = 0,
+       BT_STREAM_PACKET_CONTEXT        = 1,
+       BT_STREAM_EVENT_HEADER          = 2,
+       BT_STREAM_EVENT_CONTEXT         = 3,
+       BT_EVENT_CONTEXT                = 4,
+       BT_EVENT_FIELDS                 = 5.
+
+In order to access a field or a field list, the user needs to pass a scope as
+argument, this scope can be a top-level scope or a scope relative to an
+arbitrary field in the case of compound types (array, sequence, structure or
+variant)
+
+For more information on each scope, see the CTF specifications.
+
+The function to get a field list is the bt_ctf_get_field_list(). The function
+to get the definition of a specific field is bt_ctf_get_field().
+
+Once the field is obtained, we can obtain its name and type using the
+bt_ctf_field_name() and bt_ctf_field_type() functions respectively. The
+possible types are defined in the ctf_type_id enum:
+       CTF_TYPE_UNKNOWN = 0,
+       CTF_TYPE_INTEGER,
+       CTF_TYPE_FLOAT,
+       CTF_TYPE_ENUM,
+       CTF_TYPE_STRING,
+       CTF_TYPE_STRUCT,
+       CTF_TYPE_UNTAGGED_VARIANT,
+       CTF_TYPE_VARIANT,
+       CTF_TYPE_ARRAY,
+       CTF_TYPE_SEQUENCE,
+       NR_CTF_TYPES.
+
+Depending on the field type, we can get informations about the field with these
+functions:
+       * bt_ctf_get_index()            return the element at the index
+                                       position of an array of a sequence;
+
+       * bt_ctf_get_array_len()        return the length of an array;
+
+       * bt_ctf_get_int_signedness()   return the signedness of an integer;
+
+       * bt_ctf_get_int_base()         return the base of an integer;
+
+       * bt_ctf_get_int_byte_order()   return the byte order of an integer;
+
+       * bt_ctf_get_int_len()          return the size in bits of an integer;
+
+       * bt_ctf_get_encoding()         return the encoding of an int or a
+                                       string defined in the
+                                       ctf_string_encoding enum:
+                                               CTF_STRING_NONE = 0,
+                                               CTF_STRING_UTF8,
+                                               CTF_STRING_ASCII,
+                                               CTF_STRING_UNKNOWN.
+
+These functions give access to the value associated with a field :
+       * bt_ctf_get_uint64();
+       * bt_ctf_get_int64();
+       * bt_ctf_get_char_array();
+       * bt_ctf_get_string().
+
+If the field does not exist or is not of the type requested, the value returned
+with these four functions is undefined. To check if an error occured, use the
+bt_ctf_field_get_error() function after accessing a field. If no error
+occured, the function will return 0.
+
+It is also possible to access the declaration fields, the same way as the
+definition ones. bt_ctf_get_event_decl_list() sets a list to an array of
+bt_ctf_event_decl pointers and bt_ctf_get_event_decl_fields() sets a list to an
+array of bt_ctf_field_decl pointers.  From the first type, the name of the
+event can be obtained with bt_ctf_get_decl_event_name().  For the second type,
+the field decl name is obtained with bt_ctf_get_decl_field_name().
+
+The declaration functions allow the user to list the events, fields and
+contexts fields enabled in the trace once it is opened, whereas the definition
+functions apply on the current event being read.
+
+
+Callback:
+
+The iterator allow the user to read the trace, in order to access the events
+and fields, the user can either call the functions listed previously on each
+event, or register callbacks functions that are called when specific (or all)
+events are read.
+
+This is done with the bt_ctf_iter_add_callback() function. It requires a valid
+ctf iterator as the first argument. Here are all arguments:
+       iter: trace collection iterator (input)
+       event: event to target. 0 for all events.
+       private_data: private data pointer to pass to the callback
+       flags: specific flags controlling the behavior of this callback
+               (or'd).
+       callback: function pointer to call
+       depends: struct bt_dependency detailing the required computation
+               results.  Ends with 0.
+       weak_depends: struct bt_dependency detailing the optional computation
+               results that can be optionally consumed by this
+               callback.
+       provides: struct bt_dependency detailing the computation results
+               provided by this callback.
+               Ends with 0.
+
+"depends", "weak_depends" and "provides" memory is handled by the babeltrace
+library after this call succeeds or fails. These objects can still be used by
+the caller until the babeltrace iterator is destroyed, but they belong to the
+babeltrace library.
+
+As of now the flags and dependencies are not used, the callbacks are
+processed in FIFO order.
+
+Note: once implemented, the dependency graph will be calculated when
+bt_ctf_iter_read_event() is executed after a bt_ctf_iter_add_callback(). It is
+valid to create/add callbacks/read/add more callbacks/read some more.
+
+The callback function passed to bt_ctf_iter_add_callback() must return a
+bt_cb_ret value:
+       BT_CB_OK                = 0,
+       BT_CB_OK_STOP           = 1,
+       BT_CB_ERROR_STOP        = 2,
+       BT_CB_ERROR_CONTINUE    = 3.
+
+
+Trace handle:
+
+When a trace is added to a context, bt_context_add_trace() returns a trace
+handle id.  This id is associated with its corresponding trace handle.  With
+that id, it is possible to manipulate directly the trace.
+
+       * bt_trace_handle_get_path()
+               -> returns the path of the trace handle (path to the trace).
+
+       * bt_trace_handle_get_timestamp_begin()
+       * bt_trace_handle_get_timestamp_end()
+               -> return the creation/destruction timestamps (in ns or cycles
+                       depending on the type specified) of the buffers of a
+                       trace.
+
+       * bt_ctf_event_get_handle_id()
+               -> returns the handle id associated with an event.
+
+
+For more information on CTF, see the CTF documentation.
index 88cb57fa09c9914a64c4d053687a7b66fc0ab7da..597c43e79922f8d31576f2a7c06a8d44dcd692a5 100644 (file)
@@ -1 +1,3 @@
 dist_man_MANS = babeltrace.1 babeltrace-log.1
+
+dist_doc_DATA = API.txt
This page took 0.036242 seconds and 4 git commands to generate.