sac_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

SAC_MAX_CHANNEL_COUNT 2: Maximum of audio channels supported in audio core.

SAC_NO_ARG 0: Placeholder to be used in a sac_processing_ctrl function call when no arguments are required.

SAC_NODE_PAYLOAD_SIZE_OFFSET 0: Position of the audio payload in the audio packet.

SAC_NODE_PAYLOAD_SIZE_VAR_SIZE sizeof(uint16_t): Size of the audio payload variable.

SAC_PACKET_HEADER_OFFSET (SAC_NODE_PAYLOAD_SIZE_OFFSET + SAC_NODE_PAYLOAD_SIZE_VAR_SIZE): Position of the audio header in the audio packet.

SAC_PACKET_DATA_OFFSET (SAC_PACKET_HEADER_OFFSET + sizeof(sac_header_t)): Position of the packet data in the audio packet.

SAC_MIN_PRODUCER_QUEUE_SIZE 3: Minimum queue size to use when initializing a producer audio endpoint.

sac_node_get_payload_size(node) (*((uint16_t *)(queue_get_data_ptr(node, SAC_NODE_PAYLOAD_SIZE_OFFSET)))): Get the audio payload size in the audio packet.

sac_node_set_payload_size(node, payload_size) ((*((uint16_t *)(queue_get_data_ptr(node, SAC_NODE_PAYLOAD_SIZE_OFFSET)))) = (payload_size)): Set the audio payload size in the audio packet.

sac_node_get_header(node) ((sac_header_t *)(queue_get_data_ptr(node, SAC_PACKET_HEADER_OFFSET))): Get a pointer to the audio header in the audio packet.

sac_node_get_data(node) ((uint8_t *)(queue_get_data_ptr(node, SAC_PACKET_DATA_OFFSET))): Get a pointer to the packet data in the audio packet.

sac_align_data_size(current_size, type_to_align) (sizeof(type_to_align) - ((current_size) % sizeof(type_to_align))): Return an array size aligned on a specific type.

Typedefs

typedef struct sac_pipeline sac_pipeline_t: Audio Core Pipeline.

typedef struct sac_cfg sac_cfg_t: Audio Core Configuration.

typedef struct sac_hal sac_hal_t: Audio Core Hardware Abstraction Layer.

typedef enum sac_bit_depth sac_bit_depth_t: Audio Core Bit Depth.

typedef enum sac_word_size sac_word_size_t: Audio Core Word Size.

typedef struct sac_header sac_header_t: Audio Core Header.

typedef struct sac_processing_interface sac_processing_interface_t: Processing Interface.

typedef struct sac_processing sac_processing_t: Audio Core Processing.

typedef struct sac_endpoint_interface sac_endpoint_interface_t: Endpoint Interface.

typedef struct sac_mixer_option sac_mixer_option_t: Add Audio Core Mixer’s specific options when using pipelines to mix packets.

typedef struct sac_endpoint_cfg sac_endpoint_cfg_t: Audio Core Endpoint Configuration.

typedef struct sac_endpoint sac_endpoint_t: Audio Core Endpoint.

typedef struct sac_pipeline_cfg sac_pipeline_cfg_t: Audio Core Pipeline Configuration.

typedef struct sac_statistics sac_statistics_t: Audio Core Statistics.

typedef struct sac_fallback_module_cfg sac_fallback_module_cfg_t: Forward declaration of the fallback module configuration structure.

Enums

enum sac_bit_depth

Audio Core Bit Depth.

Values:

enumerator SAC_16BITS = 16: 16-bit PCM samples.

enumerator SAC_18BITS = 18: 18-bit PCM samples.

enumerator SAC_20BITS = 20: 20-bit PCM samples.

enumerator SAC_24BITS = 24: 24-bit PCM samples.

enumerator SAC_32BITS = 32: 32-bit PCM samples.

enum sac_word_size

Audio Core Word Size.

Values:

enumerator SAC_16BITS_BYTE = 2: 2-byte word for 16-bit PCM samples.

enumerator SAC_18BITS_BYTE = 4: 4-byte word for 18-bit PCM samples.

enumerator SAC_20BITS_BYTE = 4: 4-byte word for 20-bit PCM samples.

enumerator SAC_24BITS_BYTE = 4: 4-byte word for 24-bit PCM samples.

enumerator SAC_32BITS_BYTE = 4: 4-byte word for 32-bit PCM samples.

Functions

void sac_init(sac_cfg_t cfg, sac_hal_t *hal, sac_error_t *err)

Initialize the Audio Core.

Parameters:

cfg – [in] Audio Core configuration.
hal – [in] Board specific functions.
err – [out] Error code.

void sac_mixer_init(sac_mixer_module_cfg_t cfg, sac_error_t *err)

Initialize the SAC Mixer Module.

Note

Only call this initialization when the Mixer Module is needed.

Parameters:

cfg – [in] Configuration of the SAC Mixer Module.
err – [out] Error code.

void sac_fallback_init(sac_fallback_module_cfg_t *cfg, sac_error_t *err)

Initialize the SAC Fallback Module using the SAC mem_pool.

Note

Only call this initialization when the Fallback Module is needed.

Parameters:

cfg – [in] Pointer to the configuration of the module.
err – [out] Error code.

sac_pipeline_t *sac_pipeline_init(const char *name, sac_endpoint_t *producer, sac_pipeline_cfg_t cfg, sac_endpoint_t *consumer, sac_error_t *err)

Initialize a SAC pipeline.

Parameters:

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

Returns:

Reference to the initialized SAC pipeline.

sac_endpoint_t *sac_endpoint_init(void *instance, const char *name, sac_endpoint_interface_t iface, sac_endpoint_cfg_t cfg, sac_error_t *err)

Initialize an Audio Core 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.

void sac_endpoint_link(sac_endpoint_t *consumer, sac_endpoint_t *producer, sac_error_t *err)

Link the queue of a consumer endpoint with a producer endpoint.

Note

This feature is used for audio mixing.

Parameters:

consumer – [in] Consumer endpoint instance to be linked.
producer – [in] Producer endpoint instance to be linked.
err – [out] Error code.

sac_processing_t *sac_processing_stage_init(void *instance, const char *name, sac_processing_interface_t iface, sac_error_t *err)

Initialize an Audio Core 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 sac_pipeline_add_processing(sac_pipeline_t *pipeline, sac_processing_t *process, sac_error_t *err)

Add a processing stage to the pipeline.

Parameters:

pipeline – [in] Pipeline instance.
process – [in] Pointer to processing structure.
err – [out] Error code.

void sac_pipeline_add_extra_consumer(sac_pipeline_t *pipeline, sac_endpoint_t *next_consumer, sac_error_t *err)

Add an extra consumer endpoint to the pipeline.

Parameters:

pipeline – [in] Pipeline instance.
next_consumer – [in] Extra consumer endpoint.
err – [out] Error code.

void sac_pipeline_add_extra_producer(sac_pipeline_t *pipeline, sac_endpoint_t *next_producer, sac_error_t *err)

Add an extra producer endpoint to the pipeline.

Note

This feature is used for Audio Mixing.

Parameters:

pipeline – [in] Pipeline instance.
next_producer – [in] Extra producer endpoint.
err – [out] Error code.

void sac_pipeline_add_input_pipeline(sac_pipeline_t *pipeline, sac_pipeline_t *input_pipeline, sac_error_t *err)

Add an input pipeline to a pipeline doing audio mixing.

Parameters:

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

void sac_pipeline_setup(sac_pipeline_t *pipeline, sac_error_t *err)

Setup the Audio Core 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 sac_pipeline_start(sac_pipeline_t *pipeline, sac_error_t *err)

Start the Audio Core pipeline.

Parameters:

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

void sac_pipeline_stop(sac_pipeline_t *pipeline, sac_error_t *err)

Stop the Audio Core pipeline.

Parameters:

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

uint32_t sac_processing_ctrl(sac_processing_t *sac_processing, sac_pipeline_t *pipeline, uint8_t cmd, uint32_t arg, sac_error_t *err)

Execute process specific control.

Parameters:

sac_processing – SAC processing structure.
pipeline – [in] Pipeline instance.
cmd – [in] Command specific to the processing stage.
arg – [in] Argument specific to the processing stage.
err – [out] Error code.

Returns:

A value specific to the control function.

void sac_pipeline_process(sac_pipeline_t *pipeline, sac_error_t *err)

Execute the Audio Core processing stages.

Parameters:

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

void sac_pipeline_produce(sac_pipeline_t *pipeline, sac_error_t *err)

Execute the produce endpoint.

Parameters:

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

void sac_pipeline_consume(sac_pipeline_t *pipeline, sac_error_t *err)

Execute the consumer endpoint(s).

Parameters:

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

void sac_pipeline_consume_all(sac_pipeline_t *pipeline, sac_error_t *err)

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

Parameters:

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

uint32_t sac_get_allocated_bytes(void)

Get the number of bytes allocated in the memory pool.

Returns:: Number of bytes allocated in the memory pool.

struct sac_cfg

#include <sac_api.h>

Audio Core Configuration.

Public Members

uint8_t *memory_pool: Memory pool instance from which memory allocation is done.

size_t memory_pool_size: Memory pool size in bytes.

struct sac_hal

#include <sac_api.h>

Audio Core Hardware Abstraction Layer.

Public Members

void (*enter_critical)(void): Function the audio core uses to enter a critical section of the code.

void (*exit_critical)(void): Function the audio core uses to exit a critical section of the code.

struct sac_header

#include <sac_api.h>

Audio Core 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 fallback: Indicates a fallback packet.

uint8_t reserved: Reserved for future use.

uint8_t crc4: CRC4 of the header.

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

struct sac_processing_interface

#include <sac_api.h>

Processing Interface.

Public Members

void (*init)(void *instance, sac_pipeline_t *pipeline, mem_pool_t *mem_pool, sac_error_t *err): Function the audio core uses to execute any processing stage initialization sequence.

uint32_t (*ctrl)(void *instance, sac_pipeline_t *pipeline, uint8_t cmd, uint32_t args, sac_error_t *err): Function the audio application uses to interact with the processing stage.

uint16_t (*process)(void *instance, sac_pipeline_t *pipeline, sac_header_t *header, uint8_t *data_in, uint16_t size, uint8_t *data_out, sac_error_t *err): Function the audio core uses to do processing on audio samples.

bool (*gate)(void *instance, sac_pipeline_t *pipeline, sac_header_t *header, uint8_t *data_in, uint16_t size, sac_error_t *err): Function called by process_samples prior to process to determine if process will be executed or not.

struct sac_processing

#include <sac_api.h>

Audio Core Processing.

Public Members

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

const char *name: Character string describing the processing stage.

sac_processing_interface_t iface: Interface the processing stage must comply to.

struct sac_processing *next_process: Pointer to the next processing state.

struct sac_endpoint_interface

#include <sac_api.h>

Endpoint Interface.

Public Members

uint16_t (*action)(void *instance, uint8_t *samples, uint16_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 sac_mixer_option

#include <sac_api.h>

Add Audio Core Mixer’s specific options when using pipelines to mix packets.

Public Members

bool input_mixer_pipeline: True if it is the input pipeline of the mixing stage.

bool output_mixer_pipeline: True if it is the output pipeline of the mixing stage.

struct sac_endpoint_cfg

#include <sac_api.h>

Audio Core Endpoint Configuration.

Public Members

bool use_encapsulation: True if the endpoint produces or consumes audio packets (SAC 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.

sac_bit_depth_t bit_depth: Bit depth of samples the endpoint produces or consumes.

uint16_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 sac_endpoint

#include <sac_api.h>

Audio Core Endpoint.

Public Members

void *instance: Pointer to endpoint’s specific instance.

const char *name: Character string describing the endpoint.

sac_endpoint_interface_t iface: Interface the endpoint must comply to.

sac_endpoint_cfg_t cfg: SAC endpoint configuration.

struct sac_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 sac_endpoint::[anonymous] _internal

struct sac_pipeline_cfg

#include <sac_api.h>

Audio Core Pipeline Configuration.

Public Members

bool cdc_enable: Set to true if an audio clock drift compensation processing stage will be added to this pipeline.

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

sac_mixer_option_t mixer_option: Configure the pipeline with mixer’s specific options.

struct sac_statistics

#include <sac_api.h>

Audio Core Statistics.

Public Members

uint32_t producer_buffer_load: Number of audio packets currently in the producer queue.

uint16_t producer_buffer_size: Maximum number of audio packets the producer queue can hold.

uint32_t producer_buffer_overflow_count: Number of times the producer queue has overflowed.

uint32_t producer_packets_corrupted_count: Number of corrupted packets received from the coord.

uint32_t consumer_buffer_load: Number of audio packets currently in the consumer queue.

uint16_t consumer_buffer_size: Maximum number of 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.

uint32_t consumer_queue_peak_buffer_load: Consumer queue peak load.

uint32_t consumer_link_margin_min_peak: Consumer link margin min.

uint32_t consumer_cca_fail_count_peak: Consumer CCA count peak.

uint32_t cdc_inflated_packets_count: Number of packets inflated by the CDC.

uint32_t cdc_deflated_packets_count: Number of packets deflated by the CDC.

struct sac_pipeline

#include <sac_api.h>

Audio Core Pipeline.

Public Members

const char *name: Name of the pipeline.

sac_pipeline_t *input_pipeline[MAX_NB_OF_INPUTS]: Pipeline inputting audio samples when doing audio mixing.

sac_endpoint_t *producer: Pointer to the SAC endpoint that will produce audio samples to this SAC pipeline.

sac_processing_t *process: List of processing stages that will sequentially be produced samples before they are consumed.

sac_endpoint_t *consumer: Pointer to the SAC endpoint that will consume audio samples from this SAC pipeline.

sac_pipeline_cfg_t cfg: SAC pipeline configuration.

sac_statistics_t _statistics: SAC pipeline statistics.

uint8_t buffering_threshold: Internal: The number of audio packets to buffer before considering the initial buffering complete.

uint32_t samples_buffered_size: Internal: Size in bytes of samples produced but not yet consumed.

struct sac_pipeline::[anonymous] _internal