Atomic FIFO

FIFO implementation that allows for making atomic transactions without locking interrupts. More...

Modules
	Atomic operations API
	This module implements C11 stdatomic.h simplified API. At this point only Cortex-M3/M4 cores are supported (LDREX/STREX instructions). Atomic types are limited to nrf_atomic_u32_t and nrf_atomic_flag_t.
	FIFO instance macros

Data Structures
struct	nrf_atfifo_postag_pos_s
	Read and write position structure. More...
union	nrf_atfifo_postag_u
	End data index tag. More...
struct	nrf_atfifo_s
	The FIFO instance. More...
struct	nrf_atfifo_item_put_s
	FIFO write operation item context. More...
struct	nrf_atfifo_rcontext_s
	FIFO read operation item context. More...

Typedefs
typedef struct nrf_atfifo_postag_pos_s	nrf_atfifo_postag_pos_t
	Read and write position structure. More...
typedef union nrf_atfifo_postag_u	nrf_atfifo_postag_t
	End data index tag. More...
typedef struct nrf_atfifo_s	nrf_atfifo_t
	The FIFO instance. More...
typedef struct nrf_atfifo_item_put_s	nrf_atfifo_item_put_t
	FIFO write operation item context. More...
typedef struct nrf_atfifo_rcontext_s	nrf_atfifo_item_get_t
	FIFO read operation item context. More...

Functions
ret_code_t	nrf_atfifo_init (nrf_atfifo_t *const p_fifo, void *p_buf, uint16_t buf_size, uint16_t item_size)
	Function for initializing the FIFO. More...
ret_code_t	nrf_atfifo_clear (nrf_atfifo_t *const p_fifo)
	Function for clearing the FIFO. More...
ret_code_t	nrf_atfifo_alloc_put (nrf_atfifo_t *const p_fifo, void const *const p_var, size_t size, bool *const p_visible)
	Function for atomically putting data into the FIFO. More...
void *	nrf_atfifo_item_alloc (nrf_atfifo_t *const p_fifo, nrf_atfifo_item_put_t *p_context)
	Function for opening the FIFO for writing. More...
bool	nrf_atfifo_item_put (nrf_atfifo_t *const p_fifo, nrf_atfifo_item_put_t *p_context)
	Function for closing the writing operation. More...
ret_code_t	nrf_atfifo_get_free (nrf_atfifo_t *const p_fifo, void *const p_var, size_t size, bool *p_released)
	Function for getting a single value from the FIFO. More...
void *	nrf_atfifo_item_get (nrf_atfifo_t *const p_fifo, nrf_atfifo_item_get_t *p_context)
	Function for opening the FIFO for reading. More...
bool	nrf_atfifo_item_free (nrf_atfifo_t *const p_fifo, nrf_atfifo_item_get_t *p_context)
	Function for closing the reading operation. More...

Detailed Description

FIFO implementation that allows for making atomic transactions without locking interrupts.

There are two types of functions to prepare the FIFO writing:

• Single function for simple access:

  if (NRF_SUCCESS != nrf_atfifo_simple_put(my_fifo, &data, NULL))
  {
   // Error handling
  }

• Function pair to limit data copying:

  struct point3d
  {
   int x, y, z;
  }point3d_t;
  nrf_atfifo_context_t context;
  point3d_t * point;
  
  if (NULL != (point = nrf_atfifo_item_alloc(my_fifo, &context)))
  {
   point->x = a;
   point->y = b;
   point->z = c;
   if (nrf_atfifo_item_put(my_fifo, &context))
   {
   // Send information to the rest of the system
   // that there is new data in the FIFO available for reading.
   }
  }
  else
  {
   // Error handling
  }

  Note

  This atomic FIFO implementation requires that the operation that is opened last is finished (committed/flushed) first. This is typical for operations performed from the interrupt runtime when the other operation is performed from the main thread.

  This implementation does not support typical multithreading operating system access where operations can be started and finished in totally unrelated order.

Typedef Documentation

typedef struct nrf_atfifo_rcontext_s nrf_atfifo_item_get_t

FIFO read operation item context.

Context structure used to mark an opened get operation to properly free an item after reading.

typedef struct nrf_atfifo_item_put_s nrf_atfifo_item_put_t

FIFO write operation item context.

Context structure used to mark an allocated space in FIFO that is ready for put. All the data required to properly put allocated and written data.

typedef struct nrf_atfifo_postag_pos_s nrf_atfifo_postag_pos_t

Read and write position structure.

A structure that holds the read and write position used by the FIFO head and tail.

typedef union nrf_atfifo_postag_u nrf_atfifo_postag_t

End data index tag.

A tag used to mark the end of data. To properly realize atomic data committing, the whole variable has to be accessed atomically.

typedef struct nrf_atfifo_s nrf_atfifo_t

The FIFO instance.

The instance of atomic FIFO. Used with all FIFO functions.

Function Documentation

ret_code_t nrf_atfifo_alloc_put	(	nrf_atfifo_t *const	p_fifo,
		void const *const	p_var,
		size_t	size,
		bool *const	p_visible
	)

Function for atomically putting data into the FIFO.

It uses memcpy function inside and in most situations, it is more suitable to use nrf_atfifo_item_alloc, write the data, and nrf_atfifo_item_put to store a new value in a FIFO.

Parameters

[in,out]	p_fifo	FIFO object.
[in]	p_var	Variable to copy.
[in]	size	Size of the variable to copy. Can be smaller or equal to the FIFO item size.
[out]	p_visible	See value returned by nrf_atfifo_item_put. It may be NULL if the caller does not require the current operation status.

Return values

NRF_SUCCESS	If an element has been successfully added to the FIFO.
NRF_ERROR_NO_MEM	If the FIFO is full.

Note

To avoid data copying, you can use the nrf_atfifo_item_alloc and nrf_atfifo_item_put functions pair.

ret_code_t nrf_atfifo_clear

(

nrf_atfifo_t *const

p_fifo

)

Function for clearing the FIFO.

Function for clearing the FIFO.

If this function is called during an opened and uncommitted write operation, the FIFO is cleared up to the currently ongoing commit. There is no possibility to cancel an ongoing commit.

If this function is called during an opened and unflushed read operation, the read position in the head is set, but copying it into the write head position is left to read closing operation.

This way, there is no more data to read, but the memory is released in the moment when it is safe.

Parameters

[in,out]

p_fifo

FIFO object.

Return values

NRF_SUCCESS	FIFO totally cleared.
NRF_ERROR_BUSY	Function called in the middle of writing or reading operation. If it is called in the middle of writing operation, FIFO was cleared up to the already started and uncommitted write. If it is called in the middle of reading operation, write head was only moved. It will be copied into read tail when the reading operation is flushed.

ret_code_t nrf_atfifo_get_free	(	nrf_atfifo_t *const	p_fifo,
		void *const	p_var,
		size_t	size,
		bool *	p_released
	)

Function for getting a single value from the FIFO.

This function gets the value from the top of the FIFO. The value is removed from the FIFO memory.

Parameters

[in,out]	p_fifo	FIFO object.
[out]	p_var	Pointer to the variable to store the data.
[in]	size	Size of the data to be loaded.
[out]	p_released	See the values returned by nrf_atfifo_item_free.

Return values

NRF_SUCCESS	Element was successfully copied from the FIFO memory.
NRF_ERROR_NOT_FOUND	No data in the FIFO.

ret_code_t nrf_atfifo_init	(	nrf_atfifo_t *const	p_fifo,
		void *	p_buf,
		uint16_t	buf_size,
		uint16_t	item_size
	)

Function for initializing the FIFO.

Preparing the FIFO instance to work.

Parameters

[out]	p_fifo	FIFO object to initialize.
[in,out]	p_buf	FIFO buffer for storing data.
[in]	buf_size	Total buffer size (has to be divisible by item_size).
[in]	item_size	Size of a single item held inside the FIFO.

Return values

NRF_SUCCESS	If initialization was successful.
NRF_ERROR_NULL	If a NULL pointer is provided as the buffer.
NRF_ERROR_INVALID_LENGTH	If size of the buffer provided is not divisible by item_size.

Note

Buffer size must be able to hold one element more than the designed FIFO capacity. This one, empty element is used for overflow checking.

void* nrf_atfifo_item_alloc	(	nrf_atfifo_t *const	p_fifo,
		nrf_atfifo_item_put_t *	p_context
	)

Function for opening the FIFO for writing.

Function called to start the FIFO write operation and access the given FIFO buffer directly.

Parameters

[in,out]	p_fifo	FIFO object.
[out]	p_context	Operation context, required by nrf_atfifo_item_put.

Returns

Pointer to the space where variable data can be stored. NULL if there is no space in the buffer.

bool nrf_atfifo_item_free	(	nrf_atfifo_t *const	p_fifo,
		nrf_atfifo_item_get_t *	p_context
	)

Function for closing the reading operation.

Function used to finish the reading operation. If this reading operation does not interrupt another reading operation, the head write buffer is moved. If this reading operation is placed in the middle of another reading, only the new read pointer is written.

Parameters

[in,out]	p_fifo	FIFO object.
[in]	p_context	Context of the reading operation to be closed.

Return values

true	This operation is not generated in the middle of another read operation and the write head will be updated to the read head (space is released).
false	This operation was performed in the middle of another read operation and the write buffer head was not moved (no space is released).

void* nrf_atfifo_item_get	(	nrf_atfifo_t *const	p_fifo,
		nrf_atfifo_item_get_t *	p_context
	)

Function for opening the FIFO for reading.

Function called to start the FIFO read operation and access the given FIFO buffer directly.

Parameters

[in,out]	p_fifo	FIFO object.
[out]	p_context	The operation context, required by nrf_atfifo_item_free

Returns

Pointer to data buffer or NULL if there is no data in the FIFO.

bool nrf_atfifo_item_put	(	nrf_atfifo_t *const	p_fifo,
		nrf_atfifo_item_put_t *	p_context
	)

Function for closing the writing operation.

Puts a previously allocated context into FIFO. This function must be called to commit an opened write operation. It sets all the buffers and marks the data, so that it is visible to read.

Parameters

[in,out]	p_fifo	FIFO object.
[in]	p_context	Operation context, filled by the nrf_atfifo_item_alloc function.

Return values

true	Data is currently ready and will be visible to read.
false	The internal commit was marked, but the writing operation interrupted another writing operation. The data will be available to read when the interrupted operation is committed.