Configuration defines¶

An application using the USB audio framework needs to have defines set for configuration. Defaults for these defines are found in xua_conf_default.h.

These defines should be overridden in an optional header file xua_conf.h file or in the application’s CMakeLists.txt for the relevant build configuration.

This section fully documents all of the settable defines and their default values (where appropriate).

Code location (tile)¶

XUA_AUDIO_IO_TILE_NUM¶

Location (tile) of audio I/O.

The tile number to run the AudioHub() task. The location if automatically detected from ports in the XN file.

XUA_XUD_TILE_NUM¶

Location (tile) of audio I/O.

The tile number to run lib_xud tasks on.

XUA_MIDI_TILE_NUM¶

Location (tile) of MIDI I/O.

The tile number to run MIDI tasks on. The location if automatically detected from ports in the XN file.

XUA_SPDIF_TX_TILE_NUM¶

Location (tile) of SPDIF Tx.

The tile number to run the S/PDIF tx task on. The location if automatically detected from ports in the XN file.

XUA_MIC_PDM_TILE_NUM¶

Location (tile) of PDM Rx.

The tile number to run the PDM Mics tasks on. The location if automatically detected from ports in the XN file.

XUA_PLL_REF_TILE_NUM¶

Location (tile) of reference signal to CS2100.

The tile number to run the PLL reference clock task on. The location if automatically detected from ports in the XN file.

Channel counts¶

NUM_USB_CHAN_OUT¶: Number of output channels (host to device). Default: NONE (Must be defined by app)

NUM_USB_CHAN_IN¶: Number of input channels (device to host). Default: NONE (Must be defined by app)

I2S_CHANS_DAC¶

Number of I2S channels to DAC/CODEC. Must be a multiple of 2.

Default: NONE (Must be defined by app)

I2S_CHANS_ADC¶

Number of I2S channels from ADC/CODEC. Must be a multiple of 2.

Default: NONE (Must be defined by app)

Frequencies and clocks¶

MAX_FREQ¶

Max supported sample frequency for device (Hz).

Default: 192000Hz

MIN_FREQ¶

Min supported sample frequency for device (Hz).

Default: 44100Hz

DEFAULT_FREQ¶

Default device sample frequency. A safe default should be used.

Default: MIN_FREQ

MCLK_441¶

Master clock defines for 44100 rates (in Hz).

Default: NONE (Must be defined by app)

MCLK_48¶

Master clock defines for 48000 rates (in Hz).

Default: NONE (Must be defined by app)

XUA_USE_SW_PLL¶

Enable/disable the use of the secondary/application PLL for generating and recovering master-clocks. Only available on xcore.ai devices.

Default: Enabled (for xcore.ai devices)

Audio Class¶

AUDIO_CLASS¶

Legacy USB Audio Class version.

Default: 2 (Audio Class version 2.0)

Note: XUA_USB_AUDIO_CLASS_HS and XUA_USB_AUDIO_CLASS_FS are derived from this value. Setting these defines directly will override this value.

XUA_AUDIO_CLASS_HS¶

Audio class version to run at HS.

Default: AUDIO_CLASS

Note: Set to 0 for no operation at HS.

XUA_AUDIO_CLASS_FS¶

Audio class version to run at FS.

Default: AUDIO_CLASS

Note: Set to 0 for no operation at FS.

Feature configuration¶

I²S/TDM¶

CODEC_MASTER¶

Defines whether XMOS device runs as master (i.e. drives LR and Bit clocks)

0: XMOS is I2S master. 1: CODEC is I2s master.

Default: 0 (XMOS is master)

XUA_I2S_N_BITS¶

Number of bits per channel for I2S/TDM. Supported values: 16/32-bit.

Default: 32 bits

XUA_PCM_FORMAT¶

Format of PCM audio interface. Should be set to XUA_PCM_FORMAT_I2S or XUA_PCM_FORMAT_TDM.

Default: XUA_PCM_FORMAT_I2S

MIDI¶

MIDI¶: Enable MIDI functionality including buffering, descriptors etc. Default: DISABLED.

MIDI_RX_PORT_WIDTH¶: MIDI Rx port width (1 or 4bit). Default: 1.

S/PDIF¶

XUA_SPDIF_TX_EN¶: Enables SPDIF Tx. Default: 0 (Disabled)

SPDIF_TX_INDEX¶

Defines which output channels (stereo) should be output on S/PDIF. Note, Output channels indexed from 0.

Default: 0 (i.e. channels 0 & 1)

XUA_SPDIF_RX_EN¶: Enables SPDIF Rx. Default: 0 (Disabled)

SPDIF_RX_INDEX¶

S/PDIF Rx first channel index, defines which channels S/PDIF will be input on. Note, indexed from 0.

Default: NONE (Must be defined by app when SPDIF_RX enabled)

ADAT¶

XUA_ADAT_RX_EN¶: Enables ADAT Rx. Default: 0 (Disabled)

ADAT_RX_INDEX¶

ADAT Rx first channel index. defines which channels ADAT will be input on. Note, indexed from 0.

Default: NONE (Must be defined by app when XUA_ADAT_RX_EN is true)

PDM microphones¶

XUA_NUM_PDM_MICS¶

Number of PDM microphone outputs in the design.

Default: 0

XUA_PDM_MIC_USE_PDM_ISR¶

Merge the PDM receive task into the decimation task using an ISR. Note: this works well with lower PDM mic counts but 8 and above may require separation into dedicated tasks.

DEFAULT: 1, Enable PDM RX ISR mode

XUA_PDM_MIC_USE_DDR¶

Indicates whether two microphones share a single data line (DDR mode).

When set to 1, the system uses Double Data Rate (DDR) signaling to read two microphones from a single data line. When set to 0, each microphone is read on a separate data line.

Default: 1

XUA_PDM_MIC_INDEX¶

Disable USB functionalty just leaving AudioHub.

Default: Enabled

PDM Microphone first channel index, defines which channels microphones will be input on. Note, indexed from 0.

Default: 0 (i.e. channels [0:XUA_NUM_PDM_MICS-1])

DFU¶

XUA_DFU_EN¶

Enable DFU functionality.

Default: 1 (Enabled)

HID¶

HID_CONTROLS¶

Enable HID playback controls functionality.

1 for enabled, 0 for disabled.

Default 0 (Disabled)

USB device configuration¶

VENDOR_STR¶

Vendor String used by the device. This is also pre-pended to various strings used by the design.

Default: “XMOS”

VENDOR_ID¶

USB Vendor ID (or VID) as assigned by the USB-IF.

Default: 0x20B1 (XMOS)

PRODUCT_STR¶

USB Product String for the device. If defined will be used for both PRODUCT_STR_A2 and PRODUCT_STR_A1.

Default: Undefined

PRODUCT_STR_A2¶

Product string for Audio Class 2.0 mode.

Default: “XMOS xCORE (UAC2.0)”

PRODUCT_STR_A1¶

Product string for Audio Class 1.0 mode.

Default: “XMOS xCORE (UAC1.0)”

PID_AUDIO_1¶

USB Product ID (PID) for Audio Class 1.0 mode. Only required if XUA_AUDIO_CLASS_FS == 1.

Default: 0x0003

PID_AUDIO_2¶

USB Product ID (PID) for Audio Class 2.0 mode.

Default: 0x0002

BCD_DEVICE¶

Device firmware version number in Binary Coded Decimal format: 0xJJMN where JJ: major, M: minor, N: sub-minor version number.

NOTE: User code should not modify this but should modify BCD_DEVICE_J, BCD_DEVICE_M, BCD_DEVICE_N instead

Default: XMOS USB Audio Release version (e.g. 0x0651 for 6.5.1).

Stream Formats¶

Output/playback¶

OUTPUT_FORMAT_COUNT¶

Number of supported output stream formats.

Values 1,2,3 supported

Default: 2

STREAM_FORMAT_OUTPUT_1_RESOLUTION_BITS¶

Sample resolution (bits) of output stream Alternate 1.

Default: 24 if Alternate 1 is PCM, else 32 if DSD/RAW

Note, 24 on the lowests alt in case of OUTPUT_FORMAT_COUNT = 1 leaving 24bit as the designs default resolution.

STREAM_FORMAT_OUTPUT_2_RESOLUTION_BITS¶

Sample resolution (bits) of output stream Alternate 2.

Default: 16 if Alternate 2 is PCM, else 32 if DSD/RAW

STREAM_FORMAT_OUTPUT_3_RESOLUTION_BITS¶

Sample resolution (bits) of output stream Alternate 3.

Default: 32 if Alternate 2 is PCM, else 32 if DSD/RAW

HS_STREAM_FORMAT_OUTPUT_1_SUBSLOT_BYTES¶

Sample sub-slot size (bytes) of output stream Alternate 1 when running in high-speed.

Default: 4 if resolution for Alternate 1 is 24bits, else resolution / 8

Note, the default catchs the 24bit special case where 4-byte subslot is nicer for our 32-bit machine. Typically do not care about this extra bus overhead at High-speed

HS_STREAM_FORMAT_OUTPUT_2_SUBSLOT_BYTES¶

Sample sub-slot size (bytes) of output stream Alternate 2 when running in high-speed.

Default: 4 if resolution for Alternate 2 is 24bits, else resolution / 8

Note, the default catchs the 24bit special case where 4-byte subslot is nicer for our 32-bit machine. Typically do not care about this extra bus overhead at High-speed

HS_STREAM_FORMAT_OUTPUT_3_SUBSLOT_BYTES¶

Sample sub-slot size (bytes) of output stream Alternate 3 when running in high-speed.

Default: 4 if resolution for Alternate 3 is 24bits, else resolution / 8

Note, the default catchs the 24bit special case where 4-byte subslot is nicer for our 32-bit machine. Typically do not care about this extra bus overhead at High-speed

FS_STREAM_FORMAT_OUTPUT_1_SUBSLOT_BYTES¶

Sample sub-slot size (bytes) of output stream Alternate 1 when running in full-speed.

Note, in full-speed mode bus bandwidth is at a premium, therefore pack samples into smallest possible sub-slot.

Default: STREAM_FORMAT_OUTPUT_1_RESOLUTION_BITS / 8

FS_STREAM_FORMAT_OUTPUT_2_SUBSLOT_BYTES¶

Sample sub-slot size (bytes) of output stream Alternate 2 when running in full-speed.

Note, in full-speed mode bus bandwidth is at a premium, therefore pack samples into smallest possible sub-slot.

Default: STREAM_FORMAT_OUTPUT_2_RESOLUTION_BITS / 8

FS_STREAM_FORMAT_OUTPUT_3_SUBSLOT_BYTES¶

Sample sub-slot size (bytes) of output stream Alternate 3 when running in full-speed.

Note, in full-speed mode bus bandwidth is at a premium, therefore pack samples into smallest possible sub-slot.

Default: STREAM_FORMAT_OUTPUT_3_RESOLUTION_BITS / 8

STREAM_FORMAT_OUTPUT_1_DATAFORMAT¶

Sample audio data-format if output stream Alternate 1.

Default: UAC_FORMAT_TYPEI_RAW_DATA when Alternate 1 is RAW/DSD else UAC_FORMAT_TYPEI_PCM

STREAM_FORMAT_OUTPUT_2_DATAFORMAT¶

Sample audio data-format if output stream Alternate 2.

Default: UAC_FORMAT_TYPEI_RAW_DATA when Alternate 2 is RAW/DSD else UAC_FORMAT_TYPEI_PCM

STREAM_FORMAT_OUTPUT_3_DATAFORMAT¶

Sample audio data-format if output stream Alternate 3.

Default: UAC_FORMAT_TYPEI_RAW_DATA when Alternate 3 is RAW/DSD else UAC_FORMAT_TYPEI_PCM

Input/recording¶

INPUT_FORMAT_COUNT¶: Number of supported input stream formats. Default: 1.

STREAM_FORMAT_INPUT_1_RESOLUTION_BITS¶

Sample resolution (bits) of input stream Alternate 1.

Default: 24

HS_STREAM_FORMAT_INPUT_1_SUBSLOT_BYTES¶

Sample sub-slot size (bytes) of input stream Alternate 1 when running in high-speed.

Default: 4 if resolution for Alternate 1 is 24bits, else resolution / 8

Note, the default catchs the 24bit special case where 4-byte subslot is nicer for our 32-bit machine. Typically do not care about this extra bus overhead at High-speed

FS_STREAM_FORMAT_INPUT_1_SUBSLOT_BYTES¶

Sample sub-slot size (bytes) of input stream Alternate 1 when running in full-speed.

Note, in full-speed mode bus bandwidth is at a premium, therefore pack samples into smallest possible sub-slot.

Default: STREAM_FORMAT_INPUT_1_RESOLUTION_BITS / 8

STREAM_FORMAT_INPUT_1_DATAFORMAT¶

Sample audio data-format for input stream Alternate 1.

Default: UAC_FORMAT_TYPEI_PCM

Volume control¶

OUTPUT_VOLUME_CONTROL¶

Enable/disable output volume control including all processing and descriptor support.

Default: 1 (Enabled)

INPUT_VOLUME_CONTROL¶

Enable/disable input volume control including all processing and descriptor support.

Default: 1 (Enabled)

MIN_VOLUME¶

The minimum volume setting above -inf. This is a signed 8.8 fixed point number that must be strictly greater than -128 (0x8000)

Default: 0x8100 (-127db)

MAX_VOLUME¶

The maximum volume setting. This is a signed 8.8 fixed point number.

Default: 0x0000 (0db)

VOLUME_RES¶

The resolution of the volume control in db as a 8.8 fixed point number.

Default: 0x100 (1db)

Mixing¶

MIXER¶

Enable “mixer” core.

Default: 0 (Disabled)

MAX_MIX_COUNT¶

Number of seperate mixes to perform.

Default: 8 if MIXER enabled, else 0

MIX_INPUTS¶

Number of channels input into the mixer.

Note, total number of mixer nodes is MIX_INPUTS * MAX_MIX_COUNT

Default: 18

MIN_MIXER_VOLUME¶

The minimum volume setting for the mixer unit above -inf. This is a signed 8.8 fixed point number that must be strictly greater than -128 (0x8000)

Default: 0x8100 (-127db)

MAX_MIXER_VOLUME¶

The maximum volume setting for the mixer. This is a signed 8.8 fixed point number.

Default: 0x0000 (0db)

VOLUME_RES_MIXER¶

The resolution of the volume control in db as a 8.8 fixed point number.

Default: 0x100 (1db)

Power¶

XUA_POWERMODE¶

Report as self or bus powered device. This affects descriptors and XUD usage and is important for USB compliance.

Default: XUA_POWERMODE_BUS

XUA_CHAN_BUFF_CTRL¶

Enable power saving feature in XUA_Buffer_Decouple()

If set to 1 then a channel is instantiated between the XUA_Buffer_Ep() and XUA_Buffer_Decouple() tasks (which together form the buffer between XUD and Audio) that limits shared memory polling in XUA_Buffer_Ep() to occur only when a change has been made by XUA_Buffer_Decouple(). This significantly reduces core power at the cost of two channel ends on the USB_TILE.