Zephyr API Documentation 4.5.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
FIFO APIs

A FIFO is a typed view of a queue, so for user threads the object to grant with k_object_access_grant() is the underlying k_queue, not the wrapper. More...

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

A FIFO is a typed view of a queue, so for user threads the object to grant with k_object_access_grant() is the underlying k_queue, not the wrapper.

The macros that expand to a system call are callable from a user thread: k_fifo_init(), k_fifo_cancel_wait(), k_fifo_alloc_put(), k_fifo_get(), k_fifo_is_empty(), k_fifo_peek_head() and k_fifo_peek_tail(). k_fifo_put(), k_fifo_put_list() and k_fifo_put_slist() expand to k_queue_append(), k_queue_append_list() and k_queue_merge_slist(), none of which is a system call, so those three stay in supervisor mode.

Macro Definition Documentation

◆ k_fifo_alloc_put

#define k_fifo_alloc_put ( fifo,
data )
isr-ok

#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; \
})
int32_t k_queue_alloc_append(struct k_queue *queue, void *data)
Append an element to the end of a queue, allocating the link.
Kernel FIFO structure.
Definition kernel.h:3107

Add an element to a FIFO queue.

This routine adds data to the end of fifo, like k_fifo_put(), except that the queue link is taken from a pool instead of from data itself. The link is released automatically once the item has been retrieved, and the first pointer-sized field of data stays available to the caller. The data is not copied.

The link is allocated from the resource pool of the calling thread, or from the system heap when called from ISR context. A thread inherits the resource pool of the thread that creates it, and the main thread starts on the system heap when CONFIG_HEAP_MEM_POOL_SIZE is set, so threads have a pool by default; see k_thread_heap_assign() and k_thread_system_pool_assign(). Only a thread left without a pool fails here, with -ENOMEM, and it does so whether or not CONFIG_HEAP_MEM_POOL_SIZE is set.

If a thread is already waiting in k_fifo_get() on fifo, data is handed to that thread directly, no link is allocated, and this routine cannot fail.

Note
The link is allocated with the queue lock held, so the allocator's lock nests inside the queue lock and the cost of the allocation is part of the critical section.
Parameters
fifoAddress of the FIFO.
dataAddress of the data item.
Return values
0on success
-ENOMEMThe resource pool of the calling thread has insufficient RAM

◆ k_fifo_cancel_wait

#define k_fifo_cancel_wait ( fifo)
isr-ok

#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 the first thread pending on fifo, if any, to return from k_fifo_get() with a null value, as if its timeout had expired. Every k_poll() call waiting on fifo is woken with -EINTR and the K_POLL_STATE_CANCELLED state, and every k_work_poll item waiting on it is submitted.

Note
Does nothing when no thread or k_work_poll item is waiting on fifo.
Parameters
fifoAddress of the FIFO queue.

◆ K_FIFO_DEFINE

#define K_FIFO_DEFINE ( name)

#include <zephyr/kernel.h>

Value:
Z_FIFO_INITIALIZER(name)
#define STRUCT_SECTION_ITERABLE(struct_type, varname)
Defines a new element for an iterable section.
Definition iterable_sections.h:244

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
nameName of the FIFO queue.

◆ k_fifo_get

#define k_fifo_get ( fifo,
timeout )
isr-ok

#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; \
})
void * k_queue_get(struct k_queue *queue, k_timeout_t timeout)
Get an element from a queue.

Get an element from a FIFO queue.

This routine removes and returns the first data item of fifo, that is the one that was added first.

When the item was added by k_fifo_alloc_put(), the link allocated on its behalf is released here and the caller receives the original data pointer. The queue lock is released before the call returns.

Note
timeout must be set to K_NO_WAIT if called from ISR.
A timeout and a k_fifo_cancel_wait() are both reported as a null return; the two cannot be told apart from the return value alone.
Parameters
fifoAddress of the FIFO queue.
timeoutWaiting period to obtain a data item, or one of the special values K_NO_WAIT and K_FOREVER.
Return values
non-NULLAddress of the data item that was removed.
NULLThe FIFO was empty and timeout was K_NO_WAIT, the waiting period expired, or the wait was cancelled by k_fifo_cancel_wait().

◆ 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); \
})
#define K_OBJ_CORE(kobj)
Convert kernel object pointer into its object core pointer.
Definition obj_core.h:25

Initialize a FIFO queue.

This routine initializes a FIFO queue, prior to its first use. The FIFO is left empty, with no thread waiting on it.

Note
fifo must be initialized before any other FIFO API is called on it, and must not be initialized again while it is in use.
Parameters
fifoAddress of the FIFO queue.

◆ k_fifo_is_empty

#define k_fifo_is_empty ( fifo)
isr-ok

#include <zephyr/kernel.h>

Value:
k_queue_is_empty(&(fifo)->_queue)
int k_queue_is_empty(struct k_queue *queue)
Query a queue to see if it has data available.

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 are also trying to read from the FIFO.

Parameters
fifoAddress of the FIFO queue.
Return values
1fifo is empty.
0fifo holds at least one item.

◆ k_fifo_peek_head

#define k_fifo_peek_head ( fifo)
isr-ok

#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; \
})
void * k_queue_peek_head(struct k_queue *queue)
Peek element at the head of queue.

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
fifoAddress of the FIFO queue.
Return values
non-NULLAddress of the head element.
NULLfifo is empty.

◆ k_fifo_peek_tail

#define k_fifo_peek_tail ( fifo)
isr-ok

#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; \
})
void * k_queue_peek_tail(struct k_queue *queue)
Peek element at the tail of queue.

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
fifoAddress of the FIFO queue.
Return values
non-NULLAddress of the tail element.
NULLfifo is empty.

◆ k_fifo_put

#define k_fifo_put ( fifo,
data )
isr-ok

#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 data to the end of fifo.

The item is not copied. The FIFO keeps its link in the first pointer-sized field of data, which is why that field is reserved for the kernel and why data must be aligned as required for a pointer. The item must stay valid until it has been retrieved with k_fifo_get(), and the reserved field must not be written to while it is queued. The rest of the item stays available to the caller and may be updated in place; k_fifo_peek_head() and k_fifo_peek_tail() rely on exactly that.

If a thread is already waiting in k_fifo_get() on fifo, data is handed to that thread directly and never enters the FIFO.

Parameters
fifoAddress of the FIFO.
dataAddress of the data item.

◆ k_fifo_put_list

#define k_fifo_put_list ( fifo,
head,
tail )
isr-ok

#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 pointer-sized field in each data item pointing to the next data item; the list must be NULL-terminated.

Waiting threads are served first, one item each, until either the list is exhausted or no thread is left waiting. Only what remains is added to the FIFO, and the whole operation is done under a single acquisition of the queue lock.

Parameters
fifoAddress of the FIFO queue.
headPointer to first node in singly-linked list.
tailPointer to last node in singly-linked list.
Return values
0on success
-EINVALhead or tail is a null pointer

◆ k_fifo_put_slist

#define k_fifo_put_slist ( fifo,
list )
isr-ok

#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 original list is empty. The caller is responsible for ensuring that list is not concurrently accessed by other threads or ISRs.

As with k_fifo_put_list(), waiting threads are served first, one item each, and only the remainder reaches the FIFO.

Parameters
fifoAddress of the FIFO queue.
listPointer to sys_slist_t object.
Return values
0on success
-EINVALlist is empty