docs/modules/yaml/pages/index.adoc

   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`