Zephyr API Documentation  2.7.0-rc2
A Scalable Open Source RTOS
FIFO APIs

Macros

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

Detailed Description

Macro Definition Documentation

◆ k_fifo_alloc_put

#define k_fifo_alloc_put (   fifo,
  data 
)

#include <include/kernel.h>

Value:
({ \
SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_fifo, alloc_put, fifo, data); \
int ret = k_queue_alloc_append(&(fifo)->_queue, data); \
SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_fifo, alloc_put, fifo, data, ret); \
ret; \
})
struct k_fifo fifo
Definition: errno.c:43
int32_t k_queue_alloc_append(struct k_queue *queue, void *data)
Append an element to a queue.
static ZTEST_BMEM volatile int ret
Definition: k_float_disable.c:28
Definition: kernel.h:2153
static fdata_t data[2]
Definition: test_fifo_contexts.c:15

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)
isr-ok
Parameters
fifoAddress of the FIFO.
dataAddress of the data item.
Return values
0on success
-ENOMEMif there isn't sufficient RAM in the caller's resource pool

◆ k_fifo_cancel_wait

#define k_fifo_cancel_wait (   fifo)

#include <include/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)
isr-ok
Parameters
fifoAddress of the FIFO queue.
Returns
N/A

◆ K_FIFO_DEFINE

#define K_FIFO_DEFINE (   name)

#include <include/kernel.h>

Value:
Z_FIFO_INITIALIZER(name)
#define STRUCT_SECTION_ITERABLE_ALTERNATE(out_type, struct_type, name)
Defines an alternate data type iterable section.
Definition: common.h:215

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 
)

#include <include/kernel.h>

Value:
({ \
SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_fifo, get, fifo, timeout); \
void *ret = k_queue_get(&(fifo)->_queue, timeout); \
SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_fifo, get, fifo, timeout, ret); \
ret; \
})
ZTEST_BMEM int timeout
Definition: main.c:31
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 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)
isr-ok
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.
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 <include/kernel.h>

Value:
({ \
SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_fifo, init, fifo); \
k_queue_init(&(fifo)->_queue); \
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
fifoAddress of the FIFO queue.
Returns
N/A

◆ k_fifo_is_empty

#define k_fifo_is_empty (   fifo)     k_queue_is_empty(&(fifo)->_queue)

#include <include/kernel.h>

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)
isr-ok
Parameters
fifoAddress 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 <include/kernel.h>

Value:
({ \
SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_fifo, peek_head, fifo); \
void *ret = k_queue_peek_head(&(fifo)->_queue); \
SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_fifo, peek_head, fifo, ret); \
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.
Returns
Head element, or NULL if the FIFO queue is empty.

◆ k_fifo_peek_tail

#define k_fifo_peek_tail (   fifo)

#include <include/kernel.h>

Value:
({ \
SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_fifo, peek_tail, fifo); \
void *ret = k_queue_peek_tail(&(fifo)->_queue); \
SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_fifo, peek_tail, fifo, ret); \
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.
Returns
Tail element, or NULL if a FIFO queue is empty.

◆ k_fifo_put

#define k_fifo_put (   fifo,
  data 
)

#include <include/kernel.h>

Value:
({ \
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)
isr-ok
Parameters
fifoAddress of the FIFO.
dataAddress of the data item.
Returns
N/A

◆ k_fifo_put_list

#define k_fifo_put_list (   fifo,
  head,
  tail 
)

#include <include/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)
isr-ok
Parameters
fifoAddress of the FIFO queue.
headPointer to first node in singly-linked list.
tailPointer to last node in singly-linked list.
Returns
N/A

◆ k_fifo_put_slist

#define k_fifo_put_slist (   fifo,
  list 
)

#include <include/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)
isr-ok
Parameters
fifoAddress of the FIFO queue.
listPointer to sys_slist_t object.
Returns
N/A