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

[Danny Serres]

Signed-off-by: Danny Serres <danny.serres at efficios.com>
---
 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