// Render with Asciidoctor = barectf Linux FS platform Philippe Proulx 23 September 2020 :toc: left The barectf Linux FS platform is a very simple platform used to demonstrate barectf. The platform writes the CTF packets to a data stream file on the file system. This platform can also simulate a full back-end randomly with a configurable ratio. == barectf configuration requirements * The default `barectf` file name prefix. * The default `barectf_` identifier prefix. * A single data stream type named `default`: ** No extra packet context field type members. ** A default clock type named `default`: Frequency:::: 1000000000 (default) Offsets:::: 0 (default) Origin is Unix epoch?:::: Yes (default) C{nbsp}type:::: `uint64_t` .Compatible YAML configuration ==== [source,yaml] ---- --- ! trace: type: $include: - stdint.yaml target-byte-order: le clock-types: default: $c-type: uint64_t data-stream-types: default: $is-default: true $default-clock-type-name: default event-record-types: my_event: payload-field-type: class: struct members: - number: uint32 ---- ==== == C API === Initialization ==== Prototype [source,c] ---- struct barectf_platform_linux_fs_ctx *barectf_platform_linux_fs_init( unsigned int buf_size, const char *data_stream_file_path, int simulate_full_backend, unsigned int full_backend_rand_max, unsigned int full_backend_rand_lt); ---- ==== Parameters [cols="d,a"] |==== |Name |Description |`buf_size` |Size of the packet buffer to allocate (bytes). |`data_stream_file_path` |Path of the data stream file to which to append packets. |`simulate_full_backend` | 0:: Disable full back-end simulation. 1:: Enable full back-end simulation. |`full_backend_rand_max` |If `simulate_full_backend` is 1, maximum random value. |`full_backend_rand_lt` |If `simulate_full_backend` is 1, the back-end is considered full if the random value is less than `full_backend_rand_lt`. |==== When `simulate_full_backend` is 1, `full_backend_rand_lt` and `full_backend_rand_max` form a ratio. For example, if `full_backend_rand_max` is 5 and `full_backend_rand_lt` is 3, then the probability of having a full back-end is 3/5. ==== Return Success:: An allocated Linux FS platform context. + Call <> to finalize and free it. Failure:: `NULL`. [[api-fini]] === Finalization ==== Prototype [source,c] ---- void barectf_platform_linux_fs_fini(struct barectf_platform_linux_fs_ctx *ctx); ---- ==== Parameter |==== |Name |Description |`ctx` |Linux FS platform context to finalize and free. |==== === barectf context access ==== Prototype [source,c] ---- struct barectf_default_ctx *barectf_platform_linux_fs_get_barectf_ctx( struct barectf_platform_linux_fs_ctx *ctx); ---- ==== Parameter |==== |Name |Description |`ctx` |Linux FS platform context. |==== ==== Return The barectf context to pass to your tracing functions (`+barectf_default_trace_*()+`). == Usage example .`config.yaml` [source,yaml] ---- --- ! trace: type: $include: - stdint.yaml target-byte-order: le clock-types: default: $c-type: uint64_t data-stream-types: default: $is-default: true $default-clock-type-name: default event-record-types: my_event: payload-field-type: class: struct members: - number: uint32 ---- .`example.c` [source,c] ---- #include #include "barectf-platform-linux-fs.h" #include "barectf.h" int main(void) { struct barectf_platform_linux_fs_ctx *platform_ctx; struct barectf_default_ctx *barectf_ctx; unsigned int i; platform_ctx = barectf_platform_linux_fs_init(256, "trace/stream", 0, 0, 0); assert(platform_ctx); barectf_ctx = barectf_platform_linux_fs_get_barectf_ctx(platform_ctx); for (i = 0; i < 50; ++i) { barectf_trace_my_event(barectf_ctx, i); } barectf_platform_linux_fs_fini(platform_ctx); return 0; } ---- .Command lines to build and execute the example ---- $ mkdir trace $ barectf --metadata-dir=trace config.yaml $ gcc -o example -I. example.c barectf.c barectf-platform-linux-fs.c $ ./example ---- The complete CTF trace is the `trace` directory. Read it with https://babeltrace.org/[Babeltrace{nbsp}2], for example: ---- $ babeltrace2 trace ---- ---- [20:55:29.539931489] (+?.?????????) my_event: { number = 0 } [20:55:29.539932347] (+0.000000858) my_event: { number = 1 } [20:55:29.539932698] (+0.000000351) my_event: { number = 2 } [20:55:29.539932985] (+0.000000287) my_event: { number = 3 } [20:55:29.539933379] (+0.000000394) my_event: { number = 4 } [20:55:29.539933684] (+0.000000305) my_event: { number = 5 } ... [20:55:29.539965071] (+0.000000277) my_event: { number = 44 } [20:55:29.539965356] (+0.000000285) my_event: { number = 45 } [20:55:29.539965622] (+0.000000266) my_event: { number = 46 } [20:55:29.539965903] (+0.000000281) my_event: { number = 47 } [20:55:29.539966181] (+0.000000278) my_event: { number = 48 } [20:55:29.539966518] (+0.000000337) my_event: { number = 49 } ----