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 audio_header audio_header_t

typedef struct processing_interface processing_interface_t

typedef struct audio_processing audio_processing_t

typedef struct endpoint_interface audio_endpoint_interface_t

typedef struct audio_endpoint_cfg audio_endpoint_cfg_t

typedef struct audio_endpoint audio_endpoint_t

typedef struct audio_protocol_cfg audio_protocol_cfg_t

typedef struct audio_statistics audio_statistics_t

typedef struct audio_pipeline audio_pipeline_t

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 state.

• 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 consume endpoint.

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 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

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

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

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

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

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_consumer

Pointer to the next consumer

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

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

struct 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

Public Members

const char *name

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