| 1 |
= How barectf works |
| 2 |
|
| 3 |
barectf generates a CTF metadata stream and C{nbsp}source files |
| 4 |
from a xref:yaml:index.adoc[**configuration**]. |
| 5 |
|
| 6 |
A barectf configuration specifies a xref:yaml:trace-type-obj.adoc[trace |
| 7 |
type], xref:yaml:clk-type-obj.adoc[clock types], |
| 8 |
xref:yaml:dst-obj.adoc[data stream types], xref:yaml:ert-obj.adoc[event |
| 9 |
record types], and other options to generate the files. |
| 10 |
|
| 11 |
With the `barectf` https://pypi.org/project/barectf/[Python package], |
| 12 |
you build the barectf configuration programatically by assembling |
| 13 |
configuration objects. This documentation is _not_ about the Python |
| 14 |
package. |
| 15 |
|
| 16 |
The xref:cli:index.adoc[`barectf` CLI tool] can read a |
| 17 |
xref:yaml:index.adoc[YAML configuration file] and generate files out of |
| 18 |
it. |
| 19 |
|
| 20 |
[[generated-files]] |
| 21 |
== Generated files |
| 22 |
|
| 23 |
barectf generates the following files from a configuration: |
| 24 |
|
| 25 |
[%autowidth.stretch, cols="d,a"] |
| 26 |
|=== |
| 27 |
|File name |Description |
| 28 |
|
| 29 |
|[[metadata]]`metadata` |
| 30 |
|The CTF metadata stream file. |
| 31 |
|
| 32 |
You'll need to place this file in a directory with the |
| 33 |
xref:how-barectf-works:ctf-primer.adoc#ds[data stream] files which your |
| 34 |
application will write through the generated tracer. |
| 35 |
|
| 36 |
See xref:how-barectf-works:index.adoc[] to learn more. |
| 37 |
|
| 38 |
|[[barectf.h]]`barectf.h` |
| 39 |
|The generated tracer's public C{nbsp}header file. |
| 40 |
|
| 41 |
This header contains the prototypes of the packet opening, packet |
| 42 |
closing, and xref:tracing-funcs:index.adoc[tracing functions]. |
| 43 |
|
| 44 |
barectf generates one packet opening/closing function per configured |
| 45 |
xref:yaml:dst-obj.adoc[data stream type] and one tracing function per |
| 46 |
configured xref:yaml:ert-obj.adoc[event record type]. |
| 47 |
|
| 48 |
Your application and xref:platform:index.adoc[platforms] need to |
| 49 |
include this file. |
| 50 |
|
| 51 |
|`barectf-bitfield.h` |
| 52 |
|Internal macros for the generated tracer (included by `barectf.c`). |
| 53 |
|
| 54 |
|[[barectf.c]]`barectf.c` |
| 55 |
|The generated tracer's C{nbsp}source code. |
| 56 |
|=== |
| 57 |
|
| 58 |
Those file names assume that the configuration uses the default |
| 59 |
xref:yaml:cfg-obj.adoc#prefix-prop[prefixes]. |
| 60 |
|
| 61 |
All C{nbsp}files are written in ANSI{nbsp}C. |
| 62 |
|
| 63 |
[[ctf-data-stream-file-creation]] |
| 64 |
== CTF data stream file creation |
| 65 |
|
| 66 |
Your application calls the xref:tracing-funcs:index.adoc[tracing |
| 67 |
functions] found in <<barectf.h,`barectf.h`>> to write |
| 68 |
xref:ctf-primer.adoc#er[event records] to CTF |
| 69 |
xref:ctf-primer.adoc#ds[data streams] of |
| 70 |
xref:ctf-primer.adoc#pkt[packets]. Those CTF data streams and the |
| 71 |
generated <<metadata,CTF metadata stream>> form a complete |
| 72 |
xref:ctf-primer.adoc#trace[CTF trace]. |
| 73 |
|
| 74 |
How exactly the event timestamps are sourced and the CTF packets are |
| 75 |
appended to some file or memory buffer is controlled by the |
| 76 |
xref:platform:index.adoc[**platform**]. |
| 77 |
|
| 78 |
== Data flow |
| 79 |
|
| 80 |
The typical data flow with barectf is: |
| 81 |
|
| 82 |
[.width-80] |
| 83 |
image::barectf-data-flow.svg[] |
| 84 |
|
| 85 |
. barectf reads your xref:yaml:index.adoc[YAML configuration file]. |
| 86 |
|
| 87 |
. barectf <<generated-files,generates>> the CTF metadata stream file. |
| 88 |
|
| 89 |
. barectf also generates the tracer's C{nbsp}files. |
| 90 |
|
| 91 |
. After adding calls to the generated tracing functions in your |
| 92 |
application code, you pass your application's C{nbsp}source file(s), |
| 93 |
xref:platform:index.adoc[platform] |
| 94 |
C{nbsp}source files, and the generated tracer's C{nbsp}source file to |
| 95 |
a xref:build:index.adoc[C{nbsp}compiler to create your final |
| 96 |
application]. |
| 97 |
|
| 98 |
. Your application <<ctf-data-stream-file-creation,creates CTF data |
| 99 |
stream files>> during its execution. |
| 100 |
+ |
| 101 |
Those data stream files and the metadata stream file of step{nbsp}2 form |
| 102 |
a complete xref:ctf-primer.adoc#trace[CTF trace]. |