Platform API

This page assumes that the configured identifier prefix is the default barectf.

The public header (usually named barectf.h) which barectf generates offers an API to write a barectf platform.

Context structure

For a given data stream type named NAME:

struct barectf_NAME_ctx {
    /* ... */
};

A barectf platform is responsible for allocating and deallocating such a structure for each data stream type.

What this structure actually contains is not important; a barectf platform only needs to store it.

Platform callback functions structure

struct barectf_platform_callbacks {
    /* Clock source callback functions here */

    /*
     * Returns whether or not the back end is full.
     */
    int (*is_backend_full)(void *user_data);

    /*
     * Opens the current packet.
     */
    void (*open_packet)(void *user_data);

    /*
     * Closes the current packet.
     */
    void (*close_packet)(void *user_data);
};

Each callback function receives as its user_data parameter what you passed to the barectf context initialization function as the user_data parameter.

Clock source

For each clock type object NAME within the trace type’s clock-types property, the platform callback functions structure contains one clock source callback function:

CTYPE (*NAME_clock_get_value)(void *user_data);

CTYPE is the clock type object’s $c-type property (uint32_t by default).

A clock source function returns the clock’s current value. The clock value must be monotonic.

Packet opening

void (*open_packet)(void *user_data);

This function must call the packet opening function.

Packet closing

void (*close_packet)(void *user_data);

This function must:

Call the packet closing function.
Copy or move the current packet to the back end.

After step 2, this function can set a new packet buffer with barectf_packet_set_buf(). If it doesn’t, the next calls to the packet opening function and tracing functions will write to the current packet buffer.

Is the back end full?

int (*is_backend_full)(void *user_data);

This function returns whether or not the back end is full.

In other words, if a new packet is opened now, does this packet have its reserved space in the back end?

Context property accessors

```
uint8_t *barectf_packet_buf_addr(const void *vctx);
```
Returns the packet buffer address of the barectf context vctx.
```
uint32_t barectf_packet_buf_size(const void *vctx);
```
Returns the packet buffer size (bytes) of the barectf context vctx.
```
int barectf_packet_is_full(const void *vctx);
```
Returns whether or not the packet of the barectf context vctx is full.
```
int barectf_packet_is_empty(const void *vctx);
```
Returns whether or not the packet of the barectf context vctx is empty.
```
int barectf_packet_is_open(const void *vctx);
```
Returns whether or not the packet of the barectf context vctx is open.
```
void barectf_packet_set_buf(void *vctx, uint8_t *addr, uint32_t size);
```
Sets the packet buffer of the barectf context vctx to the address addr and the size size bytes.

You can only call this function from the packet closing callback function.
```
uint32_t barectf_discarded_event_records_count(const void *vctx);
```
Returns the number of discarded event records in the barectf context vctx.
```
uint32_t barectf_packet_sequence_number(const void *vctx);
```
Returns the packet sequence number in the barectf context vctx.
```
int barectf_is_in_tracing_section(const void *vctx);
```
Returns whether or not there’s a current tracing function call for the barectf context vctx.
```
volatile const int *barectf_is_in_tracing_section_ptr(const void *vctx);
```
Returns a pointer to an int variable which indicates whether or not there’s a current tracing function call for the barectf context vctx.

Context initialization

Initializes the barectf context vctx with the initial packet buffer located at the address buf_addr and having buf_size bytes, the platform callback functions cbs, and the user data data.

void barectf_init(void *vctx, uint8_t *buf_addr, uint32_t buf_size,
                  struct barectf_platform_callbacks cbs, void *user_data);

user_data is what the platform callback functions receive as their first parameter.

Packet opening

For a given data stream type named NAME, a packet opening function opens the current packet of a barectf context sctx:

void barectf_NAME_open_packet(struct barectf_NAME_ctx *sctx);

Parameters

For each member MNAME of the data stream type object’s packet-context-field-type-extra-members property, this function has an additional parameter named pc_MNAME.

See Generated C types to determine the exact C type of each parameter.

Note that a member with a dynamic array field type actually makes barectf generate two adjacent parameters:

One for the dynamic array’s length.

Example: uint32_t pc___my_array_len
One for the dynamic array’s data.

Example: const uint8_t *pc_my_array

Role

A packet opening function:

Writes initial packet header and context fields.

The source of some of those fields can be parameters.
Saves the offsets of some packet context fields to write them at packet closing time.
Marks the current packet as being open.

In general, a packet opening platform callback function and a platform initialization function (for the first packet) call this function.

Packet closing

For a given data stream type named NAME, a packet closing function closes the current packet of a barectf context sctx:

void barectf_NAME_close_packet(struct barectf_NAME_ctx *sctx);

Role

A packet closing function:

Marks the current packet as being closed.
Writes some packet context fields.
If the sequence-number-field-type packet feature of the corresponding data stream type is enabled: increments the packet sequence number of sctx.

In general, a packet closing platform callback function and a platform finalization function (for the last packet) call this function.