How barectf works

barectf generates a CTF metadata stream and C source files from a configuration.

A barectf configuration specifies a trace type, clock types, data stream types, event record types, and other options to generate the files.

With the barectf Python package, you build the barectf configuration programatically by assembling configuration objects. This documentation is not about the Python package.

The barectf CLI tool can read a YAML configuration file and generate files out of it.

Generated files

barectf generates the following files from a configuration:

File name Description

metadata

The CTF metadata stream file.

You’ll need to place this file in a directory with the data stream files which your application will write through the generated tracer.

See How barectf works to learn more.

barectf.h

The generated tracer’s public C header file.

This header contains the prototypes of the packet opening, packet closing, and tracing functions.

barectf generates one packet opening/closing function per configured data stream type and one tracing function per configured event record type.

Your application and platforms need to include this file.

barectf-bitfield.h

Internal macros for the generated tracer (included by barectf.c).

barectf.c

The generated tracer’s C source code.

Those file names assume that the configuration uses the default prefixes.

All C files are written in ANSI C.

CTF data stream file creation

Your application calls the tracing functions found in barectf.h to write event records to CTF data streams of packets. Those CTF data streams and the generated CTF metadata stream form a complete CTF trace.

How exactly the event timestamps are sourced and the CTF packets are appended to some file or memory buffer is controlled by the platform.

Data flow

The typical data flow with barectf is:

barectf data flow

  1. barectf reads your YAML configuration file.

  2. barectf generates the CTF metadata stream file.

  3. barectf also generates the tracer’s C files.

  4. After adding calls to the generated tracing functions in your application code, you pass your application’s C source file(s), platform C source files, and the generated tracer’s C source file to a C compiler to create your final application.

  5. Your application creates CTF data stream files during its execution.

    Those data stream files and the metadata stream file of step 2 form a complete CTF trace.