applications: nrf5340_audio: Audio Module Template

    Implement an audio template to allow rapid
    development od new audio module.

Signed-off-by: Graham Wacey <[email protected]>

CODEOWNERS

@@ -88,6 +88,8 @@ CMakeLists*                               @nrfconnect/ncs-co-build-system
 /include/net/azure_*                      @nrfconnect/ncs-cia @coderbyheart
 /include/net/wifi_credentials.h           @nrfconnect/ncs-cia
 /include/net/nrf_cloud_*                  @nrfconnect/ncs-nrf-cloud
+/include/audio_module/                    @nrfconnect/ncs-audio
+/include/audio/audio_module_template/     @nrfconnect/ncs-audio
 /include/bluetooth/                       @nrfconnect/ncs-si-muffin @nrfconnect/ncs-dragoon
 /include/bluetooth/services/fast_pair/    @nrfconnect/ncs-si-bluebagel
 /include/bluetooth/adv_prov.h             @nrfconnect/ncs-si-bluebagel
@@ -275,6 +277,7 @@ CMakeLists*                               @nrfconnect/ncs-co-build-system
 
 # Subsystems
 /subsys/                                  @nrfconnect/ncs-code-owners
+/subsys/audio/audio_module_template/      @nrfconnect/ncs-audio
 /subsys/audio_module/                     @nrfconnect/ncs-audio
 /subsys/bluetooth/                        @nrfconnect/ncs-si-muffin @nrfconnect/ncs-dragoon
 /subsys/bluetooth/mesh/                   @nrfconnect/ncs-paladin
@@ -389,6 +392,7 @@ CMakeLists*                               @nrfconnect/ncs-co-build-system
 /tests/modules/mcuboot/direct_xip/        @nrfconnect/ncs-pluto
 /tests/modules/mcuboot/external_flash/    @nrfconnect/ncs-pluto
 /tests/nrf5340_audio/                     @nrfconnect/ncs-audio @nordic-auko
+/tests/subsys/audio/audio_module_template/ @nrfconnect/ncs-audio
 /tests/subsys/audio_module/               @nrfconnect/ncs-audio
 /tests/subsys/bluetooth/gatt_dm/          @nrfconnect/ncs-si-muffin
 /tests/subsys/bluetooth/mesh/             @nrfconnect/ncs-paladin

include/audio/audio_module_template.h

@@ -0,0 +1,51 @@
+/*
+ * 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"
+
+/* @brief Size of the data block within the template context, for testing. */
+#define AUDIO_MODULE_TEMPLATE_DATA_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 sample rate, for testing. */
+	uint32_t sample_rate_hz;
+
+	/* The bit depth, for testing. */
+	uint8_t bit_depth;
+
+	/* A string for testing.*/
+	char *module_description;
+};
+
+/**
+ * @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_DATA_BYTES];
+
+	/* The template configuration. */
+	struct audio_module_template_configuration config;
+};
+
+#endif /* _AUDIO_MODULE_TEMPLATE_H_ */

scripts/ci/tags.yaml

@@ -920,6 +920,8 @@ ci_tests_subsys_audio_module:
   files:
     - nrf/subsys/audio_module/
     - nrf/tests/subsys/audio_module/
+    - nrf/subsys/audio/
+    - nrf/tests/subsys/audio/
 
 ci_tests_subsys_mpsl:
   files:

subsys/CMakeLists.txt

@@ -70,6 +70,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/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/audio_module_template/Kconfig"
 rsource "uart_async_adapter/Kconfig"
 rsource "trusted_storage/Kconfig"
 rsource "logging/Kconfig"

subsys/audio/audio_module_template/CMakeLists.txt

@@ -0,0 +1,10 @@
+#
+# Copyright (c) 2024 Nordic Semiconductor
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+target_sources(app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/audio_module_template.c)
+
+target_include_directories(app PRIVATE ${ZEPHYR_NRF_MODULE_DIR}/include/audio_module
+                     ${ZEPHYR_NRF_MODULE_DIR}/include/audio)

subsys/audio/audio_module_template/Kconfig

@@ -0,0 +1,27 @@
+#
+# Copyright (c) 2024 Nordic Semiconductor ASA
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+menu "Audio Modules"
+
+config AUDIO_MODULE_TEMPLATE
+	bool "Audio module template"
+	help
+	  Enable the audio module template, the
+	  starting point for a new audio module
+
+if AUDIO_MODULE_TEMPLATE
+
+#----------------------------------------------------------------------------#
+menu "Log levels"
+
+module = AUDIO_MODULE_TEMPLATE
+module-str = audio_module
+source "subsys/logging/Kconfig.template.log_config"
+
+endmenu # Log levels
+
+endif # AUDIO_MODULE_TEMPLATE
+
+endmenu # Audio Modules

subsys/audio/audio_module_template/audio_module_template.c

@@ -0,0 +1,201 @@
+/*
+ * Copyright(c) 2024 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+#include "audio_module_template.h"
+
+#include <stdlib.h>
+#include <stdio.h>
+#include <ctype.h>
+#include <zephyr/kernel.h>
+#include <errno.h>
+#include "audio_defines.h"
+#include "audio_module.h"
+
+#include <zephyr/logging/log.h>
+LOG_MODULE_REGISTER(audio_module_template, CONFIG_AUDIO_MODULE_TEMPLATE_LOG_LEVEL);
+
+static int audio_module_template_open(struct audio_module_handle_private *handle,
+				      struct audio_module_configuration const *const configuration)
+
+{
+	struct audio_module_handle *hdl = (struct audio_module_handle *)handle;
+	struct audio_module_template_context *ctx =
+		(struct audio_module_template_context *)hdl->context;
+	struct audio_module_template_configuration *config =
+		(struct audio_module_template_configuration *)configuration;
+
+	/* Perform any other functions required to open the module. */
+
+	/* For example: Clear the module's context.
+	 *              Save the initial configuration to the module context.
+	 */
+	memset(ctx, 0, sizeof(struct audio_module_template_context));
+	memcpy(&ctx->config, config, sizeof(struct audio_module_template_configuration));
+
+	LOG_DBG("Open %s module", hdl->name);
+
+	return 0;
+}
+
+static int audio_module_template_close(struct audio_module_handle_private *handle)
+{
+	struct audio_module_handle *hdl = (struct audio_module_handle *)handle;
+	struct audio_module_template_context *ctx =
+		(struct audio_module_template_context *)hdl->context;
+
+	/* Perform any other functions required to close the module. */
+
+	/* For example: Clear the context data */
+	memset(ctx, 0, sizeof(struct audio_module_template_context));
+
+	LOG_DBG("Close %s module", hdl->name);
+
+	return 0;
+}
+
+static int audio_module_template_configuration_set(
+	struct audio_module_handle_private *handle,
+	struct audio_module_configuration const *const configuration)
+{
+	struct audio_module_template_configuration *config =
+		(struct audio_module_template_configuration *)configuration;
+	struct audio_module_handle *hdl = (struct audio_module_handle *)handle;
+	struct audio_module_template_context *ctx =
+		(struct audio_module_template_context *)hdl->context;
+
+	/* Perform any other functions to configure the module. */
+
+	/* For example: Copy the configuration into the context. */
+	memcpy(&ctx->config, config, sizeof(struct audio_module_template_configuration));
+
+	LOG_DBG("Set the configuration for %s module: sample rate = %d  bit depth = %d  string = "
+		"%s",
+		hdl->name, ctx->config.sample_rate_hz, ctx->config.bit_depth,
+		ctx->config.module_description);
+
+	return 0;
+}
+
+static int
+audio_module_template_configuration_get(struct audio_module_handle_private const *const handle,
+					struct audio_module_configuration *configuration)
+{
+	struct audio_module_template_configuration *config =
+		(struct audio_module_template_configuration *)configuration;
+	struct audio_module_handle *hdl = (struct audio_module_handle *)handle;
+	struct audio_module_template_context *ctx =
+		(struct audio_module_template_context *)hdl->context;
+
+	/* Perform any other functions to extract the configuration of the module. */
+
+	/* For example: Copy the configuration from the context into the output configuration. */
+	memcpy(config, &ctx->config, sizeof(struct audio_module_template_configuration));
+
+	LOG_DBG("Get the configuration for %s module: sample rate = %d  bit depth = %d  string = "
+		"%s",
+		hdl->name, config->sample_rate_hz, config->bit_depth, config->module_description);
+
+	return 0;
+}
+
+static int audio_module_template_start(struct audio_module_handle_private *handle)
+{
+	struct audio_module_handle *hdl = (struct audio_module_handle *)handle;
+
+	/* Perform any other functions to start the module. */
+
+	LOG_DBG("Start the %s module", hdl->name);
+
+	return 0;
+}
+
+static int audio_module_template_stop(struct audio_module_handle_private *handle)
+{
+	struct audio_module_handle *hdl = (struct audio_module_handle *)handle;
+
+	/* Perform any other functions to stop the module. */
+
+	LOG_DBG("Stop the %s module", hdl->name);
+
+	return 0;
+}
+
+static int audio_module_template_data_process(struct audio_module_handle_private *handle,
+					      struct audio_data const *const audio_data_in,
+					      struct audio_data *audio_data_out)
+{
+	struct audio_module_handle *hdl = (struct audio_module_handle *)handle;
+
+	/* Perform any other functions to process the data within the module. */
+
+	/* For example: Copy the input to the output. */
+	{
+		size_t size = audio_data_in->data_size < audio_data_out->data_size
+				      ? audio_data_in->data_size
+				      : audio_data_out->data_size;
+
+		memcpy(&audio_data_out->meta, &audio_data_in->meta, sizeof(struct audio_metadata));
+		memcpy(audio_data_out->data, audio_data_in->data, size);
+		audio_data_out->data_size = size;
+	}
+
+	LOG_DBG("Process the input audio data into the output audio data item for %s module",
+		hdl->name);
+
+	return 0;
+}
+
+/**
+ * @brief Table of the dummy module functions.
+ */
+const struct audio_module_functions audio_module_template_functions = {
+	/**
+	 * @brief  Function to an open the dummy module.
+	 */
+	.open = audio_module_template_open,
+
+	/**
+	 * @brief  Function to close the dummy module.
+	 */
+	.close = audio_module_template_close,
+
+	/**
+	 * @brief  Function to set the configuration of the dummy module.
+	 */
+	.configuration_set = audio_module_template_configuration_set,
+
+	/**
+	 * @brief  Function to get the configuration of the dummy module.
+	 */
+	.configuration_get = audio_module_template_configuration_get,
+
+	/**
+	 * @brief Start a module processing data.
+	 */
+	.start = audio_module_template_start,
+
+	/**
+	 * @brief Pause a module processing data.
+	 */
+	.stop = audio_module_template_stop,
+
+	/**
+	 * @brief The core data processing function in the dummy module.
+	 */
+	.data_process = audio_module_template_data_process,
+};
+
+/**
+ * @brief The set-up description for the LC3 decoder.
+ */
+struct audio_module_description audio_module_template_dept = {
+	.name = "Audio Module Temp",
+	.type = AUDIO_MODULE_TYPE_IN_OUT,
+	.functions = &audio_module_template_functions};
+
+/**
+ * @brief A private pointer to the template set-up parameters.
+ */
+struct audio_module_description *audio_module_template_description = &audio_module_template_dept;

tests/subsys/audio/audio_module_template/CMakeLists.txt

@@ -0,0 +1,17 @@
+#
+# Copyright (c) 2024 Nordic Semiconductor ASA
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project("Audio module Template")
+
+target_sources(app PRIVATE
+	src/main.c
+	src/template_test.c
+)
+
+target_include_directories(app PRIVATE ${ZEPHYR_NRF_MODULE_DIR}/subsys/audio/audio_module_template)

tests/subsys/audio/audio_module_template/prj.conf

@@ -0,0 +1,17 @@
+#
+# Copyright (c) 2024 Nordic Semiconductor ASA
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+CONFIG_ZTEST=y
+CONFIG_ZTEST_STACK_SIZE=8196
+CONFIG_IRQ_OFFLOAD=y
+CONFIG_DATA_FIFO=y
+CONFIG_AUDIO_MODULE=y
+CONFIG_AUDIO_MODULE_TEMPLATE=y
+
+# The large stack size can be optimized
+CONFIG_MAIN_STACK_SIZE=16000
+
+CONFIG_STACK_SENTINEL=y

tests/subsys/audio/audio_module_template/src/main.c

@@ -0,0 +1,11 @@
+/*
+ * Copyright (c) 2024 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+
+#include <zephyr/fff.h>
+#include <zephyr/ztest.h>
+#include <errno.h>
+
+ZTEST_SUITE(suite_audio_module_template, NULL, NULL, NULL, NULL, NULL);