[lttng-dev] [babeltrace PATCH] API documentation file‏

[Julien Desfossez]

Hi Danny,

Thanks for the documentation, it is great !

I added some comments below.

On 09/08/12 05:39 PM, Danny Serres wrote:
> Signed-off-by: Danny Serres <danny.serres at efficios.com>
> ---
>  doc/API.txt |  237 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 237 insertions(+)
>  create mode 100644 doc/API.txt
> 
> diff --git a/doc/API.txt b/doc/API.txt
> new file mode 100644
> index 0000000..8cb7e31
> --- /dev/null
> +++ b/doc/API.txt
> @@ -0,0 +1,237 @@
> +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.
(taken from the babeltrace README) :
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.
> +
> +
> +TODO: add explanation for each scope (line 116)
You can just add a reference to the CTF spec for that.

> +
> +
> +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 openned.
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 file directly.
a trace, not trace file.

> +
> +
> +
> +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 collection is open.
(and the trace is valid)
trace, not trace collection
> +
> +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
> +or callbacks.
"and callbacks" (iterators are needed to read the trace, the callbacks
are only there to read the events)
> +
> +
> +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.
> +
> +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 file.
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 (git://git.efficios.com/ctf.git).

Thanks !

Julien