|
Zephyr API Documentation 4.5.99
A Scalable Open Source RTOS
|
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. | |
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.
|
isr-ok |
#include <zephyr/kernel.h>
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.
| fifo | Address of the FIFO. |
| data | Address of the data item. |
| 0 | on success |
| -ENOMEM | The resource pool of the calling thread has insufficient RAM |
|
isr-ok |
#include <zephyr/kernel.h>
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.
| fifo | Address of the FIFO queue. |
| #define K_FIFO_DEFINE | ( | name | ) |
#include <zephyr/kernel.h>
Statically define and initialize a FIFO queue.
The FIFO queue can be accessed outside the module where it is defined using:
| name | Name of the FIFO queue. |
|
isr-ok |
#include <zephyr/kernel.h>
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.
| 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. |
| non-NULL | Address of the data item that was removed. |
| NULL | The FIFO was empty and timeout was K_NO_WAIT, the waiting period expired, or the wait was cancelled by k_fifo_cancel_wait(). |
| #define k_fifo_init | ( | fifo | ) |
#include <zephyr/kernel.h>
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.
| fifo | Address of the FIFO queue. |
|
isr-ok |
#include <zephyr/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 are also trying to read from the FIFO.
| fifo | Address of the FIFO queue. |
| 1 | fifo is empty. |
| 0 | fifo holds at least one item. |
|
isr-ok |
#include <zephyr/kernel.h>
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.
| fifo | Address of the FIFO queue. |
| non-NULL | Address of the head element. |
| NULL | fifo is empty. |
|
isr-ok |
#include <zephyr/kernel.h>
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.
| fifo | Address of the FIFO queue. |
| non-NULL | Address of the tail element. |
| NULL | fifo is empty. |
|
isr-ok |
#include <zephyr/kernel.h>
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.
| fifo | Address of the FIFO. |
| data | Address of the data item. |
|
isr-ok |
#include <zephyr/kernel.h>
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.
| fifo | Address of the FIFO queue. |
| head | Pointer to first node in singly-linked list. |
| tail | Pointer to last node in singly-linked list. |
| 0 | on success |
| -EINVAL | head or tail is a null pointer |
|
isr-ok |
#include <zephyr/kernel.h>
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.
| fifo | Address of the FIFO queue. |
| list | Pointer to sys_slist_t object. |
| 0 | on success |
| -EINVAL | list is empty |