docs/modules/how-barectf-works/pages/index.adoc

   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 The specifics of how the event timestamps are sampled and how the CTF
  75 packets are appended to some file (or memory buffer) is controlled by
  76 the 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].