Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

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