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)¶

AUDIO_IO_TILE¶: Location (tile) of audio I/O. Default: 0.

XUD_TILE¶: Location (tile) of audio I/O. Default: 0.

MIDI_TILE¶: Location (tile) of MIDI I/O. Default: AUDIO_IO_TILE.

SPDIF_TX_TILE¶: Location (tile) of SPDIF Tx. Default: AUDIO_IO_TILE.

PDM_TILE¶: Location (tile) of PDM Rx. Default: AUDIO_IO_TILE.

PLL_REF_TILE¶: Location (tile) of reference signal to CS2100. Default: AUDIO_IO_TILE.

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 channesl 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 microphones in the design.

Default: 0

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.