platforms/linux-fs/README.adoc

   1 // Render with Asciidoctor
   2
   3 = barectf Linux FS platform
   4 Philippe Proulx
   5 16 September 2020
   6 :toc: left
   7
   8 The barectf Linux FS platform is a very simple platform used to
   9 demonstrate barectf.
  10
  11 The platform writes the CTF packets to a data stream file on the file
  12 system.
  13
  14 This platform can also simulate a full back-end randomly with a
  15 configurable ratio.
  16
  17 == barectf configuration requirements
  18
  19 * The default `barectf` file name prefix.
  20
  21 * The default `barectf_` identifier prefix.
  22
  23 * A single data stream type named `default`:
  24
  25 ** No extra packet context field type members.
  26 ** A default clock type named `default`:
  27 Frequency:::: 1000000000 (default)
  28 Offsets:::: 0 (default)
  29 Origin is Unix epoch?:::: Yes (default)
  30 C{nbsp}type:::: `uint64_t`
  31
  32 .Compatible YAML configuration
  33 ====
  34 [source,yaml]
  35 ----
  36 --- !<tag:barectf.org,2020/3/config>
  37 target-byte-order: le
  38 trace:
  39   type:
  40     $include:
  41       - stdint.yaml
  42     clock-types:
  43       default:
  44         $c-type: uint64_t
  45     data-stream-types:
  46       default:
  47         $is-default: true
  48         $default-clock-type-name: default
  49         event-record-types:
  50           my_event:
  51             payload-field-type:
  52               class: struct
  53               members:
  54                 - number: uint32
  55 ----
  56 ====
  57
  58 == C API
  59
  60 === Initialization
  61
  62 ==== Prototype
  63
  64 [source,c]
  65 ----
  66 struct barectf_platform_linux_fs_ctx *barectf_platform_linux_fs_init(
  67     unsigned int buf_size, const char *trace_dir, int simulate_full_backend,
  68     unsigned int full_backend_rand_max, unsigned int full_backend_rand_lt);
  69 ----
  70
  71 ==== Parameters
  72
  73 [cols="d,a"]
  74 |====
  75 |Name |Description
  76
  77 |`buf_size`
  78 |Size of the packet buffer to allocate (bytes).
  79
  80 |`trace_dir`
  81 |Path of the directory to which to write the single data stream file
  82  named `stream`.
  83
  84 |`simulate_full_backend`
  85 |
  86 0::
  87     Disable full back-end simulation.
  88
  89 1::
  90     Enable full back-end simulation.
  91
  92 |`full_backend_rand_max`
  93 |If `simulate_full_backend` is 1, maximum random value.
  94
  95 |`full_backend_rand_lt`
  96 |If `simulate_full_backend` is 1, the back-end is considered full
  97 if the random value is less than `full_backend_rand_lt`.
  98 |====
  99
 100 When `simulate_full_backend` is 1, `full_backend_rand_lt` and
 101 `full_backend_rand_max` form a ratio. For example, if
 102 `full_backend_rand_max` is 5 and `full_backend_rand_lt` is 3, then the
 103 probability of having a full back-end is 3/5.
 104
 105 ==== Return
 106
 107 Success::
 108     An allocated Linux FS platform context.
 109 +
 110 Call <<api-fini,`+barectf_platform_linux_fs_fini()+`>> to finalize and
 111 free it.
 112
 113 Failure::
 114     `NULL`.
 115
 116 [[api-fini]]
 117 === Finalization
 118
 119 ==== Prototype
 120
 121 [source,c]
 122 ----
 123 void barectf_platform_linux_fs_fini(struct barectf_platform_linux_fs_ctx *ctx);
 124 ----
 125
 126 ==== Parameter
 127
 128 |====
 129 |Name |Description
 130
 131 |`ctx`
 132 |Linux FS platform context to finalize and free.
 133 |====
 134
 135 === barectf context access
 136
 137 ==== Prototype
 138
 139 [source,c]
 140 ----
 141 struct barectf_default_ctx *barectf_platform_linux_fs_get_barectf_ctx(
 142     struct barectf_platform_linux_fs_ctx *ctx);
 143 ----
 144
 145 ==== Parameter
 146
 147 |====
 148 |Name |Description
 149
 150 |`ctx`
 151 |Linux FS platform context.
 152 |====
 153
 154 ==== Return
 155
 156 The barectf context to pass to your tracing functions
 157 (`+barectf_default_trace_*()+`).
 158
 159 == Usage example
 160
 161 .`config.yaml`
 162 [source,yaml]
 163 ----
 164 --- !<tag:barectf.org,2020/3/config>
 165 target-byte-order: le
 166 trace:
 167   type:
 168     $include:
 169       - stdint.yaml
 170     clock-types:
 171       default:
 172         $c-type: uint64_t
 173     data-stream-types:
 174       default:
 175         $is-default: true
 176         $default-clock-type-name: default
 177         event-record-types:
 178           my_event:
 179             payload-field-type:
 180               class: struct
 181               members:
 182                 - number: uint32
 183 ----
 184
 185 .`example.c`
 186 [source,c]
 187 ----
 188 #include <assert.h>
 189
 190 #include "barectf-platform-linux-fs.h"
 191 #include "barectf.h"
 192
 193 int main(void)
 194 {
 195     struct barectf_platform_linux_fs_ctx *platform_ctx;
 196     struct barectf_default_ctx *barectf_ctx;
 197     unsigned int i;
 198
 199     platform_ctx = barectf_platform_linux_fs_init(256, "trace", 0, 0, 0);
 200     assert(platform_ctx);
 201     barectf_ctx = barectf_platform_linux_fs_get_barectf_ctx(platform_ctx);
 202
 203     for (i = 0; i < 50; ++i) {
 204         barectf_trace_my_event(barectf_ctx, i);
 205     }
 206
 207     barectf_platform_linux_fs_fini(platform_ctx);
 208     return 0;
 209 }
 210 ----
 211
 212 .Command lines to build and execute the example
 213 ----
 214 $ mkdir trace
 215 $ barectf --metadata-dir=trace config.yaml
 216 $ gcc -o example -I. example.c barectf.c barectf-platform-linux-fs.c
 217 $ ./example
 218 ----
 219
 220 The complete CTF trace is the `trace` directory.
 221
 222 Read it with https://babeltrace.org/[Babeltrace{nbsp}2], for example:
 223
 224 ----
 225 $ babeltrace2 trace
 226 ----
 227
 228 ----
 229 [20:55:29.539931489] (+?.?????????) my_event: { number = 0 }
 230 [20:55:29.539932347] (+0.000000858) my_event: { number = 1 }
 231 [20:55:29.539932698] (+0.000000351) my_event: { number = 2 }
 232 [20:55:29.539932985] (+0.000000287) my_event: { number = 3 }
 233 [20:55:29.539933379] (+0.000000394) my_event: { number = 4 }
 234 [20:55:29.539933684] (+0.000000305) my_event: { number = 5 }
 235 ...
 236 [20:55:29.539965071] (+0.000000277) my_event: { number = 44 }
 237 [20:55:29.539965356] (+0.000000285) my_event: { number = 45 }
 238 [20:55:29.539965622] (+0.000000266) my_event: { number = 46 }
 239 [20:55:29.539965903] (+0.000000281) my_event: { number = 47 }
 240 [20:55:29.539966181] (+0.000000278) my_event: { number = 48 }
 241 [20:55:29.539966518] (+0.000000337) my_event: { number = 49 }
 242 ----