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