sw_usb_audio: USB Audio reference designs£££doc/rst/sw_usb_audio.html#sw-usb-audio-usb-audio-reference-designs

sw_usb_audio: USB Audio reference designs$$$USB Audio programming guide$$$Project structure$$$Build system£££doc/rst/prog_proj_structure.html#build-system

The XMOS USB Audio Reference Design software and associated libraries employ the XCommon CMake build system. The XCommon CMake build system uses CMake to configure and generate the build environment which can then be built using xmake. As part of configuring the build environment, if there are any missing dependencies, XCommon CMake fetches them using git.

sw_usb_audio: USB Audio reference designs$$$USB Audio programming guide$$$Project structure$$$Applications and libraries£££doc/rst/prog_proj_structure.html#applications-and-libraries

The sw_usb_audio GIT repository includes multiple application directories. Each application directory contains a CMakeLists.txt file which describes the build configs for that application. The format of the CMakeLists.txt is described here XCommon CMake uses the CMakeLists.txt to generate Makefiles that can be compiled using xmake into executables. Typically, there’s one application directory per hardware platform. Applications and their respective hardware platforms are listed in Table 3.

The applications depend on several modules (or libraries), each of which have their own GIT repository. The immediate dependency libraries for the applications are specified by setting the APP_DEPENDENT_MODULES variable in the deps.cmake file. deps.cmake lists the common dependencies for all the applications and is included in each application’s CMakeLists.txt.

The dependency list specified in the deps.cmake can be extended to add new dependencies. Refer to the XCommon CMake Dependency Format documentation for more information about adding dependencies.

A shared file containing common dependencies ensures a consistent set of dependencies between all of the applications.

Each library has a lib_build_info.cmake which lists the library source, compile flags and dependencies. The library dependencies are specified in the LIB_DEPENDENT_MODULES variable in the lib_build_info.cmake. This allows dependency trees and nesting. XCommon CMake builds up a tree which is traversed depth-first, and populates the sandbox, fetching any missing dependencies by cloning them from github.

Most of the core code is contained in the XMOS USB Audio Library (lib_xua). A full list of core dependencies is shown in Table 4.

sw_usb_audio: USB Audio reference designs$$$USB Audio programming guide$$$A typical USB Audio application$$$lib_xua configuration£££doc/rst/prog_app_tutorial.html#lib-xua-configuration

The xua_conf.h file contains all the build-time #defines required to tailor the framework provided by lib_xua to the particular application at hand. Typically these override default values in xua_conf_default.h in lib_xua/api.

Firstly in app_usb_aud_xk_316_mc the xua_conf.h file sets defines to determine overall capability. For this application most of the optional interfaces are disabled by default. This is because the applications provide a large number build configurations in the CMakeLists.txt enabling various interfaces. For a product with a fixed specification this almost certainly would not be the case and setting in this file may be the preferred option.

Note that ifndef is used to check that the option is not already defined in the CMakeLists.txt.

/* Enable/Disable MIDI - Default is MIDI off */
#ifndef MIDI
#define MIDI               (0)
#endif

/* Enable/Disable S/PDIF output - Default is S/PDIF off */
#ifndef XUA_SPDIF_TX_EN
#define XUA_SPDIF_TX_EN    (0)
#endif

/* Enable/Disable S/PDIF input - Default is S/PDIF off */
#ifndef XUA_SPDIF_RX_EN
#define XUA_SPDIF_RX_EN    (0)
#endif

/* Enable/Disable ADAT output - Default is ADAT off */
#ifndef XUA_ADAT_TX_EN
#define XUA_ADAT_TX_EN     (0)
#endif

/* Enable/Disable ADAT input - Default is ADAT off */
#ifndef XUA_ADAT_RX_EN
#define XUA_ADAT_RX_EN     (0)
#endif

/* Enable/Disable Mixing core(s) - Default is on */
#ifndef MIXER
#define MIXER              (1)
#endif

/* Set the number of mixes to perform - Default is 0 i.e mixing disabled */
#ifndef MAX_MIX_COUNT
#define MAX_MIX_COUNT      (0)
#endif

/* Audio Class version - Default is 2.0 */
#ifndef AUDIO_CLASS
#define AUDIO_CLASS        (2)
#endif

Next, the file defines properties of the audio channels including counts and arrangements. By default the application provides 8 analogue channels for input and output.

The total number of channels exposed to the USB host (set via NUM_USB_CHAN_OUT and NUM_USB_CHAN_IN) are calculated based on the audio interfaces enabled. Again, this is due to the multiple build configurations in the application CMakeLists.txt and likely to be hard-coded for a product.

/* Number of I2S channels to DACs*/
#ifndef I2S_CHANS_DAC
#define I2S_CHANS_DAC      (8)
#endif

/* Number of I2S channels from ADCs */
#ifndef I2S_CHANS_ADC
#define I2S_CHANS_ADC      (8)
#endif

/* Number of USB streaming channels - by default calculate by counting audio interfaces */
#ifndef NUM_USB_CHAN_IN
#define NUM_USB_CHAN_IN    (I2S_CHANS_ADC + 2*XUA_SPDIF_RX_EN + 8*XUA_ADAT_RX_EN)  /* Device to Host */
#endif

#ifndef NUM_USB_CHAN_OUT
#define NUM_USB_CHAN_OUT   (I2S_CHANS_DAC + 2*XUA_SPDIF_TX_EN + 8*XUA_ADAT_TX_EN)  /* Host to Device */
#endif

/*** Defines relating to channel arrangement/indices ***/

Channel indices/offsets are set based on the audio interfaces enabled. Channels are indexed from 0. Setting SPDIF_TX_INDEX to 0 would cause the S/PDIF channels to duplicate analogue channels 0 and 1. Note, the offset for analogue channels is always 0.

/* Channel index of S/PDIF Tx channels: separate channels after analogue channels (if they fit) */
#ifndef SPDIF_TX_INDEX
    #if (I2S_CHANS_DAC + 2*XUA_SPDIF_TX_EN) <= NUM_USB_CHAN_OUT
        #define SPDIF_TX_INDEX   (I2S_CHANS_DAC)
    #else
        #define SPDIF_TX_INDEX   (0)
    #endif
#endif

/* Channel index of S/PDIF Rx channels: separate channels after analogue channels */
#ifndef SPDIF_RX_INDEX
#define SPDIF_RX_INDEX     (I2S_CHANS_ADC)
#endif

/* Channel index of ADAT Tx channels: separate channels after S/PDIF channels (if they fit) */
#ifndef ADAT_TX_INDEX
    #define ADAT_TX_INDEX    (I2S_CHANS_DAC + 2*XUA_SPDIF_TX_EN)
#endif

/* Channel index of ADAT Rx channels: separate channels after S/PDIF channels */
#ifndef ADAT_RX_INDEX
#define ADAT_RX_INDEX      (I2S_CHANS_ADC + 2*XUA_SPDIF_RX_EN)
#endif

The file then sets some frequency related defines for the audio master clocks and the maximum sample-rate for the device.

/* Master clock defines (in Hz) */
#ifndef MCLK_441
#define MCLK_441           (512*44100)   /* 44.1, 88.2 etc */
#endif

#ifndef MCLK_48
#define MCLK_48            (512*48000)   /* 48, 96 etc */
#endif

/* Minumum sample frequency device runs at */
#ifndef MIN_FREQ
#define MIN_FREQ           (44100)
#endif

/* Maximum sample frequency device runs at */
#ifndef MAX_FREQ
#define MAX_FREQ           (192000)
#endif

Due to the multi-tile nature of the xcore architecture the framework needs to be informed as to which tile various interfaces should be placed on, for example USB, S/PDIF etc.

#define XUD_TILE           (0)
#define PLL_REF_TILE       (0)

#define AUDIO_IO_TILE      (1)
#define MIDI_TILE          (1)

The file also sets some defines for general USB IDs and strings. These are set for the XMOS reference design but vary per manufacturer:

#define VENDOR_ID          (0x20B1) /* XMOS VID */
#ifndef PID_AUDIO_2
#define PID_AUDIO_2        (0x0016)
#endif
#ifndef PID_AUDIO_1
#define PID_AUDIO_1        (0x0017)
#endif

#ifndef DFU_PID
#if (AUDIO_CLASS == 1)
#define DFU_PID             (0xD000 + PID_AUDIO_1)
#else
#define DFU_PID             (0xD000 + PID_AUDIO_2)
#endif
#endif

#define PRODUCT_STR_A2     "XMOS xCORE.ai MC (UAC2.0)"
#define PRODUCT_STR_A1     "XMOS xCORE.ai MC (UAC1.0)"

For a full description of all the defines that can be set in xua_conf.h see Configuration defines.

sw_usb_audio: USB Audio reference designs$$$USB Audio programming guide$$$A typical USB Audio application$$$User functions£££doc/rst/prog_app_tutorial.html#user-functions

In addition to the xua_conf.h file, the application needs to provide implementations of some overridable user functions in lib_xua to provide custom functionality.

For app_usb_aud_xk_316_mc the implementations can be found in src/extensions/audiohw.xc and src/extensions/audiostream.xc

The two functions it overrides in audiohw.xc are AudioHwInit() and AudioHwConfig(). These are run from lib_xua on startup and sample-rate change respectively. Note, the default implementations in lib_xua are empty. These functions have parameters for sample frequency, sample depth, etc.

In the case of app_usb_aud_xk_316_mc these functions configure the external DACs and ADCs via an I²C bus and configure the xcore secondary PLL to generate the required master clock frequencies.

Due to the complexity of the hardware on the XK-AUDIO-316-MC the source code is not included here.

The application also overrides UserAudioStreamState(). This function is called from lib_xua when the audio stream to the device is started or stopped.

The application uses this function to enable/disable the on board LEDs based on whether an audio stream is active (input or output).

// Copyright 2022-2025 XMOS LIMITED.
// This Software is subject to the terms of the XMOS Public Licence: Version 1.
#include <platform.h>

on tile[0]: out port p_leds = XS1_PORT_4F;

void UserAudioStreamState(int inputActive, int outputActive)
{
    if(inputActive || outputActive)
    {
        /* Turn all LEDs on */
        p_leds <: 0xF;
    } else
    {
        /* Turn all LEDs off */
        p_leds <: 0x0;
    }
}

sw_usb_audio: USB Audio reference designs$$$USB Audio programming guide$$$A typical USB Audio application$$$The main program£££doc/rst/prog_app_tutorial.html#the-main-program

The main() function is the entry point to an application. In the XMOS USB Audio Reference Design software it is shared by all applications and is therefore part of the framework.

This section is largely informational as most developers should not need to modify the main() function. main() is located in main.xc in lib_xua, this file contains:

• A declaration of all the ports used in the framework. These clearly vary depending on the hardware platform the application is running on.

• A main() function which declares some channels and then has a par statement which runs the required cores in parallel.

Full documentation can be found in lib_xua.

The first items in the par include running tasks for the Endpoint 0 implementaton and buffering tasks for audio and endpoint buffering:

            {
                unsigned x;
                thread_speed();

                /* Attach mclk count port to mclk clock-block (for feedback) */
                //set_port_clock(p_for_mclk_count, clk_audio_mclk);
#if(AUDIO_IO_TILE != XUD_TILE)
                set_clock_src(clk_audio_mclk_usb, p_mclk_in_usb);
                set_port_clock(p_for_mclk_count, clk_audio_mclk_usb);
                start_clock(clk_audio_mclk_usb);
#else
                /* AUDIO_IO_TILE == XUD_TILE */
                /* Clock port from same clock-block as I2S */
                /* TODO remove asm() */
                asm("ldw %0, dp[clk_audio_mclk]":"=r"(x));
                asm("setclk res[%0], %1"::"r"(p_for_mclk_count), "r"(x));
                /* This clock block is started in audiohub in case we first need to connect other logic
                   e.g. digital Tx to it before starting */
#endif
                /* Endpoint & audio buffering cores - buffers all EP's other than 0 */
                XUA_Buffer(
#if (NUM_USB_CHAN_OUT > 0)
                           c_xud_out[ENDPOINT_NUMBER_OUT_AUDIO],       /* Audio Out*/
#endif
#if (NUM_USB_CHAN_IN > 0)
                           c_xud_in[ENDPOINT_NUMBER_IN_AUDIO],         /* Audio In */
#endif
#if (NUM_USB_CHAN_OUT > 0) && ((NUM_USB_CHAN_IN == 0) || defined(UAC_FORCE_FEEDBACK_EP))
                           c_xud_in[ENDPOINT_NUMBER_IN_FEEDBACK],      /* Audio FB */
#endif
#ifdef MIDI
                           c_xud_out[ENDPOINT_NUMBER_OUT_MIDI],        /* MIDI Out */ // 2
                           c_xud_in[ENDPOINT_NUMBER_IN_MIDI],          /* MIDI In */  // 4
                           c_midi,
#endif
#if (XUA_SPDIF_RX_EN || XUA_ADAT_RX_EN)
                           /* Audio Interrupt - only used for interrupts on external clock change */
                           c_xud_in[ENDPOINT_NUMBER_IN_INTERRUPT],
                           c_clk_int,
#endif
                           c_sof, c_aud_ctl, p_for_mclk_count
#if (XUA_HID_ENABLED)
                           , c_xud_in[ENDPOINT_NUMBER_IN_HID]
#endif
                           , c_mix_out
#if (XUA_SYNCMODE == XUA_SYNCMODE_SYNC)
                           , c_audio_rate_change
    #if (!XUA_USE_SW_PLL)
                           , i_pll_ref
    #else
                           , c_sw_pll
    #endif
#endif
                    );
                //:
            }
#endif

            /* Endpoint 0 Core */
            {
                thread_speed();
                XUA_Endpoint0( c_xud_out[0], c_xud_in[0], c_aud_ctl, c_mix_ctl, c_clk_ctl, dfuInterface VENDOR_REQUESTS_PARAMS_);
            }

It also runs a task for the USB interfacing thread (XUD_Main()):

                XUD_Main(c_xud_out, ENDPOINT_COUNT_OUT, c_xud_in, ENDPOINT_COUNT_IN,

The specification of the channel arrays connecting to this driver are described in the documentation for lib_xud.

The channels connected to XUD_Main() are passed to the XUA_Buffer() function which implements audio buffering and also buffering for other Endpoints.

                XUA_Buffer(
#if (NUM_USB_CHAN_OUT > 0)
                           c_xud_out[ENDPOINT_NUMBER_OUT_AUDIO],       /* Audio Out*/
#endif
#if (NUM_USB_CHAN_IN > 0)
                           c_xud_in[ENDPOINT_NUMBER_IN_AUDIO],         /* Audio In */
#endif
#if (NUM_USB_CHAN_OUT > 0) && ((NUM_USB_CHAN_IN == 0) || defined(UAC_FORCE_FEEDBACK_EP))
                           c_xud_in[ENDPOINT_NUMBER_IN_FEEDBACK],      /* Audio FB */
#endif
#ifdef MIDI
                           c_xud_out[ENDPOINT_NUMBER_OUT_MIDI],        /* MIDI Out */ // 2
                           c_xud_in[ENDPOINT_NUMBER_IN_MIDI],          /* MIDI In */  // 4
                           c_midi,
#endif
#if (XUA_SPDIF_RX_EN || XUA_ADAT_RX_EN)
                           /* Audio Interrupt - only used for interrupts on external clock change */
                           c_xud_in[ENDPOINT_NUMBER_IN_INTERRUPT],
                           c_clk_int,
#endif
                           c_sof, c_aud_ctl, p_for_mclk_count
#if (XUA_HID_ENABLED)
                           , c_xud_in[ENDPOINT_NUMBER_IN_HID]
#endif
                           , c_mix_out
#if (XUA_SYNCMODE == XUA_SYNCMODE_SYNC)
                           , c_audio_rate_change
    #if (!XUA_USE_SW_PLL)
                           , i_pll_ref
    #else
                           , c_sw_pll
    #endif
#endif
                    );

A channel connects this buffering task to the audio driver which controls the I²S output. It also forwards and receives audio samples from other interfaces e.g. S/PDIF, ADAT, as required:

            usb_audio_io(
#if (NUM_USB_CHAN_OUT > 0) || (NUM_USB_CHAN_IN > 0) || XUA_HID_ENABLED || defined(MIDI)
                /* Connect audio system to XUA_Buffer(); */
                c_mix_out
#else
                /* Connect to XUA_Endpoint0() */
                c_aud_ctl
#endif
#if (XUA_SPDIF_TX_EN) && (SPDIF_TX_TILE != AUDIO_IO_TILE)
                , c_spdif_tx
#endif
#if (MIXER)
                , c_mix_ctl
#endif
                , c_spdif_rx, c_adat_rx, c_clk_ctl, c_clk_int
#if (XUD_TILE != 0) && (AUDIO_IO_TILE == 0) && (XUA_DFU_EN == 1)
                , dfuInterface
#endif
#if (XUA_NUM_PDM_MICS > 0)
                , c_pdm_pcm
#endif
#if (XUA_SPDIF_RX_EN || XUA_ADAT_RX_EN)
                , i_pll_ref
#endif
#if (XUA_SYNCMODE == XUA_SYNCMODE_SYNC)
                , c_audio_rate_change
#endif
#if ((XUA_SPDIF_RX_EN || XUA_ADAT_RX_EN) && XUA_USE_SW_PLL)
                , p_for_mclk_count_audio
                , c_sw_pll
#endif
            );
        }

Finally, other tasks are created for various interfaces, for example, if MIDI is enabled a core is required to drive the MIDI input and output.

        on tile[MIDI_TILE]:
        {
            thread_speed();
            usb_midi(p_midi_rx, p_midi_tx, clk_midi, c_midi, 0);
        }

sw_usb_audio: USB Audio reference designs$$$USB Audio programming guide$$$Adding custom code$$$Example: Changing output format£££doc/rst/prog_modification.html#example-changing-output-format

Customising the digital output format may be required, for example, to support a CODEC that expects sample data right-justified with respect to the word clock.

To achieve this, alter the main audio driver loop in xua_audiohub.xc. After making the alteration, re-test the functionality to ensure proper operation.

Hint, a naive approach would simply include right-shifting the audio data by 7 bits before it is output to the port. This would of course lose LSB data depending on the sample-depth.

sw_usb_audio: USB Audio reference designs$$$USB Audio programming guide$$$Adding custom code$$$Example: Adding DSP to the output stream£££doc/rst/prog_modification.html#example-adding-dsp-to-the-output-stream

To add some DSP requires an extra thread of computation. Depending on the xcore device being used, some existing functionality might need to be disabled to free up a thread (e.g. disable S/PDIF). There are many ways that DSP processing can be added, the steps below outline one approach:

1. Remove some functionality using the defines in Configuration defines to free up a thread as required.

2. Add another thread to do the DSP. This core will probably have a single XC channel. This channel can be used to send and receive audio samples from the XUA_AudioHub() task. A benefit of modifying samples here is that samples from all inputs are collected into one place at this point. Optionally, a second channel could be used to accept control messages that affect the DSP. This could be from Endpoint 0 or some other task with user input - a thread handling button presses, for example.

3. Implement the DSP in this thread. This needs to be synchronous (i.e. for every sample received from the XUA_AudioHub(), a sample needs to be output back).

sw_usb_audio: USB Audio reference designs$$$USB Audio applications$$$The xcore.ai Multi-Channel Audio Board$$$Audio hardware£££doc/rst/app_316_mc.html#audio-hardware

sw_usb_audio: USB Audio reference designs$$$USB Audio applications$$$The xcore.ai Multi-Channel Audio Board$$$Configuring audio hardware£££doc/rst/app_316_mc.html#configuring-audio-hardware

All of the external audio hardware is configured using lib_board_support.

The hardware targeted is the XMOS XU316 Multichannel Audio board (XK-AUDIO-316-MC). The lib_board_support functions xk_audio_316_mc_ab_board_setup(), xk_audio_316_mc_ab_i2c_master(), xk_audio_316_mc_ab_AudioHwInit() and xk_audio_316_mc_ab_AudioHwConfig() are called at various points during initialisation and runtime to start the I²C master, initialise and configure the audio hardware.

The audio hardware configuration is set in the config structure of type xk_audio_316_mc_ab_config_t which is passed to the xk_audio_316_mc_ab_board_setup(), xk_audio_316_mc_ab_AudioHwInit() and xk_audio_316_mc_ab_AudioHwConfig() functions.

static xk_audio_316_mc_ab_config_t config =
{
    // clk_mode
    (XUA_SYNCMODE == XUA_SYNCMODE_SYNC || XUA_SPDIF_RX_EN || XUA_ADAT_RX_EN)
    ? ( XUA_USE_SW_PLL
        ? CLK_PLL : CLK_CS2100 )
    : CLK_FIXED,

    // dac_is_clk_master
    CODEC_MASTER,

    // default_mclk
    (DEFAULT_FREQ % 22050 == 0) ? MCLK_441 : MCLK_48,

    // pll_sync_freq
    PLL_SYNC_FREQ,

    // pcm_format
    XUA_PCM_FORMAT,

    // i2s_n_bits
    XUA_I2S_N_BITS,

    // i2s_chans_per_frame
    I2S_CHANS_PER_FRAME
};

xk_audio_316_mc_ab_board_setup() function is called from the wrapper function board_setup() as part of the application’s initialisation process. It performs the required port operations to enable the audio hardware on the platform.

xk_audio_316_mc_ab_i2c_master() function is called after board_setup() during initialisation and it starts the I²C master task. This is required to allow the audio hardware to be configured over I²C, remotely from the other tile, due to the IO arrangement of the XK-AUDIO-316-MC board.

    #define USER_MAIN_CORES on tile[0]: {\
                                            board_setup();\
                                            xk_audio_316_mc_ab_i2c_master(i2c);\

The AudioHwInit() function is implemented to make a call to the lib_board_support function xk_audio_316_mc_ab_AudioHwInit() to power up and initialise the audio hardware ready for a configuration.

The AudioHwConfig() function configures the audio hardware post initialisation. It is typically called each time a sample rate or stream format change occurs. It is implmented to make a call to the lib_board_support function xk_audio_316_mc_ab_AudioHwConfig().

For further details on the hardware platform and the functions available for configuring it refer to lib_board_support documentation.

sw_usb_audio: USB Audio reference designs$$$USB Audio applications$$$The xcore.ai Multi-Channel Audio Board$$$Validated build options£££doc/rst/app_316_mc.html#validated-build-options

The reference design can be built in several ways by changing the build options. These are described in Configuration defines.

The design has only been fully validated against the build options as set in the application as distributed in the CMakeLists.txt. See Build configurations for details and general information on build configuration naming scheme.

These fully validated build configurations are enumerated in the supplied CMakeLists.txt.

The build configuration naming scheme employed in the CMakeLists.txt is shown in Table 8.

e.g. A build configuration named 2AMi10o10xsxxxx would signify: Audio Class 2.0 running in asynchronous mode. The xcore is I²S master. Input and output enabled (10 channels each), no MIDI, S/PDIF input, no S/PDIF output, no ADAT or DSD.

In addition to this some terms may be appended onto a build configuration name to signify additional options. For example, tdm may be appended to the build configuration name to indicate the I²S mode employed.

sw_usb_audio: USB Audio reference designs$$$USB Audio applications$$$The xcore-200 Multi-Channel Audio Board$$$Audio hardware£££doc/rst/app_216_mc.html#audio-hardware

sw_usb_audio: USB Audio reference designs$$$USB Audio applications$$$The xcore-200 Multi-Channel Audio Board$$$Configuring audio hardware£££doc/rst/app_216_mc.html#configuring-audio-hardware

All of the external audio hardware is configured using lib_board_support.

The hardware targeted is the XMOS XU216 Multichannel Audio board (XK-AUDIO-216-MC). The functions xk_audio_216_mc_ab_AudioHwInit() and xk_audio_216_mc_ab_AudioHwConfig() are called at various points during initialisation and runtime to initialise and configure the audio hardware.

The audio hardware configuration is set in the config structure of type xk_audio_216_mc_ab_config_t which is passed to the xk_audio_216_mc_ab_AudioHwInit() and xk_audio_216_mc_ab_AudioHwConfig() functions.

static const xk_audio_216_mc_ab_config_t config = {
    // clk_mode
    CLK_MODE,

    // codec_is_clk_master
    CODEC_MASTER,

    // usb_sel
    (USB_SEL_A ? AUD_216_USB_A : AUD_216_USB_B),

    // pcm_format
    XUA_PCM_FORMAT,

    // pll_sync_freq
    PLL_SYNC_FREQ
};

The AudioHwInit() function is implemented to make a call to the lib_board_support function xk_audio_216_mc_ab_AudioHwInit() to power up and initialise the audio hardware ready for a configuration.

The AudioHwConfig() function configures the audio hardware post initialisation. It is called each time a sample rate or stream format change occurs. It is implemented to make a call to the lib_board_support function xk_audio_216_mc_ab_AudioHwConfig().

For further details on the hardware platform and the functions available for configuring it refer to lib_board_support documentation.

sw_usb_audio: USB Audio reference designs$$$USB Audio applications$$$The xcore-200 Multi-Channel Audio Board$$$Validated build options£££doc/rst/app_216_mc.html#validated-build-options

The reference design can be built in several ways by changing the build options. These are described in Configuration defines.

The design has only been fully validated against the build options as set in the application as distributed in the CMakeLists.txt. See Build configurations for details and general information on build configuation naming scheme.

These fully validated build configurations are enumerated in the supplied CMakeLists.txt.

In practise, due to the similarities between the xcore-200 and xcore.ai series feature set, it is fully expected that all listed xcore-200 series configurations will operate as expected on the xcore.ai series and vice versa.

The build configuration naming scheme employed in the CMakeLists.txt is shown in Table 11.

e.g. A build configuration named 2AMi10o10xsxxxx would signify: Audio class 2.0 running in asynchronous mode. The xcore is I²S master. Input and output enabled (10 channels each), no MIDI, S/PDIF input, no S/PDIF output, no ADAT or DSD.

In addition to this some terms may be appended onto a build configuration name to signify additional options. For example, tdm may be appended to the build configuration name to indicate the I²S mode employed.

sw_usb_audio: USB Audio reference designs$$$USB Audio API reference$$$Configuration defines$$$Code location (tile)£££doc/rst/api_xua_conf.html#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.

PLL_REF_TILE

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

SPDIF_TX_TILE

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

sw_usb_audio: USB Audio reference designs$$$USB Audio API reference$$$Configuration defines$$$Channel counts£££doc/rst/api_xua_conf.html#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)

DSD_CHANS_DAC

Number of DSD output channels.

Default: 0 (disabled)

sw_usb_audio: USB Audio reference designs$$$USB Audio API reference$$$Configuration defines$$$Frequencies and clocks£££doc/rst/api_xua_conf.html#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

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)

sw_usb_audio: USB Audio reference designs$$$USB Audio API reference$$$Configuration defines$$$Audio Class£££doc/rst/api_xua_conf.html#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.

sw_usb_audio: USB Audio reference designs$$$USB Audio API reference$$$Configuration defines$$$System feature configuration£££doc/rst/api_xua_conf.html#system-feature-configuration

sw_usb_audio: USB Audio reference designs$$$USB Audio API reference$$$Configuration defines$$$USB device configuration£££doc/rst/api_xua_conf.html#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).

sw_usb_audio: USB Audio reference designs$$$USB Audio API reference$$$Configuration defines$$$Volume control£££doc/rst/api_xua_conf.html#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)

sw_usb_audio: USB Audio reference designs$$$USB Audio API reference$$$Configuration defines$$$Mixing parameters£££doc/rst/api_xua_conf.html#mixing-parameters

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

sw_usb_audio: USB Audio reference designs$$$USB Audio API reference$$$Configuration defines$$$Power£££doc/rst/api_xua_conf.html#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.

XUA_LOW_POWER_NON_STREAMING

Enable power saving when device is enumerated but audio in not currently streaming.

If set to 1 then transitions to ALT interface 0 (streaming stopped) will cause AudioHub to cease looping and no-longer driver the I2S/TDM lines. In addition, the callback AudioHwShutdown() is called which allows the user to run any specific code (eg. CODEC power-down and/or disable master clock) to further reduce system power in this state. AudioHwInit() and AudioHwConfig() will always be called again prior to USB audio streaming. The transition to the low power state will only occur when both input and output interfaces are not streaming. As soon as either input or output streaming starts then audiohub is restarted.

If set to zero or undefined (default behaviour) then AudioHub will always continue looping even when audio streaming stops. This behaviour may be preferable in applications where frequent initialisation of the mixed signal hardware is undesirable, where other parts of the system rely on I2S clocks being conitinuously available or in MI (musical instrument) applications where functions such as mixer need to continuously operate regardless of USB streaming state.

sw_usb_audio: USB Audio reference designs$$$USB Audio API reference$$$User function definitions$$$External audio hardware configuration£££doc/rst/api_user_functions.html#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.

sw_usb_audio: USB Audio reference designs$$$USB Audio API reference$$$User function definitions$$$Audio streaming notification£££doc/rst/api_user_functions.html#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

sw_usb_audio: USB Audio reference designs$$$USB Audio API reference$$$User function definitions$$$HID controls£££doc/rst/api_user_functions.html#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