lib: bm_fifo: a FIFO queue implementation

A simple FIFO queue implementation using a circular buffer,
that is ISR-safe.

Signed-off-by: Emanuele Di Santo <[email protected]>
Co-Authored-by: Mirko Covizzi <[email protected]>

Author: lemrey

CODEOWNERS

@@ -44,6 +44,7 @@
 /lib/ble_qwr/                             @nrfconnect/ncs-bm
 /lib/ble_racp/                            @nrfconnect/ncs-bm
 /lib/bm_buttons/                          @nrfconnect/ncs-bm
+/lib/bm_fifo/                             @nrfconnect/ncs-bm
 /lib/bm_timer/                            @nrfconnect/ncs-bm
 /lib/boot_banner/                         @nrfconnect/ncs-bm
 /lib/event_scheduler/                     @nrfconnect/ncs-bm
@@ -76,6 +77,7 @@
 # Tests
 /tests/lib/ble_qwr/                       @nrfconnect/ncs-bm
 /tests/lib/ble_racp/                      @nrfconnect/ncs-bm
+/tests/lib/bm_fifo/                       @nrfconnect/ncs-bm
 
 # Zephyr module
 /zephyr/                                  @nrfconnect/ncs-co-build-system

include/bm_fifo.h

@@ -0,0 +1,172 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+
+/** @file
+ *
+ * @defgroup bm_fifo NCS Bare Metal FIFO library
+ * @{
+ *
+ * @brief A simple FIFO queue implementation using a circular buffer, that is ISR-safe.
+ */
+
+#ifndef BM_FIFO_H__
+#define BM_FIFO_H__
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+struct bm_fifo {
+	/**
+	 * @brief FIFO buffer.
+	 */
+	void *buf;
+	/**
+	 * @brief FIFO maximum capacity (number of items).
+	 */
+	uint32_t capacity;
+	/**
+	 * @brief FIFO item size.
+	 */
+	size_t item_size;
+	/**
+	 * @brief Number of items in the queue.
+	 */
+	uint32_t count;
+	/**
+	 * @brief FIFO head.
+	 */
+	uint32_t head;
+	/**
+	 * @brief FIFO tail.
+	 */
+	uint32_t tail;
+};
+
+/**
+ * @brief Statically define a FIFO.
+ *
+ * Avoids the @ref bm_fifo_init() call.
+ */
+#define BM_FIFO_INIT(_name, _capacity, _item_size)                                                 \
+	static uint8_t _name_buf[(_item_size) * (_capacity)];                                      \
+	static struct bm_fifo _name = {                                                            \
+		.buf = _name_buf,                                                                  \
+		.item_size = _item_size,                                                           \
+		.capacity = _capacity,                                                             \
+	}
+
+/**
+ * @brief Initialize a queue.
+ *
+ * @param fifo FIFO queue.
+ * @param buf Queue buffer.
+ * @param capacity Buffer capacity, in number of items.
+ * @param item_size Size of a queue element, in bytes.
+ *
+ * @retval NRF_SUCCESS on success.
+ * @retval NRF_ERROR_NULL If @p fifo or @p buf are @c NULL.
+ * @retval NRF_ERROR_INVALID_PARAM If @p capacity or @p item_size are 0.
+ */
+uint32_t bm_fifo_init(struct bm_fifo *fifo, void *buf, size_t capacity, size_t item_size);
+
+/**
+ * @brief Check whether the queue is full.
+ *
+ * @param fifo FIFO queue.
+ *
+ * @retval true If queue is full.
+ * @retval false If queue is not full.
+ */
+bool bm_fifo_is_full(const struct bm_fifo *fifo);
+
+/**
+ * @brief Check whether the queue is empty.
+ *
+ * @param fifo FIFO queue.
+ *
+ * @retval true If queue is empty.
+ * @retval false If queue is not empty.
+ */
+bool bm_fifo_is_empty(const struct bm_fifo *fifo);
+
+/**
+ * @brief Queue an element.
+ *
+ * The element is copied into the queue's own buffer.
+ * Interrupts are disabled during the copy.
+ *
+ * @param fifo FIFO queue.
+ * @param buf Buffer pointing to the element.
+ *
+ * @retval NRF_SUCCESS on success.
+ * @retval NRF_ERROR_NULL If @p fifo or @p buf are @c NULL.
+ * @retval NRF_ERROR_NO_MEM If there are no buffers available in the queue.
+ */
+uint32_t bm_fifo_enqueue(struct bm_fifo *fifo, void *buf);
+
+/**
+ * @brief Dequeue an element.
+ *
+ * Dequeue an element from the queue's head.
+ *
+ * @param fifo FIFO queue.
+ * @param[out] buf Buffer to copy the element into.
+ *
+ * @retval NRF_SUCCESS on success.
+ * @retval NRF_ERROR_NULL If @p fifo or @p buf are @c NULL.
+ * @retval NRF_ERROR_NOT_FOUND If the queue is empty.
+ */
+uint32_t bm_fifo_dequeue(struct bm_fifo *fifo, void *buf);
+
+/**
+ * @brief Peek at the queue.
+ *
+ * Peek at the queue's head.
+ *
+ * @param fifo FIFO queue.
+ * @param[out] buf Buffer to copy the element into.
+ *
+ * @retval NRF_SUCCESS on success.
+ * @retval NRF_ERROR_NULL If @p fifo or @p buf are @c NULL.
+ * @retval NRF_ERROR_NOT_FOUND If the queue is empty.
+ */
+uint32_t bm_fifo_peek(const struct bm_fifo *fifo, void *buf);
+
+/**
+ * @brief Dequeue one element and discard it.
+ *
+ * Dequeue an element and discard it.
+ *
+ * @param fifo FIFO queue.
+ *
+ * @retval NRF_SUCCESS on success.
+ * @retval NRF_ERROR_NULL If @p fifo is @c NULL.
+ * @retval NRF_ERROR_NOT_FOUND If the queue is empty.
+ */
+uint32_t bm_fifo_discard(struct bm_fifo *fifo);
+
+/**
+ * @brief Clear the queue, discarding all elements.
+ *
+ * @param fifo FIFO queue.
+ *
+ * @retval NRF_SUCCESS on success.
+ * @retval NRF_ERROR_NULL If @p fifo is @c NULL.
+ */
+uint32_t bm_fifo_clear(struct bm_fifo *fifo);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BM_FIFO_H__ */
+
+/** @} */

lib/CMakeLists.txt

@@ -11,6 +11,7 @@ add_subdirectory_ifdef(CONFIG_BLE_RACP ble_racp)
 add_subdirectory_ifdef(CONFIG_EVENT_SCHEDULER event_scheduler)
 add_subdirectory_ifdef(CONFIG_BM_BUTTONS bm_buttons)
 add_subdirectory_ifdef(CONFIG_BM_TIMER bm_timer)
+add_subdirectory_ifdef(CONFIG_BM_FIFO bm_fifo)
 add_subdirectory_ifdef(CONFIG_BLE_QWR ble_qwr)
 add_subdirectory_ifdef(CONFIG_SENSORSIM sensorsim)
 add_subdirectory_ifdef(CONFIG_NCS_BARE_METAL_BOOT_BANNER boot_banner)

lib/Kconfig

@@ -12,6 +12,7 @@ rsource "ble_racp/Kconfig"
 rsource "event_scheduler/Kconfig"
 rsource "bm_buttons/Kconfig"
 rsource "bm_timer/Kconfig"
+rsource "bm_fifo/Kconfig"
 rsource "ble_qwr/Kconfig"
 rsource "sensorsim/Kconfig"
 rsource "boot_banner/Kconfig"

lib/bm_fifo/CMakeLists.txt

@@ -0,0 +1,7 @@
+#
+# Copyright (c) 2025 Nordic Semiconductor ASA
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+zephyr_library()
+zephyr_library_sources(bm_fifo.c)

lib/bm_fifo/Kconfig

@@ -0,0 +1,18 @@
+#
+# Copyright (c) 2025 Nordic Semiconductor
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+menuconfig BM_FIFO
+	bool "FIFO queue library"
+	help
+	  A simple FIFO queue using a circular buffer.
+
+if BM_FIFO
+
+module=BM_FIFO
+module-dep=LOG
+module-str=FIFO library
+source "${ZEPHYR_BASE}/subsys/logging/Kconfig.template.log_config"
+
+endif