Data FIFO

This library combines the Zephyr memory slab and message queue mechanisms. The purpose is to be able to allocate a memory slab, use it, and signal to a receiver when the write operation has completed. The reader can then read and free the memory slab when done. For more information, see API documentation.

Configuration

To enable the library, set the CONFIG_DATA_FIFO Kconfig option to y in the project configuration file prj.conf.

API documentation

Header file: include/data_fifo.h
Source file: lib/data_fifo/data_fifo.c
group data_fifo

Used to allocate a memory slab, use it, and signal to a receiver when the write operation has completed. The reader can then read and free the memory slab when done.

Defines

DATA_FIFO_DEFINE(name, elements_max_in, block_size_max_in)

Functions

int data_fifo_pointer_first_vacant_get(struct data_fifo *data_fifo, void **data, k_timeout_t timeout)

Get pointer to the first vacant block in slab.

Gives pointer to the first vacant memory block in the slab.

Parameters:

  • data_fifo – Pointer to the data_fifo structure.

  • data – Double pointer to the memory area. If this function returns with success, the caller is now able to write to this memory block. The write operation must not exceed the block size max given to DATA_FIFO_DEFINE.

  • timeout – Non-negative waiting period to wait for operation to complete (in milliseconds). Use K_NO_WAIT to return without waiting, or K_FOREVER to wait as long as necessary.

Return values:

  • 0 – Memory allocated.

  • value – Return values from k_mem_slab_alloc.

int data_fifo_block_lock(struct data_fifo *data_fifo, void **data, size_t size)

Confirm that the memory block use has finished and the block is put into the message queue.

There is no mechanism blocking this region from being written to or read from. Hence, this block should not be used before it is later fetched by using data_fifo_pointer_last_filled_get.

Parameters:

  • data_fifo – Pointer to the data_fifo structure.

  • data – Double pointer to the memory block that has been written to.

  • size – Number of bytes written. Must be equal to or smaller than the block size max.

Return values:

  • 0 – Block has been submitted to the message queue.

  • -ENOMEM – The size parameter is larger than the block size max.

  • -EINVAL – The supplied size is zero.

  • -ESPIPE – A generic return value if an error occurs in k_msg_put. Since data has already been added to the slab, there must be space in the message queue.

int data_fifo_pointer_last_filled_get(struct data_fifo *data_fifo, void **data, size_t *size, k_timeout_t timeout)

Get pointer to first (oldest) filled block in slab.

This returns a pointer to the first filled block in the slab (FIFO).

Parameters:

  • data_fifo – Pointer to the data_fifo structure.

  • data – Double pointer to the block. If this functions returns with success, the caller is now able to read from this memory block.

  • size – Actual size in bytes of the stored data. This may be equal to or less than the block size.

  • timeout – Non-negative waiting period to wait for operation to complete (in milliseconds). Use K_NO_WAIT to return without waiting, or K_FOREVER to wait as long as necessary.

Return values:

  • 0 – Memory pointer retrieved.

  • value – Return values from k_msgq_get.

void data_fifo_block_free(struct data_fifo *data_fifo, void *data)

Free the data block after reading.

Read has finished in the given data block.

Parameters:

  • data_fifo – Pointer to the data_fifo structure.

  • data – Pointer to the memory area which is to be freed.

int data_fifo_num_used_get(struct data_fifo *data_fifo, uint32_t *alloced_num, uint32_t *locked_num)

See how many alloced and locked blocks are in the system.

Parameters:

  • data_fifo – Pointer to the data_fifo structure.

  • alloced_num – Number of used blocks in the slab.

  • locked_num – Number of used items in the message queue.

Return values:

  • 0 – Success.

  • -EACCES – Illegal combination of used message queue items and slabs. If an error occurs, parameters will be set to UINT32_MAX.

int data_fifo_empty(struct data_fifo *data_fifo)

Empty all items from data_fifo.

Parameters:

  • data_fifo – Pointer to the data FIFO to be emptied.

Returns:

0 if success, error otherwise.

int data_fifo_init(struct data_fifo *data_fifo)

Initialise the data_fifo.

Parameters:

  • data_fifo – Pointer to the data_fifo structure.

Return values:

  • 0 – Success.

  • value – Return values from k_mem_slab_init.

struct data_fifo_msgq
#include <data_fifo.h>
struct data_fifo
#include <data_fifo.h>