Audio Core API¶

The Audio Core API is the set of public functions that applications can use to access the Audio Core functionalities.

Initialization¶

The Audio Core initialization steps are the same for every application. Only the configuration supplied at each step is different depending on specific application needs. Here is a flowchart of the whole initialization process.

Audio Core Configuration¶

typedef struct sac_cfg {
    uint8_t *memory_pool;    /*!< Memory pool instance from which memory allocation is done */
    size_t memory_pool_size; /*!< Memory pool size in bytes */
} sac_cfg_t;

memory_pool: This is the chunk of memory the Audio Core uses when creating (or allocating) structures like the ones for the pipelines, endpoints and processing stages as well as the audio buffers. It works much like the C Heap, and enables the Audio Core to internally manage the memory.
memory_pool_size: This is the size in bytes of the memory pool.

Audio Pipeline Configuration¶

typedef struct sac_pipeline_cfg {
    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 */
} sac_pipeline_cfg_t;

cdc_enable: This controls if additional memory is allocated or not for the pipeline’s consumer endpoint’s audio buffer to support audio clock drifting compensation. This is required when using the CDC processing stage supplied with the Audio Core. If set to true, the audio buffer capacity is increased by 3 audio packets. See Clock Drift Compensation for more details.
do_initial_buffering: This controls if initial buffering is enabled or not. If set to true, the endpoint’s consumer queue needs to completely fill up once before the endpoint starts consuming audio packets from it. Its purpose is to build the wireless system’s audio latency. It must be enabled on the audio pipeline transmitting audio over-the-air (i.e. the pipeline that has the Wireless Core endpoint as consumer).
user_data_enabled: This controls if data can be appended to audio packets or not. If set to true, the audio user data processing stage can be used to append and retrieve data to/from the audio packet. See User Data for more details.
mixer_option: This controls the audio pipeline’s audio mixing behavior. If input_mixer_pipeline is set to true, it means the audio pipeline audio stream is to be mixed with another one. If output_mixer_pipeline is set to true, it means the audio pipeline will be mixing audio streams. Both option are mutually exclusive. If a regular audio pipeline is desired (i.e. without audio mixing), both options must be set to false.

Audio Endpoint Configuration¶

typedef struct sac_endpoint_cfg {
    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 */
} sac_endpoint_cfg_t;

use_encapsulation: This is to specify if the endpoint deals with encapsulated audio samples or not. For example, a regular hardware audio codec will not produce nor consume encapsulated audio samples but the SPARK Wireless Core will.
delayed_action: This is to specify if the endpoint produces or consumes audio samples instantly or not. In general, an endpoint that uses DMA for audio samples transfers will have delayed_action set to true because after returning from a call to sac_pipeline_produce() or sac_pipeline_consume(), the audio samples transfer will not have completed yet. If using the SPARK Wireless Core endpoints supplied with the SPARK SDK, this settings must be set to false.
channel_count: This is the number of audio channels the endpoint produces or consumes. For mono, this must be set to 1. For interleaved stereo, this must be set to 2.
bit_depth: This is the bit depth of the audio samples the endpoint produces or consumes. Valid values are SAC_16BITS, SAC_20BITS and SAC_24BITS.
audio_payload_size: This is the size of an audio payload in bytes. For example, if an endpoint produces 20 16-bit samples, this value would be set to 40. Note that if the bit depth is higher than 16 bits (i.e. 20 or 24 bits), the audio_payload_size must take into account the required padding (internal processing will be done on 32-bit values). For example, if an endpoint produces those same 20 samples, but with a bit depth of 24 bits, this value would be set to 80 instead of 40 (20 * 4 bytes).
queue_size: This is the size of the audio buffer in number of audio packets. For a consumer endpoint, this represents most of the latency of the audio pipeline. For a producer endpoint, this represents the size of the queue used for audio processing and should always be set to SAC_PRODUCER_QUEUE_SIZE unless there is a specific reason to increase it.

Hardware Abstraction Layer¶

The Hardware Abstraction Layer (HAL) is the set of hardware-dependent functions needed by the Audio Core to operate.

typedef struct sac_hal {
    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 */
} sac_hal_t;

enter_critical: This is the function called by the Audio Core when it enters a critical section of the code that must not be interrupted. This function needs to disable all interrupts.
exit_critical: This is the function called by the Audio Core when it leaves a critical section of the code that must not be interrupted. This functions needs to re-enable all interrupts disabled by enter_critical.

Statistics¶

The Audio Core provides pipeline-level statistics that the application can use to monitor the status of the payloads it sends and receives. The available statistics are as follows:

typedef struct sac_statistics {
    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 */
} sac_statistics_t;

To refresh the statistics, the following function must be called:

sac_statistics_t *sac_pipeline_update_stats(sac_pipeline_t *pipeline);

This function returns a pointer to the statistics for direct manipulation by the application. The following code snippet gives an example on how to access the consumer_buffer_overflow_count counter:

uint32_t buf_overflow;
sac_statistics_t *stats;

stats = sac_pipeline_update_stats(pipeline);

buf_overflow = stats->consumer_buffer_overflow_count;

To reset the statistics, the user can simply call:

void sac_pipeline_reset_stats(sac_pipeline_t *pipeline);

This will reset all the statistics counters to 0. If using the Audio Core in a wireless application, resetting the statistics just after the link has synchronized is recommended as accumulated statistics prior to that point are mostly irrelevant.

Finally, a function that formats a string with all the available statistics is available:

int sac_pipeline_format_stats(sac_pipeline_t *pipeline, char *buffer, uint16_t size);

This functions adds the pipeline’s name to the string in order to separate the statistics by pipeline. This is particularly useful on systems using many pipelines. Before calling sac_pipeline_format_stats(), the statistics must be updated with sac_pipeline_update_stats() as shown in the following example:

char stats_string[500];

sac_pipeline_update_stats(pipeline);
sac_pipeline_format_stats(pipeline, stats_string, sizeof(stats_string));
puts(stats_string);

Reference¶

sdk_spark_vx.y.z/
└── core/
    └── audio/
        ├── sac_api.h
        ├── sac_error.h
        └── sac_stats.h

File name	Description
sac_api.h	The API itself. This header file must be included in the user’s application in order to use the Audio Core.
sac_error.h	Audio Core error codes.
swc_stats.h	Audio Core statistics module.