| 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[] |