| 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 | */ |