audio_api.h¶

SPARK Audio Core Application Programming Interface.

Copyright: Copyright (C) 2021 SPARK Microsystems International Inc. All rights reserved.
License: This source code is proprietary and subject to the SPARK Microsystems Software EULA found in this package in file EULA.txt.
Author: SPARK FW Team.

Defines

AUDIO_NO_ARG 0¶: Definition to use when no arguments are used if audio core calls

AUDIO_PACKET_HEADER_OFFSET 0¶: Position of the audio header in the audio packet

AUDIO_PACKET_DATA_OFFSET sizeof(audio_header_t)¶: Position of the packet data in the audio packet

AUDIO_PRODUCER_QUEUE_SIZE 3¶: Queue size to use when initializing a producer audio endpoint

audio_node_get_header(node) ((audio_header_t *)(queue_get_data_ptr(node, AUDIO_PACKET_HEADER_OFFSET)))¶: Macro used to get a pointer to the audio header in the audio packet

audio_node_get_data(node) ((uint8_t *)(queue_get_data_ptr(node, AUDIO_PACKET_DATA_OFFSET)))¶: Macro used to get a pointer to the packet data in the audio packet

Typedefs

typedef struct cdc_instance cdc_instance_t¶: CDC Instance.

typedef struct audio_header audio_header_t¶: Audio Header.

typedef struct processing_interface processing_interface_t¶: Processing Interface.

typedef struct audio_processing audio_processing_t¶: Audio Processing.

typedef struct endpoint_interface audio_endpoint_interface_t¶: Endpoint Interface.

typedef struct audio_endpoint_cfg audio_endpoint_cfg_t¶: Audio Endpoint Configuration.

typedef struct audio_endpoint audio_endpoint_t¶: Audio Endpoint.

typedef struct audio_protocol_cfg audio_protocol_cfg_t¶: Audio Protocol Configuration.

typedef struct audio_statistics audio_statistics_t¶: Audio Statistics.

typedef struct audio_pipeline audio_pipeline_t¶: Audio Pipeline.

Functions

void audio_core_init(queue_critical_cfg_t queue_critical, uint8_t *queue_memory, uint32_t queue_memory_size)¶

Initialize the Audio Core.

Parameters

queue_critical – [in] Critical section functions.
queue_memory – [in] Pointer to allocated queue memory.
queue_memory_size – [in] Size of allocated queue memory.

audio_pipeline_t *audio_pipeline_init(const char *name, audio_endpoint_t *producer, audio_protocol_cfg_t cfg, audio_endpoint_t *consumer, audio_error_t *err)¶

Initialize an audio pipeline.

Parameters

name – [in] Name of the pipeline.
producer – [in] Producer endpoint.
cfg – [in] Protocol configuration.
consumer – [in] Consumer endpoint.
err – [out] Error code.

Returns

Reference to the initialized audio pipeline.

audio_endpoint_t *audio_endpoint_init(void *instance, const char *name, audio_endpoint_interface_t iface, audio_endpoint_cfg_t cfg, audio_error_t *err)¶

Initialize an audio endpoint.

Parameters

instance – [in] Endpoint instance.
name – [in] Name of the endpoint.
iface – [in] Interface of the endpoint.
cfg – [in] Endpoint configuration.
err – [out] Error code.

Returns

Reference to the initialized endpoint.

audio_processing_t *audio_processing_stage_init(void *instance, const char *name, processing_interface_t iface, audio_error_t *err)¶

Initialize an audio processing stage.

Parameters

instance – [in] Processing stage instance.
name – [in] Name of the processing stage.
iface – [in] Interface of the processing stage.
err – [out] Error code.

Returns

Reference to the initialized processing stage.

void audio_pipeline_add_processing(audio_pipeline_t *pipeline, audio_processing_t *process)¶

Add a processing stage to the pipeline.

Parameters

pipeline – [in] Pipeline instance.
process – [in] Pointer to processing structure.

void audio_pipeline_add_extra_consumer(audio_pipeline_t *pipeline, audio_endpoint_t *next_consumer)¶

Add an extra consumer endpoint to the pipeline.

Parameters

pipeline – [in] Pipeline instance.
next_consumer – [in] Extra consumer endpoint.

void audio_pipeline_setup(audio_pipeline_t *pipeline, audio_error_t *err)¶

Setup the audio pipeline.

This makes the pipeline ready to use. It must be called last, after every other initialization functions.

Parameters

pipeline – [in] Pipeline instance.
err – [out] Error code.

void audio_pipeline_start(audio_pipeline_t *pipeline)¶

Start the audio pipeline.

Parameters: pipeline – [in] Pipeline instance.

void audio_pipeline_stop(audio_pipeline_t *pipeline)¶

Stop the audio pipeline.

Parameters: pipeline – [in] Pipeline instance.

uint32_t audio_processing_ctrl(audio_processing_t *audio_processing, uint8_t cmd, uint32_t arg)¶

Execute process specific control.

Parameters

audio_processing – Audio processing structure.
cmd – [in] Command specific to the processing stage.
arg – [in] Argument specific to the processing stage.

Returns

A value specific to the control function.

void audio_pipeline_process(audio_pipeline_t *pipeline, audio_error_t *err)¶

Execute the audio processing stages.

Parameters

pipeline – [in] Pipeline instance.
err – [out] Error code.

void audio_pipeline_produce(audio_pipeline_t *pipeline, audio_error_t *err)¶

Execute the produce endpoint.

Parameters

pipeline – [in] Pipeline instance.
err – [out] Error code.

void audio_pipeline_consume(audio_pipeline_t *pipeline, audio_error_t *err)¶

Execute the consumer endpoint(s).

Parameters

pipeline – [in] Pipeline instance.
err – [out] Error code.

void audio_pipeline_consume_all(audio_pipeline_t *pipeline, audio_error_t *err)¶

Execute all the consume endpoints that contain data in their queue.

Parameters

pipeline – [in] Pipeline instance.
err – [out] Error code.

audio_statistics_t *audio_pipeline_get_stats(audio_pipeline_t *pipeline)¶

Get the audio stats.

Parameters: pipeline – [in] Pipeline instance.
Returns: Pointer to audio stats structure.

uint32_t audio_pipeline_get_producer_buffer_load(audio_pipeline_t *pipeline)¶

Get producer buffer load.

Parameters: pipeline – [in] Pipeline instance.
Returns: buffer producer load value

uint32_t audio_pipeline_get_consumer_buffer_load(audio_pipeline_t *pipeline)¶

Get consumer buffer load.

Parameters: pipeline – [in] Pipeline instance.
Returns: Consumer buffer load value.

uint32_t audio_pipeline_get_consumer_buffer_overflow_count(audio_pipeline_t *pipeline)¶

Get consumer buffer overflow count.

Parameters: pipeline – [in] Pipeline instance.
Returns: Consumer buffer overflow counter.

uint32_t audio_pipeline_get_consumer_buffer_underflow_count(audio_pipeline_t *pipeline)¶

Get consumer buffer underflow count.

Parameters: pipeline – [in] Pipeline instance.
Returns: Consumer buffer underflow counter.

void audio_pipeline_reset_stats(audio_pipeline_t *pipeline)¶

Reset the audio stats.

Parameters: pipeline – [in] Pipeline instance.

uint32_t audio_core_get_allocated_bytes(void)¶

Get the number of bytes allocated in the memory pool.

Returns: Number of bytes allocated in the memory pool.

struct cdc_instance¶

#include <audio_api.h>

CDC Instance.

Public Members

resampling_instance_t resampling_instance¶: An instance of the resampling

uint8_t size_of_buffer_type¶: Number of bytes per audio sample

uint8_t *avg_arr¶: An circular array of tx queue lengths used for averaging

uint32_t avg_sum¶: Rolling average of the avg_arr

uint32_t avg_val¶: Normalized average of avg_sum to increase resolution

uint32_t count¶: Used to ensure a minimum number of queue length samples before determining a resampling action

uint16_t avg_idx¶: Index into the avg_arr

uint8_t max_queue_offset¶: Trigger level to determine whether to take a resampling action

uint32_t normal_queue_size¶: Normalized queue size to increase trigger resolution

uint16_t queue_avg_size¶: Size of the averaging array avg_arr

bool wait_for_queue_full¶: Set due to feedback from audio source that its tx queue is full. This will pause any resampling activity until the audio source tx queue has emptied.

struct audio_header¶

#include <audio_api.h>

Audio Header.

Public Members

uint8_t tx_queue_level_high¶: For clock drift compensation. Used by the recorder to notify the player that its TX audio buffer is filling up

uint8_t user_data_is_valid¶: Indicates if the audio packet trailling byte is a valid user data byte

uint8_t reserved¶: Reserved for future use

uint8_t payload_size¶: Size of the payload (audio samples) expressed in bytes

struct processing_interface¶

#include <audio_api.h>

Processing Interface.

Public Members

void (*init)(void *instance, mem_pool_t *mem_pool)¶: Function the audio core uses to execute any processing stage initialization sequence

void (*deinit)(void *instance)¶: Function the audio core uses to execute any processing stage de-initialization sequence

uint32_t (*ctrl)(void *instance, uint8_t cmd, uint32_t args)¶: Function the audio application uses to interact with the processing stage

uint8_t (*process)(void *instance, audio_header_t *header, uint8_t *data_in, uint8_t size, uint8_t *data_out)¶: Function the audio core uses to do processing on audio samples

struct audio_processing¶

#include <audio_api.h>

Audio Processing.

Public Members

void *instance¶: Pointer to the processing stage’s specific instance

const char *name¶: Character string describing the processing stage

processing_interface_t iface¶: Interface the processing stage must comply to

struct audio_processing *next_process¶: Pointer to the next processing state

struct endpoint_interface¶

#include <audio_api.h>

Endpoint Interface.

Public Members

uint8_t (*action)(void *instance, uint8_t *samples, uint8_t size)¶: Function the audio core uses to send or receive audio samples depending if the endpoint produces or consumes

void (*start)(void *instance)¶: Function the audio core uses to execute any endpoint startup sequence

void (*stop)(void *instance)¶: Function the audio core uses to stop any endpoint operations

struct audio_endpoint_cfg¶

#include <audio_api.h>

Audio Endpoint Configuration.

Public Members

bool use_encapsulation¶: True if the endpoint produces or consumes audio packets (audio header + audio payload), False for only audio payloads (audio samples)

bool delayed_action¶: True if the endpoint requires a complete cycle to produce or consume data. False if the endpoint produces or consumes instantly

uint8_t channel_count¶: 1 if the endpoint produces or consumes mono audio payloads and 2 for interleaved stereo

uint8_t bit_depth¶: Bit depth of samples the endpoint produces or consumes

uint8_t audio_payload_size¶: Size in bytes of the audio payload

uint8_t queue_size¶: Size in number of audio packets the endpoint’s queue can contain

struct audio_endpoint¶

#include <audio_api.h>

Audio Endpoint.

Public Members

void *instance¶: Pointer to endpoint’s specific instance

const char *name¶: Character string describing the endpoint

audio_endpoint_interface_t iface¶: Interface the endpoint must comply to

audio_endpoint_cfg_t cfg¶: Audio endpoint configuration

struct audio_endpoint *next_endpoint¶: Pointer to the next endpoint

queue_t _queue¶: Internal: queue the endpoint will use to store or retrieve audio packets

queue_t *_free_queue¶: Internal: Pointer to the free queue the endpoint will retrieve free nodes from

queue_node_t *_current_node¶: Internal: pointer to the queue node the endpoint is working with at the moment

bool _buffering_complete¶: Internal: Whether or not the initial audio buffering has been completed

struct audio_protocol_cfg¶

#include <audio_api.h>

Audio Protocol Configuration.

Public Members

bool cdc_enable¶: Enable the clock drift compensation on the pipeline

uint16_t cdc_resampling_length¶: Amount of samples used when resampling. Can be ignored if CDC is not enabled.

uint16_t cdc_queue_avg_size¶: Amount of measurements used when averaging the consumer queue size. Can be ignored if CDC is not enabled.

bool do_initial_buffering¶: Wait for the consumer queue (TX audio buffer) to be full before starting to consume

bool user_data_enable¶: Set to true if using User Data processing, false otherwise

struct audio_statistics¶

#include <audio_api.h>

Audio Statistics.

Public Members

uint32_t producer_buffer_load¶: Number audio packets currently in the producer queue

uint16_t producer_buffer_size¶: Maximum number audio packets the producer queue can hold

uint32_t consumer_buffer_load¶: Number audio packets currently in the consumer queue

uint16_t consumer_buffer_size¶: Maximum number audio packets the consumer queue can hold

uint32_t consumer_buffer_overflow_count¶: Number of times the consumer queue has overflowed

uint32_t consumer_buffer_underflow_count¶: Number of times the consumer queue has underflowed

struct audio_pipeline¶

#include <audio_api.h>

Audio Pipeline.

Public Members

const char *name¶: Name of the pipeline

audio_endpoint_t *producer¶: Pointer to the audio endpoint that will produce audio samples to this audio pipeline

audio_processing_t *process¶: List of processing stages that will sequentially be used on the produced samples before they are consumed

audio_endpoint_t *consumer¶: Pointer to the audio endpoint that will consume audio samples from this audio pipeline

audio_protocol_cfg_t cfg¶: Audio protocol configuration

audio_statistics_t _statistics¶: Audio-specific statistics

uint8_t _buffering_threshold¶: Internal: The number of audio packets to buffer before considering the initial buffering complete

uint8_t _user_data_size¶: Internal: Set to 0 or 1 depending on cfg->enable_user_data

cdc_instance_t *_cdc_instance¶: Internal: CDC instance for this pipeline