applications: nrf5340_audio: Audio Module Template

include/audio_module/audio_module.h

@@ -23,6 +23,19 @@ extern "C" {
 
 #include "audio_defines.h"
 
+/**
+ * @brief Helper macro to configure the modules parameters.
+ */
+#define AUDIO_MODULE_PARAMETERS(p, dest, sck, sck_size, pri, fifo_rx, fifo_tx, slab, slab_size)    \
+	(p).description = (dest);                                                                  \
+	(p).thread.stack = (sck);                                                                  \
+	(p).thread.stack_size = (sck_size);                                                        \
+	(p).thread.priority = (pri);                                                               \
+	(p).thread.msg_rx = (fifo_rx);                                                             \
+	(p).thread.msg_tx = (fifo_tx);                                                             \
+	(p).thread.data_slab = (slab);                                                             \
+	(p).thread.data_size = (slab_size);
+
 /**
  * @brief Number of valid location bits.
  */
@@ -409,6 +422,10 @@ int audio_module_stop(struct audio_module_handle *handle);
 /**
  * @brief Send an audio data item to an audio module, all data is consumed by the module.
  *
+ * @note: The data pointer and its associated size that are passed via the audio data
+ *        pointer, can be NULL and/or 0. It is the responsibility of the low level module functions
+ *        to handle this correctly.
+ *
  * @param handle       [in/out]  The handle for the receiving module instance.
  * @param audio_data   [in]      Pointer to the audio data to send to the module.
  * @param response_cb  [in]      Pointer to a callback to run when the buffer is
@@ -423,6 +440,10 @@ int audio_module_data_tx(struct audio_module_handle *handle,
 /**
  * @brief Retrieve an audio data item from an audio module.
  *
+ * @note: The data pointer and its associated size that are passed via the audio data
+ *        pointer, can be NULL and/or 0. It is the responsibility of the low level module functions
+ *        to handle this correctly.
+ *
  * @param handle      [in/out]  The handle to the module instance.
  * @param audio_data  [out]     Pointer to the audio data from the module.
  * @param timeout     [in]      Non-negative waiting period to wait for operation to complete
@@ -441,6 +462,10 @@ int audio_module_data_rx(struct audio_module_handle *handle, struct audio_data *
  *       returned via the module or final module's output FIFO. All the input data is consumed
  *       within the call and thus the input data buffer maybe released once the function returns.
  *
+ * @note: The data I/O pointers and their associated sizes that are passed via the audio data
+ *        pointers, can be NULL and/or 0. It is the responsibility of the low level module functions
+ *        to handle this correctly.
+ *
  * @param handle_tx      [in/out]  The handle to the module to send the input audio data to.
  * @param handle_rx      [in/out]  The handle to the module to receive audio data from.
  * @param audio_data_tx  [in]      Pointer to the audio data to send.

include/audio_modules/audio_module_template.h

@@ -0,0 +1,50 @@
+/*
+ * Copyright(c) 2024 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+#ifndef _AUDIO_MODULE_TEMPLATE_H_
+#define _AUDIO_MODULE_TEMPLATE_H_
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include "audio_defines.h"
+#include "audio_module.h"
+
+#define AUDIO_MODULE_TEMPLATE_LAST_BYTES (10)
+
+/**
+ * @brief Private pointer to the module's parameters.
+ *
+ */
+extern struct audio_module_description *audio_module_template_description;
+
+/**
+ * @brief The module configuration structure.
+ *
+ */
+struct audio_module_template_configuration {
+	/* The rate. */
+	uint32_t sample_rate_hz;
+
+	/* the depth. */
+	uint32_t bit_depth;
+
+	/* A string .*/
+	char *some_text;
+};
+
+/**
+ * @brief  Private module context.
+ *
+ */
+struct audio_module_template_context {
+	/* Array of data to illustrate the data process function. */
+	uint8_t audio_module_template_data[AUDIO_MODULE_TEMPLATE_LAST_BYTES];
+
+	/* The template configuration. */
+	struct audio_module_template_configuration config;
+};
+
+#endif /* _AUDIO_MODULE_TEMPLATE_H_ */

include/data_fifo.h

@@ -43,14 +43,14 @@ struct data_fifo {
 
 #define DATA_FIFO_DEFINE(name, elements_max_in, block_size_max_in)                                 \
 	char __aligned(WB_UP(1))                                                                   \
-		_msgq_buffer_##name[(elements_max_in) * sizeof(struct data_fifo_msgq)] = { 0 };    \
+		_msgq_buffer_##name[(elements_max_in) * sizeof(struct data_fifo_msgq)] = {0};      \
 	char __aligned(WB_UP(1))                                                                   \
-		_slab_buffer_##name[(elements_max_in) * (block_size_max_in)] = { 0 };              \
-	struct data_fifo name = { .msgq_buffer = _msgq_buffer_##name,                              \
-				  .slab_buffer = _slab_buffer_##name,                              \
-				  .block_size_max = block_size_max_in,                             \
-				  .elements_max = elements_max_in,                                 \
-				  .initialized = false }
+		_slab_buffer_##name[(elements_max_in) * (block_size_max_in)] = {0};                \
+	struct data_fifo name = {.msgq_buffer = _msgq_buffer_##name,                               \
+				 .slab_buffer = _slab_buffer_##name,                               \
+				 .block_size_max = block_size_max_in,                              \
+				 .elements_max = elements_max_in,                                  \
+				 .initialized = false}
 
 /**
  * @brief Get pointer to the first vacant block in slab.
@@ -150,6 +150,18 @@ int data_fifo_num_used_get(struct data_fifo *data_fifo, uint32_t *alloced_num,
  */
 int data_fifo_empty(struct data_fifo *data_fifo);
 
+/**
+ * @brief Deinitialize data_fifo.
+ *
+ * @note data_fifo is emptied first, so it is the user's responsibility to release any data items it
+ *       has queued. The internal slab and message buffer are not released.
+ *
+ * @param data_fifo Pointer to the data_fifo structure.
+ *
+ * @retval 0 if success, error otherwise.
+ */
+int data_fifo_uninit(struct data_fifo *data_fifo);
+
 /**
  * @brief Initialise the data_fifo.
  *

lib/data_fifo/data_fifo.c

@@ -167,6 +167,22 @@ int data_fifo_empty(struct data_fifo *data_fifo)
 	return 0;
 }
 
+int data_fifo_uninit(struct data_fifo *data_fifo)
+{
+	__ASSERT_NO_MSG(data_fifo != NULL);
+	__ASSERT_NO_MSG(data_fifo->initialized);
+	int ret;
+
+	ret = data_fifo_empty(data_fifo);
+	if (ret) {
+		return ret;
+	}
+
+	data_fifo->initialized = false;
+
+	return 0;
+}
+
 int data_fifo_init(struct data_fifo *data_fifo)
 {
 	__ASSERT_NO_MSG(data_fifo != NULL);

subsys/CMakeLists.txt

@@ -69,6 +69,7 @@ add_subdirectory_ifdef(CONFIG_NRF_DM dm)
 add_subdirectory_ifdef(CONFIG_EMDS emds)
 add_subdirectory_ifdef(CONFIG_NET_CORE_MONITOR net_core_monitor)
 add_subdirectory_ifdef(CONFIG_AUDIO_MODULE audio_module)
+add_subdirectory_ifdef(CONFIG_AUDIO_MODULE_TEMPLATE audio_modules/audio_module_template)
 add_subdirectory_ifdef(CONFIG_UART_ASYNC_ADAPTER uart_async_adapter)
 add_subdirectory_ifdef(CONFIG_SDFW_SERVICES_ENABLED sdfw_services)
 add_subdirectory(suit)

subsys/Kconfig

@@ -34,6 +34,7 @@ rsource "dm/Kconfig"
 rsource "nrf_security/Kconfig"
 rsource "net_core_monitor/Kconfig"
 rsource "audio_module/Kconfig"
+rsource "audio_modules/audio_module_template/Kconfig"
 rsource "uart_async_adapter/Kconfig"
 rsource "trusted_storage/Kconfig"
 rsource "logging/Kconfig"

subsys/audio_module/CMakeLists.txt

@@ -4,4 +4,7 @@
 # SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
 #
 
-target_sources(app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/audio_module.c)
+target_sources(app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/audio_module.c
+)
+
+target_include_directories(app PRIVATE ${ZEPHYR_NRF_MODULE_DIR}/include/audio_module)

subsys/audio_module/Kconfig

@@ -3,8 +3,7 @@
 #
 # SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
 #
-
-menu "Audio Module"
+menu "Audio Modules"
 
 config AUDIO_MODULE
 	tristate "Enable the audio module"
@@ -20,8 +19,12 @@ config AUDIO_MODULE_NAME_SIZE
 	int "Maximum size for module naming in characters"
 	default 20
 
+#----------------------------------------------------------------------------#
+menu "Log levels"
+
 module = AUDIO_MODULE
 module-str = audio_module
 source "subsys/logging/Kconfig.template.log_config"
 
-endmenu # Audio Module
+endmenu # Log levels
+endmenu # Audio Modules