X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;ds=inline;f=doc%2Fapi%2Flibbabeltrace2%2Fdox%2Fgroup-trace-ir.dox;fp=doc%2Fapi%2Flibbabeltrace2%2Fdox%2Fgroup-trace-ir.dox;h=db258057ce58fbb1a6e6d25582f80ee2aa5e2a09;hb=43c59509042845f8d42c3e99ec74d45fa2dc0908;hp=0000000000000000000000000000000000000000;hpb=1cda4ff4025e4b3f7bd2a861baa51d2113c4cbf9;p=babeltrace.git
diff --git a/doc/api/libbabeltrace2/dox/group-trace-ir.dox b/doc/api/libbabeltrace2/dox/group-trace-ir.dox
new file mode 100644
index 00000000..db258057
--- /dev/null
+++ b/doc/api/libbabeltrace2/dox/group-trace-ir.dox
@@ -0,0 +1,108 @@
+/*!
+@defgroup api-tir Trace IR
+@ingroup api-msg
+
+@brief
+ Intermediate representation of
+ tracing
+ domain objects and concepts (contents of \bt_p_msg).
+
+The \bt_name
+trace IR (intermediate representation) modules
+contain everything you need to represent tracing domain concepts and
+objects so that many \bt_p_comp, written by different authors, can
+exchange trace metadata and data.
+
+The trace IR objects are divided into two main categories:
+
+
+ - Metadata
+ -
+ Classes of data objects.
+
+ A metadata object describes many data objects.
+
+ For example, an \bt_ev_cls describes the numeric ID, name, logging
+ level, and \ref api-tir-fc "classes" of payload \bt_p_field of all
+ the \bt_p_ev you create from it.
+
+ Metadata objects are one of the most valuable concepts of
+ \bt_name: because they describe the structures of many
+ data objects at once, they enable great space and time
+ optimizations.
+
+ For example, a \bt_sink_comp which writes a trace following a
+ metadata-supporting format, such as the
+ Common Trace Format, can
+ serialize the metadata objects once so that the data objects are
+ more compact and take less time to write.
+
+ The metadata objects are:
+
+ - \bt_c_clock_cls
+ - \bt_c_ev_cls
+ - \bt_cp_fc
+ - \bt_c_field_path
+ - \bt_c_stream_cls
+ - \bt_c_trace_cls
+
+
+ - Data
+ -
+ Instances of metadata objects.
+
+ For example, a \bt_stream is an instance of a \bt_stream_cls.
+
+ The data objects are:
+
+ - \bt_c_cs
+ - \bt_c_ev
+ - \bt_cp_field
+ - \bt_c_pkt
+ - \bt_c_stream
+ - \bt_c_trace
+
+
+
+The trace IR metadata to data object association is:
+
+
+
+ Metadata object
+ | Data object
+ |
+ \bt_c_clock_cls
+ | Stream clock (see \ref api-tir-cs)
+ |
+ \bt_c_ev_cls
+ | \bt_c_ev
+ |
+ \bt_c_fc
+ | \bt_c_field
+ |
+ \bt_c_stream_cls
+ | \bt_c_stream
+ |
+ \bt_c_trace_cls
+ | \bt_c_trace
+ |
+
+Within a trace processing \bt_graph, \bt_p_msg carry data objects from
+\bt_comp to component.
+
+You need to create metadata objects \em before you create data objects.
+You can then use the data objects to create messages.
+
+For example, you need a \bt_stream_cls to create a \bt_stream. With
+a \bt_stream, you can create a \bt_p_sb_msg, \bt_p_se_msg, \bt_p_ev_msg,
+and other types of messages.
+
+Usually, when you create a data object from a metadata object, the
+metadata object becomes \ref api-fund-freezing "frozen": you cannot
+modify it for the rest of its lifetime.
+
+All metadata objects and some data objects have an optional user
+attributes property (a \bt_map_val): you can use it to attach
+custom attributes, without any semantics specified by the \bt_name
+project, to those objects.
+*/