| 1 | /** |
| 2 | @mainpage Welcome! |
| 3 | |
| 4 | Welcome to the |
| 5 | <strong><em>Babeltrace \btversion C API</em></strong> documentation! |
| 6 | |
| 7 | <a href="http://diamon.org/babeltrace">Babeltrace</a> is an open |
| 8 | source converter of |
| 9 | <a href="https://en.wikipedia.org/wiki/Tracing_(software)">trace</a> |
| 10 | formats. You can use its C API to |
| 11 | write custom source, sink, and filter |
| 12 | \link btcomponents component classes\endlink which you can package as user |
| 13 | \link btplugins plugins\endlink. |
| 14 | |
| 15 | |
| 16 | @section intro Introduction |
| 17 | |
| 18 | The goal of using this API is to create user |
| 19 | \link btplugins <em>plugins</em>\endlink. |
| 20 | |
| 21 | A Babeltrace plugin contains one or more |
| 22 | \link btcomponents <em>component classes</em>\endlink. |
| 23 | |
| 24 | A component class is either: |
| 25 | |
| 26 | - A \b source, or producer of trace events. |
| 27 | - A \b sink, or consumer of trace events. |
| 28 | - A \b filter, that is, both a producer and a consumer of trace |
| 29 | events. |
| 30 | |
| 31 | A program or library can instantiate a component class as many times as |
| 32 | needed as concrete \em components. At component instantiation time, the |
| 33 | constructor function receives custom parameters. |
| 34 | |
| 35 | Plugins, as of Babeltrace \btversion, are built as dynamic libraries |
| 36 | (<code>.so</code> or <code>.dll</code> files) and loaded by the \c |
| 37 | babeltrace converter program. The converter program is responsible for |
| 38 | passing notifications and events from source components to filter |
| 39 | components, if any, and from filter components to sink components. |
| 40 | |
| 41 | The internal representations of a trace, a stream, and an event follow |
| 42 | the <a href="http://diamon.org/ctf">Common Trace Format</a> model. |
| 43 | Within the Babeltrace C API, this representation is called the |
| 44 | <em>Common Trace Format Intermediate Representation</em>, or |
| 45 | \link ctfir CTF IR\endlink. |
| 46 | |
| 47 | The CTF IR model contains the following objects, amongst others: |
| 48 | |
| 49 | <ul> |
| 50 | <li> |
| 51 | A \link ctfirfieldtypes field type\endlink is a template for creating |
| 52 | a concrete \link ctfirfields field\endlink. |
| 53 | <p> |
| 54 | For example, an integer field type contains the size (in bits) of the |
| 55 | integer fields it describes, as well as their byte order, whether or not |
| 56 | they are signed, and so on. An integer field created out of an integer |
| 57 | field type, however, only contains a raw integer value. You can create |
| 58 | many fields from a single field type template. |
| 59 | |
| 60 | <li> |
| 61 | An \link ctfireventclass event class\endlink is a template for |
| 62 | creating a concrete \link ctfirevent event\endlink. |
| 63 | <p> |
| 64 | An event class contains the field types of its various scopes, while an |
| 65 | event contains the actual fields holding their values. |
| 66 | |
| 67 | <li> |
| 68 | A \link ctfirstreamclass stream class\endlink is a template for |
| 69 | creating a concrete \link ctfirstream stream\endlink. |
| 70 | <p> |
| 71 | A stream class contains the field types of its various scopes, while |
| 72 | \link ctfirpacket packets\endlink attached to a |
| 73 | \link ctfirstream stream\endlink instantiated from a |
| 74 | stream class contains the actual |
| 75 | fields holding their values. <p> A stream class is the parent of one or |
| 76 | more event classes. |
| 77 | |
| 78 | <li> |
| 79 | A \link ctfirtraceclass trace class\endlink describes traces. |
| 80 | <p> |
| 81 | A trace class is the parent of one or more stream classes. |
| 82 | |
| 83 | <li> |
| 84 | A \link ctfirclockclass clock class\endlink holds the common properties |
| 85 | of clock values that are instantiated in \link ctfirevent events\endlink. |
| 86 | </ul> |
| 87 | |
| 88 | Some parts of the API require typical scalar value objects (boolean, |
| 89 | integer, floating point number, string) and compound value objects |
| 90 | (array, map). For example, the environment of a |
| 91 | \link ctfirtraceclass CTF IR trace class\endlink maps strings to strings |
| 92 | or to integers, and the parameters passed to component instances take |
| 93 | the form of a map. For this purpose, the API uses |
| 94 | \link values value objects\endlink. |
| 95 | |
| 96 | All the <em>Babeltrace objects</em> have a |
| 97 | <a href="https://en.wikipedia.org/wiki/Reference_counting">reference count</a> |
| 98 | to make them shareable. |
| 99 | When you create a Babeltrace object, its reference count is |
| 100 | initialized to 1: you are its sole owner. When you add this object to |
| 101 | another one, the latter takes its own reference using bt_get(), |
| 102 | incrementing the shared object's reference count. When you are done |
| 103 | with an object, you must call bt_put() to drop your reference, |
| 104 | decrementing its reference count. When an object's reference count |
| 105 | reaches 0, the object is considered \em destroyed and cannot be |
| 106 | used anymore. See \ref refs for more details. |
| 107 | |
| 108 | The postconditions of the functions and macros documented here indicate |
| 109 | what you can expect of the reference counts of the Babeltrace objects |
| 110 | passed as parameters and returned. |
| 111 | |
| 112 | The Babeltrace library can \em freeze almost all of the Babeltrace |
| 113 | objects. A frozen object is considered \em immutable, although you can |
| 114 | still get and put references to this object. |
| 115 | |
| 116 | The preconditions of the functions and macros documented here indicate |
| 117 | when they expect unfrozen objects. The postconditions indicate when |
| 118 | the functions and macros freeze an object. |
| 119 | |
| 120 | Have a look at \ref quickstart to learn more about the available |
| 121 | modules of the Babeltrace C API. |
| 122 | */ |