docs/modules/ROOT/pages/getting-started.adoc

   1 = Getting started
   2
   3 This introductory guide makes you create a very simple barectf YAML
   4 configuration, generate a tracer out of it, and then use it.
   5
   6 You need Linux for this user guide.
   7
   8 The steps are:
   9
  10 . <<yaml,Write the YAML configuration file>>.
  11 . <<cli,Generate the files with the `barectf` CLI tool>>.
  12 . <<app,Write the application source file>>.
  13 . <<build,Download the Linux FS platform source files and
  14   build the application>>.
  15 . <<trace,Execute the application>> to produce
  16   xref:how-barectf-works:ctf-primer.adoc#ds[CTF data streams].
  17 . <<read,Read the resulting CTF trace>>.
  18
  19 IMPORTANT: Make sure that barectf xref:install.adoc[is installed] before
  20 you follow this guide.
  21
  22 [[yaml]]
  23 == Write the YAML configuration file
  24
  25 . Create an empty directory and `cd` into it, for example:
  26 +
  27 [.cl]
  28 [verse]
  29 [.prompt]##$## cd $(mktemp --directory)
  30
  31 . Write the following xref:yaml:index.adoc[YAML configuration file]:
  32 +
  33 [[config.yaml]]
  34 .`config.yaml`
  35 [source,yaml]
  36 ----
  37 # Needed YAML tag for the configuration object
  38 --- !<tag:barectf.org,2020/3/config>
  39
  40 # Configuration's trace
  41 trace:
  42   # Type of the trace
  43   type:
  44     # Add standard field type aliases
  45     $include:
  46       - stdint.yaml
  47       - stdmisc.yaml
  48
  49     # Native byte order is little-endian
  50     native-byte-order: little-endian
  51
  52     # One clock type
  53     clock-types:
  54       # The Linux FS platform requires a clock type named `default`
  55       # which has a 1-GHz frequency and the `uint64_t` C type.
  56       default:
  57         frequency: 1000000000
  58         $c-type: uint64_t
  59
  60     # One data stream type
  61     data-stream-types:
  62       # Stream type named `default`
  63       default:
  64         # Default data stream type
  65         $is-default: true
  66
  67         # Default clock type: `default`
  68         $default-clock-type-name: default
  69
  70         # Two event record types
  71         event-record-types:
  72           # Event record type named `one_integer`
  73           one_integer:
  74             payload-field-type:
  75               class: structure
  76               members:
  77                 # One payload member: a 32-bit signed integer field type
  78                 # (`int32_t` C type)
  79                 - the_integer: int32
  80
  81           # Event record type named `one_string`
  82           one_string:
  83             payload-field-type:
  84               class: structure
  85               members:
  86                 # One payload member: a string field type
  87                 # (`const char *` C type)
  88                 - the_string: string
  89 ----
  90 +
  91 barectf will <<cli,generate>> two
  92 xref:tracing-funcs:index.adoc[tracing functions] named
  93 `+barectf_trace_one_integer()+` and `+barectf_trace_one_string()+` from
  94 this configuration.
  95
  96 [[cli]]
  97 == Generate the files with the `barectf` CLI tool
  98
  99 . Create a directory which will contain the CTF trace:
 100 +
 101 --
 102 [.cl]
 103 [verse]
 104 [.prompt]##$## mkdir trace
 105 --
 106 +
 107 A CTF trace always contains a file named `metadata` and one or more data
 108 stream files. barectf always generates the `metadata` file while the
 109 user application writes the data stream files through the generated
 110 tracer.
 111
 112 . Generate the CTF metadata stream and C{nbsp}source files with the
 113   xref:cli:index.adoc[`barectf` CLI tool]:
 114 +
 115 [.cl]
 116 [verse]
 117 --
 118 [.prompt]##$## barectf generate --metadata-dir=trace config.yaml
 119 --
 120 +
 121 `barectf generate` creates:
 122 +
 123 [%autowidth.stretch, cols="d,a"]
 124 |===
 125 |File name |Description
 126
 127 |`trace/metadata`
 128 |The CTF metadata stream file.
 129
 130 It's in the `trace` directory because we used the
 131 xref:cli:usage.adoc#generate-metadata-dir-option[`+--metadata-dir+`]
 132 option.
 133
 134 |`barectf.h`
 135 |The generated tracer's public C{nbsp}header file.
 136
 137 |`barectf-bitfield.h`
 138 |Internal macros for the generated tracer (included by `barectf.c`).
 139
 140 |`barectf.c`
 141 |The generated tracer's C{nbsp}source code.
 142 |===
 143
 144 [[app]]
 145 == Write the application source file
 146
 147 Write a simple application which uses the generated tracer:
 148
 149 .`app.c`
 150 [source,c]
 151 ----
 152 /* Include the Linux FS platform header */
 153 #include "barectf-platform-linux-fs.h"
 154
 155 /* Include the barectf public header */
 156 #include "barectf.h"
 157
 158 int main(const int argc, const char * const argv[])
 159 {
 160     /* Platform context */
 161     struct barectf_platform_linux_fs_ctx *platform_ctx;
 162
 163     /* barectf context */
 164     struct barectf_default_ctx *ctx;
 165
 166     int i;
 167
 168     /*
 169      * Obtain a platform context.
 170      *
 171      * The platform is configured to write 512-byte packets to a data
 172      * stream file within the `trace` directory.
 173      */
 174     platform_ctx = barectf_platform_linux_fs_init(512, "trace/stream",
 175                                                   0, 0, 0);
 176
 177     /* Obtain the barectf context from the platform context */
 178     ctx = barectf_platform_linux_fs_get_barectf_ctx(platform_ctx);
 179
 180     /*
 181      * Write a `one_integer` event record which contains the number of
 182      * command arguments.
 183      */
 184     barectf_trace_one_integer(ctx, argc);
 185
 186     /* For each command argument */
 187     for (i = 0; i < argc; ++i) {
 188         /*
 189          * Write a `one_integer` event record which contains the
 190          * argument's index.
 191          */
 192         barectf_trace_one_integer(ctx, i);
 193
 194         /*
 195          * Write a `one_string` event record which contains the
 196          * argument.
 197          */
 198         barectf_trace_one_string(ctx, argv[i]);
 199     }
 200
 201     /* Finalize (free) the platform context */
 202     barectf_platform_linux_fs_fini(platform_ctx);
 203
 204     return 0;
 205 }
 206 ----
 207
 208 This application calls the `+barectf_trace_one_integer()+` and
 209 `+barectf_trace_one_string()+` functions which correspond to the
 210 `one_integer` and `one_string` event record types in
 211 <<config.yaml,`config.yaml`>>.
 212
 213 [[build]]
 214 == Download platform source files and build the application
 215
 216 To build the final application, you need the Linux FS platform source
 217 files.
 218
 219 The Linux FS platform only exists to demonstrate barectf; a barectf user
 220 almost always xref:platform:index.adoc[writes its own platform] because
 221 of the bare-metal/embedded nature of the target systems.
 222
 223 . Download the Linux FS platform source files:
 224 +
 225 [.cl]
 226 [verse]
 227 [.prompt]##$## wget https://raw.githubusercontent.com/efficios/barectf/stable-{page-component-version}/platforms/linux-fs/barectf-platform-linux-fs.h
 228 [.prompt]##$## wget https://raw.githubusercontent.com/efficios/barectf/stable-{page-component-version}/platforms/linux-fs/barectf-platform-linux-fs.c
 229
 230 . Build the application:
 231 +
 232 [.cl]
 233 [verse]
 234 [.prompt]##$## gcc -o app app.c barectf.c barectf-platform-linux-fs.c
 235
 236 [[trace]]
 237 == Execute the application
 238
 239 Run the <<build,built>> application, passing a few command-line
 240 arguments:
 241
 242 [.cl]
 243 [verse]
 244 [.prompt]##$## ./app lorem ipsum nulla dolore consequat
 245
 246 This writes the xref:how-barectf-works:ctf-primer.adoc#ds[CTF data
 247 stream] file `trace/stream`.
 248
 249 The `trace` directory is now a complete
 250 xref:how-barectf-works:ctf-primer.adoc#trace[CTF trace].
 251
 252 [[read]]
 253 == Read the CTF trace
 254
 255 Use https://babeltrace.org/[Babeltrace{nbsp}2] to read the resulting
 256 CTF trace:
 257
 258 [.cl]
 259 [verse]
 260 [.prompt]##$## babeltrace2 trace
 261
 262 ----
 263 [15:52:24.202028327] (+?.?????????) one_integer: { the_integer = 6 }
 264 [15:52:24.202029477] (+0.000001150) one_integer: { the_integer = 0 }
 265 [15:52:24.202029988] (+0.000000511) one_string: { the_string = "./app" }
 266 [15:52:24.202033362] (+0.000003374) one_integer: { the_integer = 1 }
 267 [15:52:24.202033716] (+0.000000354) one_string: { the_string = "lorem" }
 268 [15:52:24.202034147] (+0.000000431) one_integer: { the_integer = 2 }
 269 [15:52:24.202034465] (+0.000000318) one_string: { the_string = "ipsum" }
 270 [15:52:24.202034812] (+0.000000347) one_integer: { the_integer = 3 }
 271 [15:52:24.202035147] (+0.000000335) one_string: { the_string = "nulla" }
 272 [15:52:24.202035527] (+0.000000380) one_integer: { the_integer = 4 }
 273 [15:52:24.202035848] (+0.000000321) one_string: { the_string = "dolore" }
 274 [15:52:24.202036175] (+0.000000327) one_integer: { the_integer = 5 }
 275 [15:52:24.202036553] (+0.000000378) one_string: { the_string = "consequat" }
 276 ----
 277
 278 You can also open the trace with
 279 https://www.eclipse.org/tracecompass/[Trace{nbsp}Compass]:
 280
 281 .Trace Compass 5.3.0's event list view
 282 image::getting-started-trace-compass.png[]