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

@@ -47,6 +47,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
@@ -83,6 +84,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,147 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+#include <stddef.h>
+#include <stdint.h>
+
+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.
+	 */
+	int head;
+	/**
+	 * @brief FIFO tail.
+	 */
+	int 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.
+ *
+ * @return true Queue is full.
+ * @return false 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.
+ *
+ * @return true Queue is empty.
+ * @return false 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 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 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);

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

lib/bm_fifo/bm_fifo.c

@@ -0,0 +1,181 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+#include <stddef.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <string.h>
+#include <zephyr/sys/__assert.h> /* __ASSERT */
+#include <s115/nrf_error.h>
+
+/* We don't want to include this in unit tests. */
+#if CONFIG_HAS_NRFX
+#include <nrfx.h>
+#else
+#define NRFX_CRITICAL_SECTION_ENTER(...)
+#define NRFX_CRITICAL_SECTION_EXIT(...)
+#endif
+
+#include <bm_fifo.h>
+
+bool bm_fifo_is_full(const struct bm_fifo *fifo)
+{
+	__ASSERT_NO_MSG(fifo);
+	return (fifo->count == fifo->capacity);
+}
+
+bool bm_fifo_is_empty(const struct bm_fifo *fifo)
+{
+	__ASSERT_NO_MSG(fifo);
+	return (fifo->count == 0);
+}
+
+uint32_t bm_fifo_init(struct bm_fifo *fifo, void *buf, size_t capacity, size_t item_size)
+{
+	if (!fifo || !buf) {
+		return NRF_ERROR_NULL;
+	}
+	if (!item_size || !capacity) {
+		return NRF_ERROR_INVALID_PARAM;
+	}
+
+	memset(fifo, 0x00, sizeof(*fifo));
+
+	fifo->buf = buf;
+	fifo->item_size = item_size;
+	fifo->capacity = capacity;
+
+	return NRF_SUCCESS;
+}
+
+uint32_t bm_fifo_enqueue(struct bm_fifo *fifo, void *buf)
+{
+	uint32_t err;
+	void *item;
+
+	if (!fifo || !buf) {
+		return NRF_ERROR_NULL;
+	}
+
+	NRFX_CRITICAL_SECTION_ENTER();
+
+	if (bm_fifo_is_full(fifo)) {
+		err = NRF_ERROR_NO_MEM;
+		goto out;
+	}
+
+	fifo->count++;
+	__ASSERT(fifo->count <= fifo->capacity, "Queue overflow");
+
+	item = (uint8_t *)fifo->buf + (fifo->tail * fifo->item_size);
+	fifo->tail = (fifo->tail + 1) % fifo->capacity;
+	memcpy(item, buf, fifo->item_size);
+
+	err = NRF_SUCCESS;
+
+out:
+	NRFX_CRITICAL_SECTION_EXIT();
+	return err;
+}
+
+uint32_t bm_fifo_dequeue(struct bm_fifo *fifo, void *buf)
+{
+	uint32_t err;
+	void *item;
+
+	if (!fifo || !buf) {
+		return NRF_ERROR_NULL;
+	}
+
+	NRFX_CRITICAL_SECTION_ENTER();
+
+	if (bm_fifo_is_empty(fifo)) {
+		err = NRF_ERROR_NOT_FOUND;
+		goto out;
+	}
+
+	fifo->count--;
+	__ASSERT(fifo->count <= fifo->capacity, "Queue underflow");
+
+	item = (uint8_t *)fifo->buf + (fifo->head * fifo->item_size);
+	fifo->head = (fifo->head + 1) % fifo->capacity;
+	memcpy(buf, item, fifo->item_size);
+
+	err = NRF_SUCCESS;
+
+out:
+	NRFX_CRITICAL_SECTION_EXIT();
+	return err;
+}
+
+uint32_t bm_fifo_peek(const struct bm_fifo *fifo, void *buf)
+{
+	uint32_t err;
+	void *item;
+
+	if (!fifo || !buf) {
+		return NRF_ERROR_NULL;
+	}
+
+	NRFX_CRITICAL_SECTION_ENTER();
+
+	if (bm_fifo_is_empty(fifo)) {
+		err = NRF_ERROR_NOT_FOUND;
+		goto out;
+	}
+
+	item = (uint8_t *)fifo->buf + (fifo->head * fifo->item_size);
+	memcpy(buf, item, fifo->item_size);
+
+	err = NRF_SUCCESS;
+
+out:
+	NRFX_CRITICAL_SECTION_EXIT();
+	return err;
+}
+
+uint32_t bm_fifo_discard(struct bm_fifo *fifo)
+{
+	uint32_t err;
+
+	if (!fifo) {
+		return NRF_ERROR_NULL;
+	}
+
+	NRFX_CRITICAL_SECTION_ENTER();
+
+	if (bm_fifo_is_empty(fifo)) {
+		err = NRF_ERROR_NOT_FOUND;
+		goto out;
+	}
+
+	fifo->count--;
+	__ASSERT(fifo->count <= fifo->capacity, "Queue underflow");
+
+	fifo->head = (fifo->head + 1) % fifo->capacity;
+
+	err = NRF_SUCCESS;
+
+out:
+	NRFX_CRITICAL_SECTION_EXIT();
+	return err;
+}
+
+uint32_t bm_fifo_clear(struct bm_fifo *fifo)
+{
+	if (!fifo) {
+		return NRF_ERROR_NULL;
+	}
+
+	NRFX_CRITICAL_SECTION_ENTER();
+
+	fifo->head = 0;
+	fifo->tail = 0;
+	fifo->count = 0;
+
+	NRFX_CRITICAL_SECTION_EXIT();
+
+	return NRF_SUCCESS;
+}