FIFO APIs

Macros
#define	k_fifo_init(fifo)
	Initialize a FIFO queue.
#define	k_fifo_cancel_wait(fifo)
	Cancel waiting on a FIFO queue.
#define	k_fifo_put(fifo, data)
	Add an element to a FIFO queue.
#define	k_fifo_alloc_put(fifo, data)
	Add an element to a FIFO queue.
#define	k_fifo_put_list(fifo, head, tail)
	Atomically add a list of elements to a FIFO.
#define	k_fifo_put_slist(fifo, list)
	Atomically add a list of elements to a FIFO queue.
#define	k_fifo_get(fifo, timeout)
	Get an element from a FIFO queue.
#define	k_fifo_is_empty(fifo)
	Query a FIFO queue to see if it has data available.
#define	k_fifo_peek_head(fifo)
	Peek element at the head of a FIFO queue.
#define	k_fifo_peek_tail(fifo)
	Peek element at the tail of FIFO queue.
#define	K_FIFO_DEFINE(name)
	Statically define and initialize a FIFO queue.

Detailed Description

Macro Definition Documentation

k_fifo_alloc_put

#define k_fifo_alloc_put	(		fifo,
			data )

#include <zephyr/kernel.h>

Value:

        ({ \
        void *_data = data; \
        SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_fifo, alloc_put, fifo, _data); \
        int fap_ret = k_queue_alloc_append(&(fifo)->_queue, _data); \
        SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_fifo, alloc_put, fifo, _data, fap_ret); \
        fap_ret; \
        })

Add an element to a FIFO queue.

This routine adds a data item to fifo. There is an implicit memory allocation to create an additional temporary bookkeeping data structure from the calling thread's resource pool, which is automatically freed when the item is removed. The data itself is not copied.

Function properties (list may not be complete)

Parameters

fifo	Address of the FIFO.
data	Address of the data item.

Return values

0	on success
-ENOMEM	if there isn't sufficient RAM in the caller's resource pool

k_fifo_cancel_wait

#define k_fifo_cancel_wait

(

fifo

)

#include <zephyr/kernel.h>

Value:

        ({ \
        SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_fifo, cancel_wait, fifo); \
        k_queue_cancel_wait(&(fifo)->_queue); \
        SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_fifo, cancel_wait, fifo); \
        })

Cancel waiting on a FIFO queue.

This routine causes first thread pending on fifo, if any, to return from k_fifo_get() call with NULL value (as if timeout expired).

Function properties (list may not be complete)

Parameters

fifo	Address of the FIFO queue.

K_FIFO_DEFINE

#define K_FIFO_DEFINE

(

name

)

#include <zephyr/kernel.h>

Value:

        STRUCT_SECTION_ITERABLE(k_fifo, name) = \
                Z_FIFO_INITIALIZER(name)

Statically define and initialize a FIFO queue.

The FIFO queue can be accessed outside the module where it is defined using:

extern struct k_fifo <name>; 

Parameters

name	Name of the FIFO queue.

k_fifo_get

#define k_fifo_get	(		fifo,
			timeout )

#include <zephyr/kernel.h>

Value:

        ({ \
        SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_fifo, get, fifo, timeout); \
        void *fg_ret = k_queue_get(&(fifo)->_queue, timeout); \
        SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_fifo, get, fifo, timeout, fg_ret); \
        fg_ret; \
        })

Get an element from a FIFO queue.

This routine removes a data item from fifo in a "first in, first out" manner. The first word of the data item is reserved for the kernel's use.

Note

timeout must be set to K_NO_WAIT if called from ISR.

Function properties (list may not be complete)

Parameters

fifo	Address of the FIFO queue.
timeout	Waiting period to obtain a data item, or one of the special values K_NO_WAIT and K_FOREVER.

Returns

Address of the data item if successful; NULL if returned without waiting, or waiting period timed out.

k_fifo_init

#define k_fifo_init

(

fifo

)

#include <zephyr/kernel.h>

Value:

        ({                                                   \
        SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_fifo, init, fifo); \
        k_queue_init(&(fifo)->_queue);                       \
        K_OBJ_CORE_INIT(K_OBJ_CORE(fifo), _obj_type_fifo);   \
        K_OBJ_CORE_LINK(K_OBJ_CORE(fifo));                   \
        SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_fifo, init, fifo);  \
        })

Initialize a FIFO queue.

This routine initializes a FIFO queue, prior to its first use.

Parameters

fifo	Address of the FIFO queue.

k_fifo_is_empty

#define k_fifo_is_empty

(

fifo

)

#include <zephyr/kernel.h>

Value:

        k_queue_is_empty(&(fifo)->_queue)

Query a FIFO queue to see if it has data available.

Note that the data might be already gone by the time this function returns if other threads is also trying to read from the FIFO.

Function properties (list may not be complete)

Parameters

fifo	Address of the FIFO queue.

Returns

Non-zero if the FIFO queue is empty.

0 if data is available.

k_fifo_peek_head

#define k_fifo_peek_head

(

fifo

)

#include <zephyr/kernel.h>

Value:

        ({ \
        SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_fifo, peek_head, fifo); \
        void *fph_ret = k_queue_peek_head(&(fifo)->_queue); \
        SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_fifo, peek_head, fifo, fph_ret); \
        fph_ret; \
        })

Peek element at the head of a FIFO queue.

Return element from the head of FIFO queue without removing it. A usecase for this is if elements of the FIFO object are themselves containers. Then on each iteration of processing, a head container will be peeked, and some data processed out of it, and only if the container is empty, it will be completely remove from the FIFO queue.

Parameters

fifo	Address of the FIFO queue.

Returns

Head element, or NULL if the FIFO queue is empty.

k_fifo_peek_tail

#define k_fifo_peek_tail

(

fifo

)

#include <zephyr/kernel.h>

Value:

        ({ \
        SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_fifo, peek_tail, fifo); \
        void *fpt_ret = k_queue_peek_tail(&(fifo)->_queue); \
        SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_fifo, peek_tail, fifo, fpt_ret); \
        fpt_ret; \
        })

Peek element at the tail of FIFO queue.

Return element from the tail of FIFO queue (without removing it). A usecase for this is if elements of the FIFO queue are themselves containers. Then it may be useful to add more data to the last container in a FIFO queue.

Parameters

fifo	Address of the FIFO queue.

Returns

Tail element, or NULL if a FIFO queue is empty.

k_fifo_put

#define k_fifo_put	(		fifo,
			data )

#include <zephyr/kernel.h>

Value:

        ({ \
        void *_data = data; \
        SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_fifo, put, fifo, _data); \
        k_queue_append(&(fifo)->_queue, _data); \
        SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_fifo, put, fifo, _data); \
        })

Add an element to a FIFO queue.

This routine adds a data item to fifo. A FIFO data item must be aligned on a word boundary, and the first word of the item is reserved for the kernel's use.

Function properties (list may not be complete)

Parameters

fifo	Address of the FIFO.
data	Address of the data item.

k_fifo_put_list

#define k_fifo_put_list	(		fifo,
			head,
			tail )

#include <zephyr/kernel.h>

Value:

        ({ \
        SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_fifo, put_list, fifo, head, tail); \
        k_queue_append_list(&(fifo)->_queue, head, tail); \
        SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_fifo, put_list, fifo, head, tail); \
        })

Atomically add a list of elements to a FIFO.

This routine adds a list of data items to fifo in one operation. The data items must be in a singly-linked list, with the first word of each data item pointing to the next data item; the list must be NULL-terminated.

Function properties (list may not be complete)

Parameters

fifo	Address of the FIFO queue.
head	Pointer to first node in singly-linked list.
tail	Pointer to last node in singly-linked list.

k_fifo_put_slist

#define k_fifo_put_slist	(		fifo,
			list )

#include <zephyr/kernel.h>

Value:

        ({ \
        SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_fifo, put_slist, fifo, list); \
        k_queue_merge_slist(&(fifo)->_queue, list); \
        SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_fifo, put_slist, fifo, list); \
        })

Atomically add a list of elements to a FIFO queue.

This routine adds a list of data items to fifo in one operation. The data items must be in a singly-linked list implemented using a sys_slist_t object. Upon completion, the sys_slist_t object is invalid and must be re-initialized via sys_slist_init().

Function properties (list may not be complete)

Parameters

fifo	Address of the FIFO queue.
list	Pointer to sys_slist_t object.