3 **barectf** is a command-line utility which generates pure C99
4 code that is able to write native [Common Trace Format](http://diamon.org/ctf)
7 You will find barectf interesting if:
9 1. You need to trace an application.
10 2. You need tracing to be efficient, yet flexible:
11 record integers of custom sizes, custom floating point numbers,
12 enumerations supported by a specific integer type, and
13 null-terminated UTF-8/ASCII strings (C strings).
14 3. You need to be able to convert the recorded binary events to
15 human-readable text, as well as analyze them with Python scripts
16 ([Babeltrace](http://www.efficios.com/babeltrace) does all that,
18 4. You _cannot_ use [LTTng](http://lttng.org/), an efficient tracing
19 framework for the Linux kernel and Linux/BSD user applications, which
22 The target audience of barectf is developers who need to trace bare metal
23 systems (without an operating system). The code produced by barectf
24 is pure C99 and can be lightweight enough to fit on a tiny microcontroller.
28 * Single input: easy-to-write [YAML](https://en.wikipedia.org/wiki/YAML)
29 configuration file (documentation below)
30 * 1-to-1 mapping from tracing function parameters to event fields
31 * Custom and bundled _platforms_ hiding the details of opening/closing
32 packets and writing them to a back-end (continuous tracing), getting
33 the clock values, etc.:
34 * _linux-fs_: basic Linux application tracing writing stream files to
35 the file system for demonstration purposes
36 * _parallella_: Adapteva Epiphany/[Parallella](http://parallella.org/)
37 with host-side consumer
38 * CTF metadata generated by the command-line tool (automatic trace UUID,
39 stream IDs, and event IDs)
40 * All basic CTF types are supported: integers, floating point numbers,
41 enumerations, and null-terminated strings (C strings)
42 * Binary streams produced by the generated C code and metadata file
43 produced by barectf are CTF 1.8-compliant
44 * Human-readable error reporting
46 **Current limitations**:
50 * All the generated tracing C functions, for a given barectf
51 stream-specific context, need to be called from the same thread, and cannot
52 be called from an interrupt handler, unless a user-provided
53 synchronization mechanism is used.
54 * CTF compound types (array, sequence, structure, variant) are not supported
55 yet, except at some very specific locations in the metadata.
57 barectf is written in Python 3.
62 Make sure you have Python 3 and `pip` for Python 3 installed, then
65 Note that you may pass the `--user` argument to
66 `pip install` to install the tool in your home directory (instead of
71 sudo apt-get install python3-pip
72 sudo pip3 install barectf
74 **Ubuntu 12.04 and lower**:
76 sudo apt-get install python3-setuptools
77 sudo easy_install3 pip
78 sudo pip3 install barectf
82 sudo apt-get install python3-pip
83 sudo pip3 install barectf
87 sudo yum install python3-pip
88 sudo pip3 install barectf
92 sudo install python-pip
93 sudo pip install barectf
97 With [Homebrew](http://brew.sh/):
105 See the [CTF in a nutshell](http://diamon.org/ctf/#ctf-in-a-nutshell)
106 section of CTF's website to understand the basics of this
109 The most important thing to understand about CTF, for barectf use
110 cases, is the layout of a binary stream packet:
112 * Packet header (defined at the trace level)
113 * Packet context (defined at the stream level)
114 * Sequence of events (defined at the stream level):
115 * Event header (defined at the stream level)
116 * Stream event context (defined at the stream level)
117 * Event context (defined at the event level)
118 * Event payload (defined at the event level)
120 The following diagram, stolen without remorse from CTF's website, shows
123 ![](http://diamon.org/ctf/img/ctf-stream-packet.png)
125 Any of those six dynamic scopes, if defined at all, has an associated
126 CTF type. barectf requires them to be structure types.
131 Using barectf involves the following steps:
133 1. Writing the YAML configuration file defining the various header,
134 context, and event field types.
135 2. Running the `barectf` command-line tool with this configuration file
136 to generate the CTF metadata and C files.
137 3. Using the generated C code (tracing functions), along with the C code
138 provided by the appropriate barectf platform, in the source code of
139 your own application.
140 4. Running your application, along with anything the barectf platform
141 you chose requires, to generate the binary streams of a CTF trace.
143 Your application, when running, will generate CTF packets. Depending
144 on the chosen barectf platform, those packets will be consumed and
145 sequentially written at some place for later viewing/analysis.
147 Here's a diagram summarizing the steps described above:
149 ![](http://0x3b.org/ss/cardiectasis400.png)
151 The following subsections explain the four steps above.
153 Also, have a look at the [`doc/examples`](doc/examples) directory, which
154 contains complete examples.
157 ### Writing the YAML configuration file
159 The barectf [YAML](https://en.wikipedia.org/wiki/YAML) configuration file
160 is the only input the `barectf` command-line tool needs in order to generate
161 the corresponding CTF metadata and C files.
163 To start with a concrete configuration, here's some minimal configuration:
191 The `version` property must be set to the `2.0` _string_ (hence the single
192 quotes). As features are added to barectf and to its configuration file schema,
193 this version will be bumped accordingly.
195 The `metadata` property is where the properties and layout of the
196 eventual CTF trace are defined. The accepted properties of each object
197 are documented later in this document. For the moment, note simply
198 that the native byte order of the trace is set to `le` (little-endian),
199 and that there's one defined stream named `my_stream`, having one
200 defined event named `my_event`, having a structure as its payload
201 type, with a single 8-bit unsigned integer type field named `my_field`. Also,
202 the stream packet context type is a structure defining the mandatory
203 `packet_size` and `content_size` special fields as 16-bit unsigned integer
206 Running `barectf` with the configuration above (as a file named `config.yaml`):
210 will produce a C file (`barectf.c`), and its header file (`barectf.h`),
211 the latter declaring the following function:
214 void barectf_my_stream_trace_my_event(
215 struct barectf_my_stream_ctx *ctx, uint8_t ep_my_field);
218 `ctx` is the barectf context for the stream named `my_stream` (usually
219 initialized and provided by the barectf platform), and `ep_my_field` is the
220 value of the `my_event` event payload's `my_field` field.
222 The following subsections define all the objects of the YAML configuration
226 #### Configuration object
228 The top-level object of the YAML configuration file.
232 | Property | Type | Description | Required? | Default value |
233 |---|---|---|---|---|
234 | `version` | String | Must be set to `'2.0'` | Required | N/A |
235 | `prefix` | String | Prefix to be used for function names, file names, etc. | Optional | `barectf_` |
236 | `metadata` | [Metadata object](#metadata-object) | Trace metadata | Required | N/A |
238 The `prefix` property must be set to a valid C identifier. It can be
239 overridden by the `barectf` command-line tool's `--prefix` option.
273 A metadata object defines the desired layout of the CTF trace to be
274 produced by the generated C code. It is used by barectf to generate C code,
275 as well as a corresponding CTF metadata file.
279 | Property | Type | Description | Required? | Default value |
280 |---|---|---|---|---|
281 | `type-aliases` | Associative array of strings (alias names) to [type objects](#type-objects) or strings (previous alias names) | Type aliases to be used in trace, stream, and event objects | Optional | `{}` |
282 | `log-levels` | Associative array of strings (log level names) to log level constant integers | Log levels to be used in event objects | Optional | `{}` |
283 | `clocks` | Associative array of strings (clock names) to [clock objects](#clock-object) | Trace clocks | Optional | `{}` |
284 | `env` | Associative array of strings (names) to strings or integers (values) | Trace environment variables | Optional | `{}` |
285 | `trace` | [Trace object](#trace-object) | Metadata common to the whole trace | Required | N/A |
286 | `streams` | Associative array of strings (stream names) to [stream objects](#stream-object) | Trace streams | Required | N/A |
288 Each clock name of the `clocks` property must be a valid C identifier.
290 The `streams` property must contain at least one entry. Each stream name must be
291 a valid C identifier.
293 Each environment variable name in the `env` property must be a valid
294 C identifier. Those variables will be appended to some environment
295 variables set by barectf itself.
297 The order of the `type-aliases` entries is important: a type alias may only
298 inherit from another type alias if the latter is defined before.
340 return-ctype: uint64_t
342 my_system_version: '0.3.2-2015.03'
359 timestamp_begin: clock-int
360 timestamp_end: clock-int
364 events_discarded: uint32
393 | Property | Type | Description | Required? | Default value |
394 |---|---|---|---|---|
395 | `freq` | Integer (positive) | Frequency (Hz) | Optional | 1000000000 |
396 | `description` | String | Description | Optional | No description |
397 | `uuid` | String (UUID canonical format) | UUID (unique identifier of this clock) | Optional | No UUID |
398 | `error-cycles` | Integer (zero or positive) | Error (uncertainty) of clock in clock cycles | Optional | 0 |
399 | `offset` | [Clock offset object](#clock-offset-object) | Offset | Optional | Default clock offset object |
400 | `absolute` | Boolean | Absolute clock | Optional | `false` |
401 | `return-ctype` | String | Return C type of the associated clock callback | Optional | `uint32_t` |
403 The `return-ctype` property must be set to a valid C integer type
404 (or valid type definition). This is not currently validated by barectf
405 itself, but the C compiler will fail to compile the generated C code
406 if the clock's return type is not a valid C integer type.
412 description: CCLK/A2 (System clock, A2 clock domain)
413 uuid: 184883f6-6b6e-4bfd-bcf7-1e45c055c56a
419 return-ctype: unsigned long long
423 ##### Clock offset object
425 An offset in seconds and clock cycles from the Unix epoch.
429 | Property | Type | Description | Required? | Default value |
430 |---|---|---|---|---|
431 | `seconds` | Integer (zero or positive) | Seconds since the Unix epoch | Optional | 0 |
432 | `cycles` | Integer (zero or positive) | Clock cycles since the Unix epoch plus the value of the `seconds` property | Optional | 0 |
444 Metadata common to the whole trace.
448 | Property | Type | Description | Required? | Default value |
449 |---|---|---|---|---|
450 | `byte-order` | String | Native byte order (`le` for little-endian or `be` for big-endian) | Required | N/A |
451 | `uuid` | String (UUID canonical format or `auto`) | UUID (unique identifier of this trace); automatically generated if value is `auto` | Optional | No UUID |
452 | `packet-header-type` | [Type object](#type-objects) or string (alias name) | Type of packet header (must be a [structure type object](#structure-type-object)) | Optional | No packet header |
454 Each field of the packet header structure type (`packet-header-type` property)
455 corresponds to one parameter
456 of the generated packet opening function (prefixed with `tph_`), except for the
457 following special fields, which are automatically written if present:
459 * `magic` (32-bit unsigned [integer type object](#integer-type-object)):
461 * `uuid` ([array type object](#array-type-object) of 8-bit unsigned
462 [integer type objects](#integer-type-object), of length 16):
463 trace UUID (`uuid` property of trace object must be set)
464 * `stream_id` (unsigned [integer type object](#integer-type-object)):
467 As per CTF 1.8, the `stream_id` field is mandatory if there's more
468 than one defined stream.
493 | Property | Type | Description | Required? | Default value |
494 |---|---|---|---|---|
495 | `packet-context-type` | [Type object](#type-objects) or string (alias name) | Type of packet context (must be a [structure type object](#structure-type-object)) | Required | N/A |
496 | `event-header-type` | [Type object]((#type-objects)) or string (alias name) | Type of event header (must be a [structure type object](#structure-type-object)) | Optional | No event header |
497 | `event-context-type` | [Type object]((#type-objects)) or string (alias name) | Type of stream event context (must be a [structure type object](#structure-type-object)) | Optional | No stream event context |
498 | `events` | Associative array of event names (string) to [event objects](#event-object) | Stream events | Required | N/A |
500 Each field of the packet context structure type (`packet-context-type` property)
501 corresponds to one parameter
502 of the generated packet opening function (prefixed with `spc_`), except for the
503 following special fields, which are automatically written if present:
505 * `timestamp_begin` and `timestamp_end` (unsigned
506 [integer type objects](#integer-type-object), with
507 a clock value property mapping): resp. open and close timestamps
508 * `packet_size` (unsigned [integer type object](#integer-type-object),
509 mandatory): packet size
510 * `content_size` (unsigned [integer type object](#integer-type-object),
511 mandatory): content size
512 * `events_discarded` (unsigned [integer type object](#integer-type-object)):
513 number of discarded events so far
515 The `timestamp_end` field must exist if the `timestamp_begin` field exists,
518 Each field of the event header structure type (`event-header-type` property)
519 corresponds to one parameter of the generated tracing function
520 (prefixed with `eh_`) (for a given event), except for the following special
521 fields, which are automatically written if present:
523 * `id` (unsigned [integer type object](#integer-type-object)): event ID
524 * `timestamp` (unsigned [integer type object](#integer-type-object), with
525 a clock value property mapping): event timestamp
527 The `id` field must exist if there's more than one defined event in the
530 Each field of the stream event context structure type (`event-context-type`
531 property) corresponds to one parameter of the generated tracing function
532 (prefixed with `seh_`) (for a given event).
534 Each field name of the `packet-context-type`, `event-header-type`,
535 and `event-context-type` properties must be a valid C identifier.
537 The `events` property must contain at least one entry.
545 timestamp_begin: clock-int
546 timestamp_end: clock-int
549 events_discarded: uint16
550 my_custom_field: int12
562 payload-type: msg-type
572 | Property | Type | Description | Required? | Default value |
573 |---|---|---|---|---|
574 | `log-level` | String (predefined log level name) or integer (zero or positive) | Log level of this event | Optional | No log level |
575 | `context-type` | [Type object](#type-objects) or string (alias name) | Type of event context (must be a [structure type object](#structure-type-object)) | Optional | No event context |
576 | `payload-type` | [Type object](#type-objects) or string (alias name) | Type of event payload (must be a [structure type object](#structure-type-object)) | Required | N/A |
578 Available log level names, for a given event, are defined by the
579 `log-levels` property of the [metadata object](#metadata-object)
582 Each field of the event context structure type (`context-type` property)
583 corresponds to one parameter
584 of the generated tracing function (prefixed with `ec_`).
586 Each field of the event payload structure type (`payload-type` property)
587 corresponds to one parameter
588 of the generated tracing function (prefixed with `ep_`). The event
589 payload structure type must contain at least one field.
591 Each field name of the `context-type` and `payload-type` properties must be a
615 Type objects represent CTF types.
617 **Common properties**:
619 | Property | Type | Description | Required? | Default value |
620 |---|---|---|---|---|
621 | `class` | String | Type class | Required if `inherit` property is absent | N/A |
622 | `inherit` | String | Name of type alias from which to inherit properties | Required if `class` property is absent | N/A |
624 The accepted values for the `class` property are:
626 | `class` property value | CTF type |
628 | `int`<br>`integer` | Integer type |
629 | `flt`<br>`float`<br>`floating-point` | Floating point number type |
630 | `enum`<br>`enumeration` | Enumeration type |
631 | `str`<br>`string` | String type |
632 | `struct`<br>`structure` | Structure type |
633 | `array` | Array/sequence types |
634 | `var`<br>`variant` | Variant type |
636 The `inherit` property accepts the name of any previously defined
637 type alias. Any propery in a type object that inherits from another
638 type object overrides the parent properties as follows:
640 * Booleans, numbers, and strings: value of parent property with
641 the same name is replaced
642 * Arrays: new elements are appended to parent array
643 * Associative arrays: properties sharing the name of parent
644 properties completely replace them; new properties are
645 added to the parent associative array
648 ##### Integer type object
654 | Property | Type | Description | Required? | Default value |
655 |---|---|---|---|---|
656 | `size` | Integer (positive) | Size (bits) (1 to 64) | Required | N/A |
657 | `align` | Integer (positive) | Alignment (bits) (power of two) | Optional | 8 if `size` property is a multiple of 8, else 1 |
658 | `signed` | Boolean | Signedness | Optional | `false` (unsigned) |
659 | `base` | Integer | Display radix (2, 8, 10, or 16) | Optional | 10 |
660 | `byte-order` | String | Byte order (`le` for little-endian, `be` for big-endian, or `native` to use the byte order defined at the trace level) | Optional | `native` |
661 | `property-mappings` | Array of [property mapping objects](#property-mapping-object) | Property mappings of this integer type | Optional | N/A |
663 The `property-mappings` array property currently accepts only one element.
679 **Equivalent C type**:
681 * Unsigned: `uint8_t`, `uint16_t`, `uint32_t`, or `uint64_t`, depending on the
683 * Signed: `int8_t`, `int16_t`, `int32_t`, or `int64_t`, depending on the
687 ###### Property mapping object
689 A property mapping object associates an integer type with a stateful
690 object's property. When the integer type is decoded from a CTF binary
691 stream, the associated object's property is updated.
693 Currently, the only available stateful object's property is the
694 current value of a given clock.
698 | Property | Type | Description | Required? | Default value |
699 |---|---|---|---|---|
700 | `type` | String | Object type (always `clock`) | Required | N/A |
701 | `name` | String | Clock name | Required | N/A |
702 | `property` | String | Clock property name (always `value`) | Required | N/A |
713 ##### Floating point number type object
715 A CTF floating point number type.
719 | Property | Type | Description | Required? | Default value |
720 |---|---|---|---|---|
721 | `size` | [Floating point number type size object](#floating-point-number-type-size-object) | Size parameters | Required | N/A |
722 | `align` | Integer (positive) | Alignment (bits) (power of two) | Optional | 8 |
723 | `byte-order` | String | Byte order (`le` for little-endian, `be` for big-endian, or `native` to use the byte order defined at the trace level) | Optional | `native` |
736 **Equivalent C type**:
738 * 8-bit exponent, 24-bit mantissa, 32-bit alignment: `float`
739 * 11-bit exponent, 53-bit mantissa, 64-bit alignment: `double`
740 * Every other combination: `uint64_t`
743 ###### Floating point number type size object
745 The CTF floating point number type is encoded, in a binary stream,
746 following [IEEE 754-2008](https://en.wikipedia.org/wiki/IEEE_floating_point)'s
747 interchange format. The required parameters are the exponent and
748 significand sizes, in bits. In CTF, the _mantissa_ size includes the
749 sign bit, whereas IEEE 754-2008's significand size does not include it.
753 | Property | Type | Description | Required? | Default value |
754 |---|---|---|---|---|
755 | `exp` | Integer (positive) | Exponent size (bits) | Required | N/A |
756 | `mant` | Integer (positive) | Mantissa size (significand size + 1) (bits) | Required | N/A |
758 As per IEEE 754-2008, the sum of the `exp` and `mant` properties must be a
761 The sum of the `exp` and `mant` properties must be lesser than or equal to 64.
771 ##### Enumeration type object
773 A CTF enumeration type.
775 Each label of an enumeration type is mapped to a single value, or to a
780 | Property | Type | Description | Required? | Default value |
781 |---|---|---|---|---|
782 | `value-type` | [Integer type object](#integer-type-object) or string (alias name) | Supporting integer type | Required | N/A |
783 | `members` | Array of [enumeration type member objects](#enumeration-type-member-object) | Enumeration members | Required | N/A |
785 The `members` property must contain at least one element. If the member
786 is a string, its associated value is computed as follows:
788 * If the member is the first one of the `members` array, its value
790 * If the previous member is a string, its value is the previous
791 member's computed value + 1.
792 * If the previous member is a single value member, its value is
793 the previous member's value + 1.
794 * If the previous member is a range member, its value is the previous
795 member's upper bound + 1.
797 The member values must not overlap each other.
811 - label: TWENTY TO FOURTY
816 **Equivalent C type**: equivalent C type of supporting integer type
817 (see [integer type object documentation](#integer-type-object) above).
820 ###### Enumeration type member object
822 The member of a CTF enumeration type.
824 If it's a string, the string is the member's label, and the members's
825 value depends on the last member's value (see explanation in
826 [enumeration type object documentation](#enumeration-type-object) above).
828 Otherwise, it's a complete member object, with the following properties:
830 | Property | Type | Description | Required? | Default value |
831 |---|---|---|---|---|
832 | `label` | String | Member's label | Required | N/A |
833 | `value` | Integer (single value) or array of two integers (range value) | Member's value | Required | N/A |
835 If the `value` property is an array of two integers, the member's label is
836 associated to this range, both lower and upper bounds included. The array's
837 first element must be lesser than or equal to the second element.
847 ##### String type object
849 A CTF null-terminated string type.
851 This object has no properties.
859 **Equivalent C type**: `const char *`.
862 ##### Array type object
864 A CTF array or sequence (variable-length array) type.
868 | Property | Type | Description | Required? | Default value |
869 |---|---|---|---|---|
870 | `element-type` | [Type object](#type-objects) or string (alias name) | Type of array's elements | Required | N/A |
871 | `length` | Positive integer (static array) or string (variable-length array) | Array type's length | Required | N/A |
873 If the `length` property is a string, the array type has a
874 variable length (CTF sequence). In this case, the property's value
875 refers to a previous structure field. The `length` property's value
876 may be prefixed with one of the following strings to indicate an
877 absolute lookup within a previous (or current) dynamic scope:
879 * `trace.packet.header.`: trace packet header
880 * `stream.packet.context.`: stream packet context
881 * `stream.event.header.`: stream event header
882 * `stream.event.context.`: stream event context
883 * `event.context.`: event context
884 * `event.payload.`: event payload
886 The pointed field must have an unsigned integer type.
888 **Example** (16 bytes):
898 **Example** (variable-length array of null-terminated strings):
902 length: previous_field
908 ##### Structure type object
910 A CTF structure type, i.e. a list of fields, each field
911 having a name and a CTF type.
915 | Property | Type | Description | Required? | Default value |
916 |---|---|---|---|---|
917 | `min-align` | Integer (positive) | Minimum alignment (bits) (power of two) | Optional | 1 |
918 | `fields` | Associative array of field names (string) to [type objects](#type-objects) or strings (alias names) | Structure type's fields | Optional | `{}` |
920 The order of the entries in the `fields` property is important; it is in
921 this order that the fields are serialized in binary streams.
937 ##### Variant type object
939 A CTF variant type, i.e. a tagged union of CTF types.
943 | Property | Type | Description | Required? | Default value |
944 |---|---|---|---|---|
945 | `tag` | String | Variant type's tag | Required | N/A |
946 | `types` | Associative array of strings to [type objects](#type-objects) or strings (alias names) | Possible types | Required | N/A |
948 The `tag` property's value refers to a previous structure field.
949 The value may be prefixed with one of the following strings to indicate
950 an absolute lookup within a previous (or current) dynamic scope:
952 * `trace.packet.header.`: trace packet header
953 * `stream.packet.context.`: stream packet context
954 * `stream.event.header.`: stream event header
955 * `stream.event.context.`: stream event context
956 * `event.context.`: event context
957 * `event.payload.`: event payload
959 The pointed field must have an enumeration type. Each type name in the
960 `types` property must have its equivalent member's label in this
961 enumeration type. This is how a variant's type is selected using the
982 ### Running the `barectf` command
984 Using the `barectf` command-line utility is easy. In its simplest form,
985 it outputs a CTF metadata file and a few C files out of a
986 YAML configuration file:
990 will output, in the current working directory:
992 * `metadata`: CTF metadata file
993 * `barectf-bitfield.h`: macros used by tracing functions to pack bits
994 * `barectf.h`: other macros and prototypes of context/tracing functions
995 * `barectf.c`: context/tracing functions
997 `barectf_` is the default name of the files and the default prefix of
998 barectf C functions and structures. The prefix is read from the
999 configuration file (see the
1000 [configuration object documentation](#configuration-object)), but
1001 you may override it on the command line:
1003 barectf --prefix my_app_ config.yaml
1005 You may also output the files elsewhere:
1007 barectf --code-dir src --headers-dir include --metadata-dir ctf config.yaml
1010 ### Using the generated C code
1012 This section assumes you ran `barectf` with no options:
1016 The command generates C structures and functions to initialize
1017 barectf contexts, open packets, and close packets. It also generates as many
1018 tracing functions as there are events defined in the YAML configuration
1021 An application should never have to initialize barectf contexts,
1022 open packets, or close packets; this is the purpose of a specific barectf
1023 platform, which wraps those calls in its own initialization and
1024 finalization functions.
1026 The barectf project provides a few platforms in the [`platforms`](platforms)
1027 directory. Each one contains a `README.md` file explaining how to use
1028 the platform. If you're planning to write your own platform,
1029 read the next subsection. Otherwise, skip it.
1032 #### Writing a barectf platform
1034 A **_barectf platform_** is responsible for:
1036 1. Providing some initialization and finalization functions
1037 for the tracing infrastructure of the target. The initialization
1038 function is responsible for initializing a barectf context,
1039 providing the platform callback functions, and for opening the very
1040 first stream packet(s). The finalization function is responsible
1041 for closing, usually when not empty, the very last stream
1043 2. Implementing the platform callback functions to accomodate the target
1044 system. The main purposes of those callback functions are:
1045 * Getting the current value of clock(s).
1046 * Doing something with a packet once it's full. This is how
1047 a ring buffer of packets may be implemented. The platform
1048 may also be naive and write the full packets to the file system
1051 Thus, the traced application itself should never have to call
1052 the barectf initialization, packet opening, and packet closing
1053 funcions. The application only deals with initializing/finalizing
1054 the platform, and calling the tracing functions.
1056 The following diagram shows how each part connects with
1059 ![](http://0x3b.org/ss/placoderm625.png)
1061 The following subsections explain what should exist in each
1065 ##### Platform initialization function
1067 A barectf platform initialization function is responsible for
1068 initializing barectf context(s) (calling `barectf_init()`,
1069 where `barectf_` is the configured prefix), and opening the very
1070 first packet (calling `barectf_stream_open_packet()` with
1071 target-specific parameters, for each stream, where `stream` is
1074 barectf generates one context C structure for each defined stream.
1075 They all contain the same first member, a structure with common
1078 barectf generates a single context initialization function:
1085 struct barectf_platform_callbacks cbs,
1090 This function must be called with each stream-specific context
1091 structure to be used afterwards. The parameters are:
1093 * `ctx`: stream-specific barectf context (allocated by caller)
1094 * `buf`: buffer to use for this stream's packet (allocated by caller)
1095 * `buf_size`: size of `buf` in bytes
1096 * `cbs`: platform callback functions to be used with this
1097 stream-specific context
1098 * `data`: user data passed to platform callback functions (`cbs`)
1105 void platform_init(/* ... */)
1107 struct barectf_my_stream_ctx *ctx;
1109 struct my_data *my_data;
1110 struct barectf_platform_callbacks cbs = {
1114 ctx = platform_alloc(sizeof(*ctx));
1115 buf = platform_alloc(BUF_SZ);
1116 my_data = platform_alloc(sizeof(*my_data));
1118 barectf_init(ctx, buf, BUF_SZ, cbs, my_data);
1124 barectf generates one packet opening and one packet closing
1125 function per defined stream, since each stream may have custom
1126 parameters at the packet opening time, and custom offsets of
1127 fields to write at packet closing time.
1129 The platform initialization should open the very first packet
1130 of each stream to use because the tracing functions expect the
1131 current packet to be opened.
1133 Here's an example of a packet opening function prototype:
1136 void barectf_my_stream_open_packet(
1137 struct barectf_my_stream_ctx *ctx,
1142 The function needs the stream-specific barectf context, as well as any
1143 custom trace packet header or stream packet context field; in this
1144 last example, `something` is a floating point number stream packet context
1148 ##### barectf packet information API
1150 There's a small API to query stuff about the current packet of a
1151 given barectf context:
1154 uint32_t barectf_packet_size(void *ctx);
1155 int barectf_packet_is_full(void *ctx);
1156 int barectf_packet_is_empty(void *ctx);
1157 uint32_t barectf_packet_events_discarded(void *ctx);
1158 uint8_t *barectf_packet_buf(void *ctx);
1159 void barectf_packet_set_buf(void *ctx, uint8_t *buf, uint32_t buf_size);
1160 uint32_t barectf_packet_buf_size(void *ctx);
1161 int barectf_packet_is_open(void *ctx);
1164 `barectf_packet_is_full()` returns 1 if the context's current packet
1165 is full (no space left for any event), 0 otherwise.
1167 `barectf_packet_is_empty()` returns 1 if the context's current packet
1168 is empty (no recorded events), 0 otherwise.
1170 `barectf_packet_events_discarded()` returns the number of lost (discarded)
1171 events _so far_ for a given stream.
1173 The buffer size (`buf_size` parameter of `barectf_packet_set_buf()` and
1174 return value of `barectf_packet_buf_size()`) is always a number of bytes.
1176 `barectf_packet_is_open()` returns 1 if the context's current packet
1177 is open (the packet opening function was called with this context).
1180 ##### Platform callback functions
1182 The callback functions to implement for a given platform are
1183 in the generated `barectf_platform_callbacks` C structure. This
1184 structure will contain:
1186 * One callback function per defined clock, using the clock's
1187 return C type. Those functions must return the current clock
1189 * `is_backend_full()`: is the back-end full? If a new packet
1190 is opened now, does it have its reserved space in the back-end?
1191 Return 0 if it does, 1 otherwise.
1192 * `open_packet()`: this callback function **must** call the relevant
1193 packet opening function.
1194 * `close_packet()`: this callback function **must** call the
1195 relevant packet closing function _and_ copy/move the current packet
1198 What exactly is a _back-end_ is left to the platform implementor. It
1199 could be a ring buffer of packets, or it could be dumber: `close_packet()`
1200 always appends the current packet to some medium, and `is_backend_full()`
1201 always returns 0 (back-end is never full).
1203 Typically, if `is_backend_full()` returns 0, then the next
1204 call to `close_packet()` should be able to write the current packet.
1205 If `is_backend_full()` returns 1, there will be lost (discarded)
1206 events. If a stream packet context has an `events_discarded` field,
1207 it will be written to accordingly when a packet is closed.
1209 If a platform needs double buffering, `open_packet()` is the callback
1210 function where packet buffers would be swapped (before calling
1211 the barectf packet opening function).
1214 ##### Platform finalization function
1216 The platform finalization function should be called by the application
1217 when tracing is no more required. It is responsible for closing the
1218 very last packet of each stream.
1220 Typically, assuming there's only one stream (named `my_stream` in this
1221 example), the finalization function will look like this:
1224 void platform_tracing_finalize(struct platform_data *platform_data)
1226 if (barectf_packet_is_open(platform_data->ctx) &&
1227 !barectf_packet_is_empty(platform_data->ctx)) {
1228 barectf_my_stream_close_packet(platform_data->ctx);
1231 * Do whatever is necessary here to write the packet
1232 * to the platform's back-end.
1238 That is: if the packet is still open (thus not closed and written yet)
1239 _and_ it contains at least one event (not empty), close and write the last
1242 Note, however, that you might be interested in closing an open empty
1243 packet, since its packet context could update the discarded events count
1244 (if there were lost events between the last packet closing time and
1245 now, which is quite possible if the back-end became full after closing
1246 and writing the previous packet).
1249 #### Calling the generated tracing functions
1251 Calling the generated tracing functions is what the traced application
1254 For a given prefix named `barectf`, a given stream named `stream`, and
1255 a given event named `event`, the generated tracing function name is
1256 `barectf_stream_trace_event()`.
1258 The first parameter of a tracing function is always the stream-specific
1259 barectf context. Then, in this order:
1261 * One parameter for each custom event header field
1262 (prefixed with `seh_`)
1263 * One parameter for each custom stream event context field
1264 (prefixed with `sec_`)
1265 * One parameter for each custom event context field
1266 (prefixed with `ec_`)
1267 * One parameter for each custom event payload field
1268 (prefixed with `ep_`)
1270 A tracing function returns nothing: it either succeeds (the event
1271 is serialized in the current packet) or fails when there's no
1272 space left (the context's discarded events count is incremented).
1276 Given the following [event object](#event-object), named `my_event`,
1277 placed in a stream named `default` with no custom event header/stream event
1312 barectf will generate the following tracing function prototype:
1315 /* trace (stream "default", event "my_event") */
1316 void barectf_default_trace_my_event(
1317 struct barectf_default_ctx *ctx,
1329 ### Reading CTF traces
1331 To form a complete CTF trace, the `metadata` file generated by the
1332 `barectf` command-line tool and the binary stream files generated
1333 by the application (or by an external consumer, depending on the
1334 platform) should be placed in the same directory.
1336 To read a CTF trace, use [Babeltrace](http://www.efficios.com/babeltrace).
1337 Babeltrace is packaged by most major distributions as the `babeltrace`
1338 package. Babeltrace ships with a command-line utility that can convert a
1339 CTF trace to human-readable text output. Also, it includes Python bindings
1340 so that you may analyze a CTF trace using a custom script.
1342 In its simplest form, the `babeltrace` command-line converter is quite
1345 babeltrace /path/to/directory/containing/ctf/files
1347 See `babeltrace --help` and `man babeltrace` for more options.