projects / babeltrace.git / blame
| Commit | Line | Data |
|---|---|---|
| 43c59509 PP |
1 | /*! |
| 2 | @defgroup api-tir Trace IR | |
| 3 | @ingroup api-msg | |
| 4 | ||
| 5 | @brief | |
| 6 | Intermediate representation of | |
| 7 | <a href="https://en.wikipedia.org/wiki/Tracing_(software)">tracing</a> | |
| 8 | domain objects and concepts (contents of \bt_p_msg). | |
| 9 | ||
| 10 | The \bt_name | |
| 11 | <strong><em>trace IR</em></strong> (intermediate representation) modules | |
| 12 | contain everything you need to represent tracing domain concepts and | |
| 13 | objects so that many \bt_p_comp, written by different authors, can | |
| 14 | exchange trace metadata and data. | |
| 15 | ||
| 16 | The trace IR objects are divided into two main categories: | |
| 17 | ||
| 18 | <dl> | |
| 19 | <dt>Metadata</dt> | |
| 20 | <dd> | |
| 21 | Classes of data objects. | |
| 22 | ||
| 23 | A metadata object describes many data objects. | |
| 24 | ||
| 25 | For example, an \bt_ev_cls describes the numeric ID, name, logging | |
| 26 | level, and \ref api-tir-fc "classes" of payload \bt_p_field of all | |
| 27 | the \bt_p_ev you create from it. | |
| 28 | ||
| 29 | Metadata objects are one of the most valuable concepts of | |
| 30 | \bt_name: because they describe the structures of many | |
| 31 | data objects at once, they enable great space and time | |
| 32 | optimizations. | |
| 33 | ||
| 34 | For example, a \bt_sink_comp which writes a trace following a | |
| 35 | metadata-supporting format, such as the | |
| 36 | <a href="https://diamon.org/ctf/">Common Trace Format</a>, can | |
| 37 | serialize the metadata objects once so that the data objects are | |
| 38 | more compact and take less time to write. | |
| 39 | ||
| 40 | The metadata objects are: | |
| 41 | ||
| 42 | - \bt_c_clock_cls | |
| 43 | - \bt_c_ev_cls | |
| 44 | - \bt_cp_fc | |
| 45 | - \bt_c_field_path | |
| 46 | - \bt_c_stream_cls | |
| 47 | - \bt_c_trace_cls | |
| 48 | </dd> | |
| 49 | ||
| 50 | <dt>Data</dt> | |
| 51 | <dd> | |
| 52 | Instances of metadata objects. | |
| 53 | ||
| 54 | For example, a \bt_stream is an instance of a \bt_stream_cls. | |
| 55 | ||
| 56 | The data objects are: | |
| 57 | ||
| 58 | - \bt_c_cs | |
| 59 | - \bt_c_ev | |
| 60 | - \bt_cp_field | |
| 61 | - \bt_c_pkt | |
| 62 | - \bt_c_stream | |
| 63 | - \bt_c_trace | |
| 64 | </dd> | |
| 65 | </dl> | |
| 66 | ||
| 67 | The trace IR metadata to data object association is: | |
| 68 | ||
| 69 | <table> | |
| 70 | <tr> | |
| 71 | <th>Metadata object | |
| 72 | <th>Data object | |
| 73 | <tr> | |
| 74 | <td>\bt_c_clock_cls | |
| 75 | <td>Stream clock (see \ref api-tir-cs) | |
| 76 | <tr> | |
| 77 | <td>\bt_c_ev_cls | |
| 78 | <td>\bt_c_ev | |
| 79 | <tr> | |
| 80 | <td>\bt_c_fc | |
| 81 | <td>\bt_c_field | |
| 82 | <tr> | |
| 83 | <td>\bt_c_stream_cls | |
| 84 | <td>\bt_c_stream | |
| 85 | <tr> | |
| 86 | <td>\bt_c_trace_cls | |
| 87 | <td>\bt_c_trace | |
| 88 | </table> | |
| 89 | ||
| 90 | Within a trace processing \bt_graph, \bt_p_msg carry data objects from | |
| 91 | \bt_comp to component. | |
| 92 | ||
| 93 | You need to create metadata objects \em before you create data objects. | |
| 94 | You can then use the data objects to create messages. | |
| 95 | ||
| 96 | For example, you need a \bt_stream_cls to create a \bt_stream. With | |
| 97 | a \bt_stream, you can create a \bt_p_sb_msg, \bt_p_se_msg, \bt_p_ev_msg, | |
| 98 | and other types of messages. | |
| 99 | ||
| 100 | Usually, when you create a data object from a metadata object, the | |
| 101 | metadata object becomes \ref api-fund-freezing "frozen": you cannot | |
| 102 | modify it for the rest of its lifetime. | |
| 103 | ||
| 104 | All metadata objects and some data objects have an optional <em>user | |
| 105 | attributes</em> property (a \bt_map_val): you can use it to attach | |
| 106 | custom attributes, without any semantics specified by the \bt_name | |
| 107 | project, to those objects. | |
| 108 | */ |