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.

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