Signed-off-by: Danny Serres <[email protected]> --- doc/API.txt | 257 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 257 insertions(+) create mode 100644 doc/API.txt
diff --git a/doc/API.txt b/doc/API.txt new file mode 100644 index 0000000..4688a75 --- /dev/null +++ b/doc/API.txt @@ -0,0 +1,257 @@ +Babeltrace API documentation + +Babeltrace is a trace viewer and converter reading and writing the +Common Trace Format (CTF). Its main use is to pretty-print CTF traces +into a human-readable text output. + +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, the trace is open and valid. + +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 for now, only ctf iterator are supported. These are used to traverse a ctf- +formatted trace. Such iterator 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 2 +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 free the iterator. +Note that only one iterator can be created against 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 probably 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(), which moves the position to the next event + bt_iter_set_pos(), which moves the position to the specified one + +To get the current position (struct bt_iter_pos) of the iterator, the function +bt_iter_get_pos() can be used. To get an arbitrary position based on a +specific time, bt_itet_create_time_pos() is the function to use. The position +returned by one of these two functions must be freed with bt_iter_free_pos() +after use. + + +CTF Event: + +A CTF event is usually obtained from an iterator via the +bt_ctf_iter_read_event() function, which returns a struct bt_ctf_event. Having +the event, we can collect its data: + * bt_ctf_event_name() will return the name of the event; + * bt_ctf_get_timestamp() will return the timestamp of the event + offsetted with the system clock source (in ns); + * bt_ctf_get_cycles will return the timestamp of the event as written + in the packet (in cycles). + +To access the event fields which contain various information, the first step is +to obtain a scope definition for the desired field. This can be done using the +bt_ctf_get_top_level_scope() function. This function provides the mapping +between the enum and the actual definition of top-level scopes and returns +a definition of the top-level scope. +Top-level scopes are defined in the bt_ctf_scope enum: + 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 get 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. + +For more information on each scope, see the CTF specifications. + +To get a field list, the bt_ctf_get_field_list() function is to be used. +To get the definition of a specific field, the appropriate function would be +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 data on its value using the appropriate +function: + * bt_ctf_get_index() return the element at the index + position of an array of a sequence; + + * bt_ctf_get_array_len() return the len 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. + +To obtain the value associated with a field, the appropriate function of these +is to be used: + + * 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. + +The other alternative to reading a trace is with the use of callbacks. This is +done with the bt_ctf_iter_add_callback() function. It still 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. + +Note: the dependency graph is calculated when bt_ctf_iter_read_event() is +executed after a bt_ctf_iter_add_callback(). Beware that it is valid to +create/add callbacks/read/add more callbacks/read some more. + +As of now the flags and dependencies are not used, the callbacks are +processed in FIFO order. + +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. -- 1.7.9.5 _______________________________________________ lttng-dev mailing list [email protected] http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev
