diff --git a/doc/api/kernel_api.rst b/doc/api/kernel_api.rst index d1081f40850..384d63e3bb3 100644 --- a/doc/api/kernel_api.rst +++ b/doc/api/kernel_api.rst @@ -119,20 +119,20 @@ somewhat akin to Unix-style signals. .. doxygengroup:: alert_apis :project: Zephyr -Fifos +FIFOs ***** -Fifos provide traditional first in, first out (FIFO) queuing of data items +FIFOs provide traditional first in, first out (FIFO) queuing of data items of any size. (See :ref:`fifos_v2`.) .. doxygengroup:: fifo_apis :project: Zephyr -Lifos +LIFOs ***** -Lifos provide traditional last in, first out (LIFO) queuing of data items +LIFOs provide traditional last in, first out (LIFO) queuing of data items of any size. (See :ref:`lifos_v2`.) diff --git a/doc/kernel/data_passing/fifos.rst b/doc/kernel/data_passing/fifos.rst index b06629bdbaf..d4d3a1fe89c 100644 --- a/doc/kernel/data_passing/fifos.rst +++ b/doc/kernel/data_passing/fifos.rst @@ -1,6 +1,6 @@ .. _fifos_v2: -Fifos +FIFOs ##### A :dfn:`fifo` is a kernel object that implements a traditional @@ -24,7 +24,7 @@ A fifo has the following key properties: A fifo must be initialized before it can be used. This sets its queue to empty. -Fifo data items must be aligned on a 4-byte boundary, as the kernel reserves +FIFO data items must be aligned on a 4-byte boundary, as the kernel reserves the first 32 bits of an item for use as a pointer to the next data item in the queue. Consequently, a data item that holds N bytes of application data requires N+4 bytes of memory. @@ -56,7 +56,7 @@ without waiting. Implementation ************** -Defining a Fifo +Defining a FIFO =============== A fifo is defined using a variable of type :c:type:`struct k_fifo`. @@ -79,7 +79,7 @@ The following code has the same effect as the code segment above. K_FIFO_DEFINE(my_fifo); -Writing to a Fifo +Writing to a FIFO ================= A data item is added to a fifo by calling :cpp:func:`k_fifo_put()`. @@ -112,7 +112,7 @@ to send data to one or more consumer threads. Additionally, a singly-linked list of data items can be added to a fifo by calling :cpp:func:`k_fifo_put_list()` or :cpp:func:`k_fifo_put_slist()`. -Reading from a Fifo +Reading from a FIFO =================== A data item is removed from a fifo by calling :cpp:func:`k_fifo_get()`. diff --git a/doc/kernel/data_passing/lifos.rst b/doc/kernel/data_passing/lifos.rst index 15dc533b99a..5fa4b1050ae 100644 --- a/doc/kernel/data_passing/lifos.rst +++ b/doc/kernel/data_passing/lifos.rst @@ -1,6 +1,6 @@ .. _lifos_v2: -Lifos +LIFOs ##### A :dfn:`lifo` is a kernel object that implements a traditional @@ -24,7 +24,7 @@ A lifo has the following key properties: A lifo must be initialized before it can be used. This sets its queue to empty. -Lifo data items must be aligned on a 4-byte boundary, as the kernel reserves +LIFO data items must be aligned on a 4-byte boundary, as the kernel reserves the first 32 bits of an item for use as a pointer to the next data item in the queue. Consequently, a data item that holds N bytes of application data requires N+4 bytes of memory. @@ -47,7 +47,7 @@ that has waited longest. Implementation ************** -Defining a Lifo +Defining a LIFO =============== A lifo is defined using a variable of type :c:type:`struct k_lifo`. @@ -70,7 +70,7 @@ The following code has the same effect as the code segment above. K_LIFO_DEFINE(my_lifo); -Writing to a Lifo +Writing to a LIFO ================= A data item is added to a lifo by calling :cpp:func:`k_lifo_put()`. @@ -100,7 +100,7 @@ to send data to one or more consumer threads. } } -Reading from a Lifo +Reading from a LIFO =================== A data item is removed from a lifo by calling :cpp:func:`k_lifo_get()`. diff --git a/include/kernel.h b/include/kernel.h index 7cdad5cf46c..ece7e0956a2 100644 --- a/include/kernel.h +++ b/include/kernel.h @@ -1777,17 +1777,17 @@ struct k_fifo { */ /** - * @defgroup fifo_apis Fifo APIs + * @defgroup fifo_apis FIFO APIs * @ingroup kernel_apis * @{ */ /** - * @brief Initialize a fifo. + * @brief Initialize a FIFO queue. * - * This routine initializes a fifo object, prior to its first use. + * This routine initializes a FIFO queue, prior to its first use. * - * @param fifo Address of the fifo. + * @param fifo Address of the FIFO queue. * * @return N/A */ @@ -1795,7 +1795,7 @@ struct k_fifo { k_queue_init((struct k_queue *) fifo) /** - * @brief Cancel waiting on a fifo. + * @brief Cancel waiting on a FIFO queue. * * This routine causes first thread pending on @a fifo, if any, to * return from k_fifo_get() call with NULL value (as if timeout @@ -1803,7 +1803,7 @@ struct k_fifo { * * @note Can be called by ISRs. * - * @param fifo Address of the fifo. + * @param fifo Address of the FIFO queue. * * @return N/A */ @@ -1811,15 +1811,15 @@ struct k_fifo { k_queue_cancel_wait((struct k_queue *) fifo) /** - * @brief Add an element to a fifo. + * @brief Add an element to a FIFO queue. * - * This routine adds a data item to @a fifo. A fifo data item must be + * This routine adds a data item to @a fifo. A FIFO data item must be * aligned on a 4-byte boundary, and the first 32 bits of the item are * reserved for the kernel's use. * * @note Can be called by ISRs. * - * @param fifo Address of the fifo. + * @param fifo Address of the FIFO. * @param data Address of the data item. * * @return N/A @@ -1828,7 +1828,7 @@ struct k_fifo { k_queue_append((struct k_queue *) fifo, data) /** - * @brief Atomically add a list of elements to a fifo. + * @brief Atomically add a list of elements to a FIFO. * * This routine adds a list of data items to @a fifo in one operation. * The data items must be in a singly-linked list, with the first 32 bits @@ -1837,7 +1837,7 @@ struct k_fifo { * * @note Can be called by ISRs. * - * @param fifo Address of the fifo. + * @param fifo Address of the FIFO queue. * @param head Pointer to first node in singly-linked list. * @param tail Pointer to last node in singly-linked list. * @@ -1847,7 +1847,7 @@ struct k_fifo { k_queue_append_list((struct k_queue *) fifo, head, tail) /** - * @brief Atomically add a list of elements to a fifo. + * @brief Atomically add a list of elements to a FIFO queue. * * This routine adds a list of data items to @a fifo in one operation. * The data items must be in a singly-linked list implemented using a @@ -1856,7 +1856,7 @@ struct k_fifo { * * @note Can be called by ISRs. * - * @param fifo Address of the fifo. + * @param fifo Address of the FIFO queue. * @param list Pointer to sys_slist_t object. * * @return N/A @@ -1865,14 +1865,14 @@ struct k_fifo { k_queue_merge_slist((struct k_queue *) fifo, list) /** - * @brief Get an element from a fifo. + * @brief Get an element from a FIFO queue. * * This routine removes a data item from @a fifo in a "first in, first out" * manner. The first 32 bits of the data item are reserved for the kernel's use. * * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT. * - * @param fifo Address of the fifo. + * @param fifo Address of the FIFO queue. * @param timeout Waiting period to obtain a data item (in milliseconds), * or one of the special values K_NO_WAIT and K_FOREVER. * @@ -1883,59 +1883,59 @@ struct k_fifo { k_queue_get((struct k_queue *) fifo, timeout) /** - * @brief Query a fifo to see if it has data available. + * @brief 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. + * if other threads is also trying to read from the FIFO. * * @note Can be called by ISRs. * - * @param fifo Address of the fifo. + * @param fifo Address of the FIFO queue. * - * @return Non-zero if the fifo is empty. + * @return Non-zero if the FIFO queue is empty. * @return 0 if data is available. */ #define k_fifo_is_empty(fifo) \ k_queue_is_empty((struct k_queue *) fifo) /** - * @brief Peek element at the head of fifo. + * @brief Peek element at the head of a FIFO queue. * - * Return element from the head of fifo without removing it. A usecase - * for this is if elements of the fifo are themselves containers. Then + * Return element from the head of FIFO queue without removing it. A usecase + * for this is if elements of the FIF 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. + * it will be completely remove from the FIFO queue. * - * @param fifo Address of the fifo. + * @param fifo Address of the FIFO queue. * - * @return Head element, or NULL if the fifo is empty. + * @return Head element, or NULL if the FIFO queue is empty. */ #define k_fifo_peek_head(fifo) \ k_queue_peek_head((struct k_queue *) fifo) /** - * @brief Peek element at the tail of fifo. + * @brief Peek element at the tail of FIFO queue. * - * Return element from the tail of fifo (without removing it). A usecase - * for this is if elements of the fifo are themselves containers. Then - * it may be useful to add more data to the last container in fifo. + * 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. * - * @param fifo Address of the fifo. + * @param fifo Address of the FIFO queue. * - * @return Tail element, or NULL if fifo is empty. + * @return Tail element, or NULL if a FIFO queue is empty. */ #define k_fifo_peek_tail(fifo) \ k_queue_peek_tail((struct k_queue *) fifo) /** - * @brief Statically define and initialize a fifo. + * @brief Statically define and initialize a FIFO queue. * - * The fifo can be accessed outside the module where it is defined using: + * The FIFO queue can be accessed outside the module where it is defined using: * * @code extern struct k_fifo ; @endcode * - * @param name Name of the fifo. + * @param name Name of the FIFO queue. */ #define K_FIFO_DEFINE(name) \ struct k_fifo name \ @@ -1964,17 +1964,17 @@ struct k_lifo { */ /** - * @defgroup lifo_apis Lifo APIs + * @defgroup lifo_apis LIFO APIs * @ingroup kernel_apis * @{ */ /** - * @brief Initialize a lifo. + * @brief Initialize a LIFO queue. * - * This routine initializes a lifo object, prior to its first use. + * This routine initializes a LIFO queue object, prior to its first use. * - * @param lifo Address of the lifo. + * @param lifo Address of the LIFO queue. * * @return N/A */ @@ -1982,15 +1982,15 @@ struct k_lifo { k_queue_init((struct k_queue *) lifo) /** - * @brief Add an element to a lifo. + * @brief Add an element to a LIFO queue. * - * This routine adds a data item to @a lifo. A lifo data item must be + * This routine adds a data item to @a lifo. A LIFO queue data item must be * aligned on a 4-byte boundary, and the first 32 bits of the item are * reserved for the kernel's use. * * @note Can be called by ISRs. * - * @param lifo Address of the lifo. + * @param lifo Address of the LIFO queue. * @param data Address of the data item. * * @return N/A @@ -1999,14 +1999,14 @@ struct k_lifo { k_queue_prepend((struct k_queue *) lifo, data) /** - * @brief Get an element from a lifo. + * @brief Get an element from a LIFO queue. * * This routine removes a data item from @a lifo in a "last in, first out" * manner. The first 32 bits of the data item are reserved for the kernel's use. * * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT. * - * @param lifo Address of the lifo. + * @param lifo Address of the LIFO queue. * @param timeout Waiting period to obtain a data item (in milliseconds), * or one of the special values K_NO_WAIT and K_FOREVER. * @@ -2017,9 +2017,9 @@ struct k_lifo { k_queue_get((struct k_queue *) lifo, timeout) /** - * @brief Statically define and initialize a lifo. + * @brief Statically define and initialize a LIFO queue. * - * The lifo can be accessed outside the module where it is defined using: + * The LIFO queue can be accessed outside the module where it is defined using: * * @code extern struct k_lifo ; @endcode *