User function definitions

The following functions can be optionally defined by an application to override default (empty) implementations in lib_xua.

External audio hardware configuration

The functions listed below should be implemented to configure external audio hardware.

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 AUDIO_IO_TILE.

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 AUDIO_IO_TILE.

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 AUDIO_IO_TILE.

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 AUDIO_IO_TILE.

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 streaming notification

The functions listed below can be useful for mute lines, indication LEDs 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

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