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¶: Definition to use when no arguments are used if audio core calls

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_PRODUCER_QUEUE_SIZE 3¶: Queue size to use when initializing a producer audio endpoint

SAC_TXQ_ARR_LEN 3¶: Array size holding tx queue len values to determine a rolling average

SAC_LINK_MARGIN_SIZE_BYTES 1¶: Number of bytes for the link margin data

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¶: Audio Core Fallback Module Configuration.

typedef enum sac_fallback_state sac_fallback_state_t¶: Fallback State.

typedef struct sac_txq_metrics sac_txq_metrics_t¶: TX Queue Metrics.

typedef struct sac_link_margin_metrics sac_link_margin_metrics_t¶: Link Margin Metrics.

typedef struct sac_cca_metrics sac_cca_metrics_t¶

typedef struct sac_fallback_module sac_fallback_module_t¶: Audio Core Fallback Module.

Enums

enum sac_bit_depth¶

Audio Core Bit Depth.

Values:

enumerator SAC_16BITS = 16¶: 16-bit PCM samples

enumerator SAC_20BITS = 20¶: 20-bit PCM samples

enumerator SAC_24BITS = 24¶: 24-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_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

enum sac_fallback_state¶

Fallback State.

Values:

enumerator FB_STATE_NORMAL¶: Normal state, monitor txq for switch to wait threshold

enumerator FB_STATE_WAIT_THRESHOLD¶: Link degrading, measure link margin for ~1/4 sec to determine return from fallback threshold

enumerator FB_STATE_FALLBACK¶: Fallback mode due to degraded link, monitor link margin for return to normal mode

enumerator FB_STATE_FALLBACK_DISCONNECT¶: Fallback mode due to disconnected link, threshold set to fixed value, monitor link margin for return to normal mode

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.

Note

Only call this initialization when the Fallback Module is needed.

Parameters

cfg – [in] Configuration of the SAC Fallback 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)¶

Add a processing stage to the pipeline.

Parameters

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

void sac_pipeline_add_extra_consumer(sac_pipeline_t *pipeline, sac_endpoint_t *next_consumer)¶

Add an extra consumer endpoint to the pipeline.

Parameters

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

void sac_pipeline_add_extra_producer(sac_pipeline_t *pipeline, sac_endpoint_t *next_producer)¶

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.

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 – [in] 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)¶

Start the Audio Core pipeline.

Parameters: pipeline – [in] Pipeline instance.

void sac_pipeline_stop(sac_pipeline_t *pipeline)¶

Stop the Audio Core pipeline.

Parameters: pipeline – [in] Pipeline instance.

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 user_data_is_valid¶: Indicates if the audio packet trailing byte is a valid user data byte

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

void (*deinit)(void *instance, sac_pipeline_t *pipeline, sac_error_t *err)¶: Function the audio core uses to execute any processing stage de-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_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

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

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_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]¶: Pipepline 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

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

uint32_t _samples_buffered_size¶: Internal: Size in bytes of samples produced but not yet consumed

struct sac_fallback_module_cfg¶

#include <sac_api.h>

Audio Core Fallback Module Configuration.

Public Members

bool is_tx_device¶: True if the device is the tx device on the fallback connection

uint8_t link_margin_threshold¶: Default lm threshold

uint8_t link_margin_threshold_hysteresis¶: Threshold hysteresis

sac_pipeline_t *pipeline¶: Fallback pipeline

uint32_t txq_max_size¶: Max TX queue size

uint32_t link_margin_conn_packets_per_second¶: Number of packets per second on the link margin connection

uint32_t main_conn_packets_per_second¶: Number of packets per second on the main connection

uint16_t cca_max_try_count¶: CCA max try count

uint32_t txq_buffer_load_threshold¶: TX queue load above which fallback is triggered. Value should be multiplied by 10. (ex: 1.3 is 13)

struct sac_txq_metrics¶

#include <sac_api.h>

TX Queue Metrics.

Public Members

uint8_t txq_len_arr[SAC_TXQ_ARR_LEN]¶: TX queue length averaging array

uint8_t txq_len_arr_idx¶: TX queue size averaging array index

uint16_t txq_len_sum¶: TX queue len rolling average sum

uint8_t txq_len_avg¶: Tx queue len rolling average

struct sac_link_margin_metrics¶

#include <sac_api.h>

Link Margin Metrics.

Public Members

uint32_t link_margin_accumulator¶: Accumulation of link margin values over a nominal 1/4 sec

uint16_t link_margin_accumulator_count¶: Number of link margin values accumulated

uint8_t link_margin_acc_avg¶: Link margin average calculated from accumulator

uint8_t link_margin_count¶: Number of link margin values above the threshold

struct sac_cca_metrics¶

Public Members

uint32_t cca_fail_count_max¶: Max fail count possible over sampling period, based on packets per second

uint32_t cca_fail_count_threshold¶: Threshold under which link is considered good for switch back to normal

uint32_t cca_fail_count_start¶: Start count of CCA fail count to determine if link is good for switch to normal

uint32_t cca_fail_count_current¶: Sample of CCA fail count

uint16_t cca_fail_acc_count¶: Number of CCA fail count values below the threshold

uint32_t cca_fail_count_value¶: CCA fail count averaged over the sampling period

struct sac_fallback_module¶

#include <sac_api.h>

Audio Core Fallback Module.

Public Members

uint8_t fallback_threshold¶: Current link margin threshold to return to normal

uint8_t fallback_threshold_default¶: Default link margin threshold

uint8_t fallback_threshold_hysteresis¶: Link margin threshold hysteresis

uint16_t lm_packets_per_sampling_period¶: Number of audio packets per 250 ms

sac_fallback_state_t fallback_state¶: Fallback state

uint32_t fallback_count¶: Number of times fallback was triggered

sac_pipeline_t *pipeline¶: Pipeline where fallback will be applied

uint32_t txq_max_size¶: Max size of the tx queue

bool fallback_flag¶: Fallback mode flag

bool rx_link_margin_data_valid¶: Flag indicating that rx_link_margin_data_rx data is valid

uint8_t rx_link_margin_data_rx¶: Link margin data from the node

sac_txq_metrics_t txq_metrics¶: TX queue metrics

sac_link_margin_metrics_t link_margin_metrics¶: Link margin metrics

sac_cca_metrics_t cca_metrics¶: CCA metrics

uint32_t txq_buffer_load_threshold¶: TX queue load above which fallback is triggered. Value should be multiplied by 10. (ex: 1.3 is 13)