User function definitions

The following functions can be defined by an application using lib_xua.

Note

Default, empty, implementations of these functions are provided in lib_xua. These are marked as weak symbols so the application can simply define its own version of them.

External audio hardware configuration functions

The following functions can be optionally used by the design to configure external audio hardware. As a minimum, in most applications, it is expected that a implementation of AudioHwConfig() will need to be provided.

void AudioHwInit(void)

User audio hardware initialisation code.

This function is called when the device starts up and should contain user code to perform any required audio hardware initialisation

void AudioHwConfig(
unsigned samFreq,
unsigned mClk,
unsigned dsdMode,
unsigned sampRes_DAC,
unsigned sampRes_ADC,
)

User audio hardware configuration code.

This function is called when on sample rate change and should contain user code to configure audio hardware (clocking, CODECs etc) for a specific mClk/Sample frequency. It is called from audiohub on XUA_AUDIO_IO_TILE_NUM.

Parameters:

  • samFreq – The new sample frequency (in Hz)

  • mClk – The new master clock frequency (in Hz)

  • dsdMode – DSD mode, DSD_MODE_NATIVE, DSD_MODE_DOP or DSD_MODE_OFF

  • sampRes_DAC – Playback sample resolution (in bits)

  • sampRes_ADC – Record sample resolution (in bits)

void AudioHwConfig_Mute(void)

User code mute audio hardware.

This function is called before AudioHwConfig() and should contain user code to mute audio hardware before a sample rate change in order to reduced audible pops/clicks It is called from audiohub on XUA_AUDIO_IO_TILE_NUM.

Note, if using the application PLL of a xcore.ai device this function will be called before the master-clock is changed

void AudioHwConfig_UnMute(void)

User code to un-mute audio hardware.

This function is called after AudioHwConfig() and should contain user code to un-mute audio hardware after a sample rate change. It is called from audiohub on XUA_AUDIO_IO_TILE_NUM.

void AudioHwShutdown(void)

User audio hardware de-initialisation code.

This function is called when streaming stops (device enumerated but audio is idle) and should contain user code to perform any required audio hardware de-initialisation. This can be useful for saving power in the audio sub-system. It is called from audiohub on XUA_AUDIO_IO_TILE_NUM.

Note this callback will only be called if the XUA_LOW_POWER_NON_STREAMING define is set, otherwise lib_xua assumes that I2S is always looping.

Audio stream start/stop functions

The following functions can be optionally used by the design. They can be useful for mute lines etc.

void UserAudioStreamState(int inputActive, int outputActive)

User stream start code.

User code to perform any actions required at every stream start - either input or output.

/param inputActive An input stream is active if 1, else inactive if 0 /param OutputActive An output stream is active if 1, else inactive if 0

Host active functions

The following function can be used to signal that the device is connected to a valid host.

void UserHostActive(int active)

User host active code.

This function can be used to perform user defined actions based on host present/not-present events. This function is called on a change in state.

Parameters:

  • active – Indicates if the host is active or not. 1 for active, else 0

HID controls

The following function is called when the device wishes to read physical user input (buttons etc). The function should write relevant HID bits into this array. The bit ordering and functionality is defined by the HID report descriptor used.

size_t UserHIDGetData(
const unsigned id,
unsigned char hidData[HID_MAX_DATA_BYTES],
)

Get the data for the next HID Report.

Parameters:

  • id – [in] The HID Report ID (see 5.6, 6.2.2.7, 8.1 and 8.2 of the USB Device Class Definition for HID 1.11) Set to zero if the application provides only one HID Report which does not include a Report ID

  • hidData – [out] The HID data If using Report IDs, this function places the Report ID in the first element; otherwise the first element holds the first byte of HID event data.

Return values:

Zero – means no new HID event data has been recorded for the given id

Returns:

The length of the HID Report in the hidData argument

PDM Mics user callback functions

Two weak callback APIs are provided which optionally allow user code to be executed at startup (before PDM microphone initialisation) and after each PCM sample is received. These can be useful for custom hardware initialisation required by the PDM microphone or post processing such as gain control before samples are forwarded to XUA

void xua_user_pdm_init(unsigned channel_map[MIC_ARRAY_CONFIG_MIC_COUNT])

User pre-PDM mic function callback (optional).

This function is called before mic-array initialisation—both the first time and every time the mic array restarts. It can be used to update the channel_map in cases where the mapping between PDM input port pins and microphone output channels is not 1:1. It may also be used to initialise any PDM related hardware.

Note

This function is called on the same tile as the mic-array task (XUA_MIC_PDM_TILE_NUM). channel_map is a global array whose default initialisation occurs on that tile before mic_array_task() runs. xua_user_pdm_init() is invoked by mic_array_task() itself, before starting the mic-array hardware thread.

void xua_user_pdm_process(int32_t mic_audio[MIC_ARRAY_CONFIG_MIC_COUNT])

USB PDM Mic PCM sample post processing callback (optional).

This is called after a PCM sample is received from mic_array. It can be used to modify the samples (gain, filter etc.) before sending to XUA audiohub.

Warning

This function is called from Audiohub (I2S) and so any processing must take significantly less than half of a sample period else I2S will break timing.

Parameters:

  • mic_audio – Array of samples for in-place processing