| 1 |
= Write a barectf YAML configuration file |
| 2 |
|
| 3 |
A barectf configuration controls how barectf generates a tracer, for |
| 4 |
example: |
| 5 |
|
| 6 |
* What are the event record types for which to generate |
| 7 |
xref:tracing-funcs:index.adoc[tracing functions]? |
| 8 |
+ |
| 9 |
In other words, what are the tracing function names and what are their |
| 10 |
parameter types and names? |
| 11 |
|
| 12 |
* Does a data stream have a clock source? If so, what's the clock source |
| 13 |
function's return C{nbsp}type? |
| 14 |
|
| 15 |
* What's the identifier prefix for the C{nbsp}source code which barectf |
| 16 |
generates? |
| 17 |
+ |
| 18 |
By default, a tracing function name could be |
| 19 |
`+barectf_trace_my_stream_my_event()+`, but it can also be |
| 20 |
`+my_company_trace_my_stream_my_event()+`. |
| 21 |
|
| 22 |
barectf supports two methods to write a configuration: |
| 23 |
|
| 24 |
. Create and assemble configuration objects with the barectf Python API |
| 25 |
(`barectf` package). |
| 26 |
|
| 27 |
. Write a configuration in https://yaml.org/[YAML]. |
| 28 |
|
| 29 |
This section is about method{nbsp}2. |
| 30 |
|
| 31 |
Read xref:yaml-primer.adoc[] to learn more about the YAML language. |
| 32 |
|
| 33 |
A barectf YAML configuration document is a |
| 34 |
xref:yaml:cfg-obj.adoc[configuration object]. |
| 35 |
|
| 36 |
[NOTE] |
| 37 |
==== |
| 38 |
In a barectf YAML configuration, a xref:yaml-primer.adoc#scalar[null |
| 39 |
value] always means to use the default value. |
| 40 |
|
| 41 |
This is useful when taking into account the xref:include.adoc[partial |
| 42 |
YAML file inclusion] or xref:ft-obj.adoc#inherit[field type object |
| 43 |
inheritance] features: the overriding object can reset properties to |
| 44 |
their default values. |
| 45 |
==== |
| 46 |
|
| 47 |
[[stages]] |
| 48 |
== Processing stages |
| 49 |
|
| 50 |
barectf goes through the following stages when it processes a YAML |
| 51 |
configuration: |
| 52 |
|
| 53 |
. xref:include.adoc[Include], recursively, partial YAML files. |
| 54 |
|
| 55 |
. Expand xref:trace-type-obj.adoc#ft-aliases-prop[field type aliases]. |
| 56 |
+ |
| 57 |
Replace every field type alias with its full xref:ft-obj.adoc[field type |
| 58 |
object], recursively. |
| 59 |
|
| 60 |
. Apply xref:ft-obj.adoc#inherit[field type object inheritance]. |
| 61 |
|
| 62 |
. Expand xref:trace-type-obj.adoc#ll-aliases-prop[log level aliases]. |
| 63 |
+ |
| 64 |
Replace every log level alias with its numeric value. |
| 65 |
|
| 66 |
. Normalize property values. |
| 67 |
+ |
| 68 |
If more than one value mean the same thing (for example, |
| 69 |
xref:common-values.adoc#byte-order[`be` and |
| 70 |
`big-endian`]), prefer one version. |
| 71 |
|
| 72 |
A xref:cfg-obj.adoc[configuration object], after step{nbsp}5, is known |
| 73 |
as an _effective configuration object_. The |
| 74 |
xref:cli:usage.adoc#show-effective-configuration-command[`barectf show-effective-configuration` |
| 75 |
CLI command] shows the effective version of a YAML configuration file. |
| 76 |
|
| 77 |
[[tsdl-ident]] |
| 78 |
== TSDL identifier |
| 79 |
|
| 80 |
Many barectf YAML objects require that a given string key or value |
| 81 |
be a valid TSDL (Trace Stream Description Language) identifier. |
| 82 |
|
| 83 |
As per https://diamon.org/ctf/v1.8.3/[CTF{nbsp}1.8.3], a valid TSDL |
| 84 |
identifier is any valid C{nbsp}identifier which is __not__ one of: |
| 85 |
|
| 86 |
* `align` |
| 87 |
* `callsite` |
| 88 |
* `const` |
| 89 |
* `char` |
| 90 |
* `clock` |
| 91 |
* `double` |
| 92 |
* `enum` |
| 93 |
* `env` |
| 94 |
* `event` |
| 95 |
* `floating_point` |
| 96 |
* `float` |
| 97 |
* `integer` |
| 98 |
* `int` |
| 99 |
* `long` |
| 100 |
* `short` |
| 101 |
* `signed` |
| 102 |
* `stream` |
| 103 |
* `string` |
| 104 |
* `struct` |
| 105 |
* `trace` |
| 106 |
* `typealias` |
| 107 |
* `typedef` |
| 108 |
* `unsigned` |
| 109 |
* `variant` |
| 110 |
* `void` |
| 111 |
* `_Bool` |
| 112 |
* `_Complex` |
| 113 |
* `_Imaginary` |