audio_module.h

Go to the documentation of this file.

/*
 * Copyright(c) 2023 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
 */
 
#ifndef _AUDIO_MODULE_H_
#define _AUDIO_MODULE_H_
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <zephyr/kernel.h>
#include <data_fifo.h>
 
#include "audio_defines.h"
 
#define AUDIO_MODULE_PARAMETERS(p, dest, stk, stk_size, pri, fifo_rx, fifo_tx, slab, slab_size)    \
        (p).description = (dest);                                                                  \
        (p).thread.stack = (stk);                                                                  \
        (p).thread.stack_size = (stk_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);
 
#define AUDIO_MODULE_LOCATIONS_NUM (32)
 
enum audio_module_type {
        /* The module type is undefined. */
        AUDIO_MODULE_TYPE_UNDEFINED = 0,
 
        /* This is an input processing module.
         *
         * @note An input module obtains data internally within the
         *       module (e.g. I2S in) and hence has no RX FIFO.
         */
        AUDIO_MODULE_TYPE_INPUT,
 
        /* This is an output processing module.
         *
         * @note An output module takes audio data from an input or an in/out module.
         *       It then outputs data internally within the module (e.g. I2S out) and hence has no
         *       TX FIFO.
         */
        AUDIO_MODULE_TYPE_OUTPUT,
 
        /* This is a processing module.
         *
         * @note A processing module takes input from and outputs to another
         *       module, thus having RX and TX FIFOs.
         */
        AUDIO_MODULE_TYPE_IN_OUT
};
 
enum audio_module_state {
        /* Module state undefined. */
        AUDIO_MODULE_STATE_UNDEFINED = 0,
 
        /* Module is in the configured state. */
        AUDIO_MODULE_STATE_CONFIGURED,
 
        /* Module is in the running state. */
        AUDIO_MODULE_STATE_RUNNING,
 
        /* Module is in the stopped state. */
        AUDIO_MODULE_STATE_STOPPED
};
 
struct audio_data {
        /* A pointer to the raw or coded data (e.g., PCM, LC3, etc.) buffer. */
        void *data;
 
        /* The size in bytes of the data buffer.
         * To get the size of each channel, this value must be divided by the number of
         * used channels. Metadata is not included in this figure.
         */
        size_t data_size;
 
        /* Additional information describing the audio data.
         */
        struct audio_metadata meta;
};
 
struct audio_module_handle_private;
 
struct audio_module_context;
 
struct audio_module_configuration;
 
typedef void (*audio_module_response_cb)(struct audio_module_handle_private *handle,
                                         struct audio_data const *const audio_data);
 
struct audio_module_functions {
        int (*open)(struct audio_module_handle_private *handle,
                    struct audio_module_configuration const *const configuration);
 
        int (*close)(struct audio_module_handle_private *handle);
 
        int (*configuration_set)(struct audio_module_handle_private *handle,
                                 struct audio_module_configuration const *const configuration);
 
        int (*configuration_get)(struct audio_module_handle_private const *const handle,
                                 struct audio_module_configuration *configuration);
 
        int (*start)(struct audio_module_handle_private *handle);
 
        int (*stop)(struct audio_module_handle_private *handle);
 
        int (*data_process)(struct audio_module_handle_private *handle,
                            struct audio_data const *const audio_data_rx,
                            struct audio_data *audio_data_tx);
};
 
struct audio_module_description {
        /* The module base name. */
        char *name;
 
        /* The module type. */
        enum audio_module_type type;
 
        /* A pointer to the functions in the module. */
        const struct audio_module_functions *functions;
};
 
struct audio_module_thread_configuration {
        /* Thread stack. */
        k_thread_stack_t *stack;
 
        /* Thread stack size. */
        size_t stack_size;
 
        /* Thread priority. */
        int priority;
 
        /* A pointer to a module's audio data receiver FIFO, can be NULL. */
        struct data_fifo *msg_rx;
 
        /* A pointer to a module's audio data transmitter FIFO, can be NULL. */
        struct data_fifo *msg_tx;
 
        /* A pointer to the audio data buffer slab, can be NULL. */
        struct k_mem_slab *data_slab;
 
        /* Size of each memory data buffer in bytes that will be
         * taken from the audio data buffer slab. The size can be 0.
         */
        size_t data_size;
};
 
struct audio_module_parameters {
        /* The module's description. */
        struct audio_module_description *description;
 
        /* The module's thread setting. */
        struct audio_module_thread_configuration thread;
};
 
struct audio_module_handle {
        /* A NULL terminated string giving a unique name of this module's instance. */
        char name[CONFIG_AUDIO_MODULE_NAME_SIZE + 1];
 
        /* The module's description. */
        const struct audio_module_description *description;
 
        /* Current state of the module. */
        enum audio_module_state state;
 
        /* Thread ID. */
        k_tid_t thread_id;
 
        /* Thread data. */
        struct k_thread thread_data;
 
        /* Flag to indicate if the module should put its output audio data onto its TX FIFO. */
        bool use_tx_queue;
 
        /* List node (pointer to next audio module). */
        sys_snode_t node;
 
        /* A single linked-list of the destination handles the module is connected to. */
        sys_slist_t handle_dest_list;
 
        /* Number of destination modules. */
        uint8_t dest_count;
 
        /* Semaphore to count messages between modules and on a module's TX FIFO. */
        struct k_sem sem;
 
        /* Mutex to make the above destinations list thread safe. */
        struct k_mutex dest_mutex;
 
        /* Module's thread configuration. */
        struct audio_module_thread_configuration thread;
 
        /* Private context for the module. */
        struct audio_module_context *context;
};
 
struct audio_module_message {
        /* Audio data to input. */
        struct audio_data audio_data;
 
        /* Sending module's handle. */
        struct audio_module_handle *tx_handle;
 
        /* Callback for when the audio data has been consumed. */
        audio_module_response_cb response_cb;
};
 
int audio_module_open(struct audio_module_parameters const *const parameters,
                      struct audio_module_configuration const *const configuration,
                      char const *const name, struct audio_module_context *context,
                      struct audio_module_handle *handle);
 
int audio_module_close(struct audio_module_handle *handle);
 
int audio_module_reconfigure(struct audio_module_handle *handle,
                             struct audio_module_configuration const *const configuration);
 
int audio_module_configuration_get(struct audio_module_handle const *const handle,
                                   struct audio_module_configuration *configuration);
 
int audio_module_connect(struct audio_module_handle *handle_from,
                         struct audio_module_handle *handle_to, bool connect_external);
 
int audio_module_disconnect(struct audio_module_handle *handle,
                            struct audio_module_handle *handle_disconnect,
                            bool disconnect_external);
 
int audio_module_start(struct audio_module_handle *handle);
 
int audio_module_stop(struct audio_module_handle *handle);
 
int audio_module_data_tx(struct audio_module_handle *handle,
                         struct audio_data const *const audio_data,
                         audio_module_response_cb response_cb);
 
int audio_module_data_rx(struct audio_module_handle *handle, struct audio_data *audio_data,
                         k_timeout_t timeout);
 
int audio_module_data_tx_rx(struct audio_module_handle *handle_tx,
                            struct audio_module_handle *handle_rx,
                            struct audio_data const *const audio_data_tx,
                            struct audio_data *audio_data_rx, k_timeout_t timeout);
 
int audio_module_names_get(struct audio_module_handle const *const handle, char **base_name,
                           char *instance_name);
 
int audio_module_state_get(struct audio_module_handle const *const handle,
                           enum audio_module_state *state);
 
int audio_module_number_channels_calculate(uint32_t locations, int8_t *number_channels);
 
#ifdef __cplusplus
}
#endif
 
#endif /*_AUDIO_MODULE_H_ */