Write a barectf platform

A barectf platform is:

Callback functions to open and close packets.

Those functions allow the platform to control where the data streams are stored (called the back end) and how full packets are appended to them.

The back end can be anything: files, memory, network, serial, and more.
A callback function to indicate whether or not the back end is full.
Data stream default clock source callback functions.
An API for applications to:
- Initialize the platform.
- Obtain a barectf context pointer.
- Finalize the platform.

The purpose of a barectf platform is to decouple the packet storing and clock sourcing operations from the event record writing operations. Tracing functions, which the application calls, handle the latter.

See Platform example for a complete barectf platform example.

Steps

To write a barectf platform:

Write the platform callback functions.

Each function receives some platform context pointer as its first parameter.
Write a platform initialization function.

This function needs to allocate one or more barectf contexts, initialize them with the platform callback functions of step 1, and store them.

This function typically opens the first packet.

This function can return a pointer to a platform context structure. This structure can also be global if needed.
Write a platform finalization function.

This function can accept a platform context pointer parameter.

This function typically starts with this, for each barectf context of the platform:
```
if (barectf_packet_is_open(barectf_ctx) &&
        !barectf_packet_is_empty(barectf_ctx)) {
    /* Close the packet here */
}
```
where barectf_ctx is a pointer to a barectf context.

This function also needs to deallocate the platform’s barectf contexts.
Write one or more barectf context pointer accessor functions.

This function can accept a platform context pointer parameter. It returns the requested barectf context pointer.

See Platform example for a complete barectf platform example.

YAML configuration file recommandation

The barectf project recommends that you create a partial YAML file containing a base trace type object as its document for your platform.

This platform’s base trace type object can be configured so that it matches what your platform expects, for example:

The native byte order
Specific clock type objects
Specific Data stream type objects, possibly with:
- Default clock types
- Extra packet context field type members

An application-specific YAML configuration files can then include the platform’s trace type partial YAML file and augment it.

Consider this partial YAML file:

my-platform-trace-type.yaml

native-byte-order: little-endian
clock-types:
  sys3:
    frequency: 8000000
    precision: 80
    origin-is-unix-epoch: false
data-stream-types:
  main:
    $default-clock-type-name: sys3
    packet-context-field-type-extra-members:
      - load: int8
      - node_id: uint16

An application-specific YAML configuration file can include my-platform-trace-type.yaml at the trace type object level:

--- !<tag:barectf.org,2020/3/config>
trace:
  type:
    $include:
      - my-platform-trace-type.yaml
      - stdint.yaml
      - stdmisc.yaml
    $field-type-aliases:
      ipv4-addr:
        class: static-array
        length: 4
        element-field-type: uint8
    data-stream-types:
      main:
        $is-default: true
        event-record-types:
          on_send:
            payload-field-type:
              class: structure
              members:
                - msg: string
                - dst_ip_addr: ipv4-addr
          on_recv:
            payload-field-type:
              class: structure
              members:
                - msg: string
                - src_ip_addr: ipv4-addr