lib_xua£££doc/rst/lib_xua.html#lib-xua

lib_xua$$$Options$$$Strings and IDs£££doc/rst/opt_strings.html#strings-and-ids

The codebase includes various strings and IDs that should be customised to match the product requirements. These are listed in Table 6.

The Vendor ID (VID) should be acquired from the USB Implementers Forum (www.usb.org).

The VID and Product ID (PID) pair must be unique to each product, otherwise driver incompatibilities may arise.

lib_xua$$$Options$$$Code Location£££doc/rst/opt_location.html#code-location

When designing a system there is a choice as to which hardware resources to use for each interface. In a multi-tile system the codebase needs to be informed as to which tiles to use for these hardware resources and associated code.

A series of defines are used to allow the programmer to easily move code between tiles. Arguably the most important of these are AUDIO_IO_TILE and XUD_TILE. Table 7 shows a full listing of these TILE defines.

lib_xua$$$Options$$$Channel counts and sample rates£££doc/rst/opt_channels.html#channel-counts-and-sample-rates

lib_xua is fully configurable in relation to channel counts and sample rates. Practical limitations of these are normally based on USB packet size restrictions and I/O availablity.

For example, the maximum packet size for high-speed USB is 1024 bytes, limiting the channel count to 10 channels for a device running at 192kHz with 32bit sample depth.

The defines in Table 8 set the channel counts exposed to the USB host.

Sample rates ranges are set by the defines in Table 9. The codebase will automatically populate the device sample rate list with popular frequencies between the min and max values. All values are in Hz:

The codebase requires knowledge of the two master clock frequencies that will be present on the master-clock port(s). One for 44.1kHz, 88.2kHz etc and one for 48kHz, 96kHz etc. These are set using defines in Table 10. All values are in Hz.

lib_xua$$$Options$$$USB Audio Class version£££doc/rst/opt_audio_class.html#usb-audio-class-version

The codebase supports USB Audio Class (UAC) versions 1.0 and 2.0.

UAC 2.0 offers many improvements over UAC 1.0, most notable is the complete support for high-speed (HS) operation. This means that Audio Class devices are no longer limited to full-speed (FS) operation allowing greater channel counts, sample frequencies and sample bit-depths. Additional improvements, amongst others, include:

• Added support for multiple clock domains, clock description and clock control

• Extensive support for interrupts to inform the host about dynamic changes that occur to different entities such as Clocks etc

lib_xua$$$Options$$$Synchronisation£££doc/rst/opt_sync.html#synchronisation

The codebase supports “Synchronous” and “Asynchronous” modes for USB transfer as defined by the USB specification(s).

Asynchronous mode (XUA_SYNCMODE_ASYNC) has the advantage that the device is clock-master. This means that a high-quality local master-clock source can be utilised. It also has the benefit that the device may synchronise its master clock to an external digital input stream e.g. S/PDIF and thus avoiding sample-rate conversion.

The drawback of this mode is that it burdens the host with syncing to the device which some hosts may not support. This is especially pertinent to embedded hosts, however, most PCs and mobile devices will indeed support this mode.

Synchronous mode (XUA_SYNCMODE_SYNC) is an option if the target host does not support asynchronous mode or if it is desirable to synchronise many devices to a single host. It should be noted, however, that input from digital streams, such as S/PDIF, are not currently supported in this mode.

Setting the synchronisation mode of the device is done using the defines in Table 12.

When operating in synchronous mode a local master clock must be generated that is synchronised to the incoming SoF rate from USB. Either an external Cirrus Logic CS2100 device is required for this purpose or, on xcore.ai devices, the on-chip application PLL may be used via lib_sw_pll. In the case of using the CS2100, the codebase expects to drive a synchronisation signal to this external device as a reference.

The programmer should ensure the defines in Table 13 are set appropriately.

The codebase expects the CS2100 reference signal port to be defined in the application XN file as PORT_PLL_REF. This may be a port of any bit-width, however, connection to bit[0] is assumed:

<Port Location="XS1_PORT_1A"  Name="PORT_PLL_REF"/>

Configuration of the external CS2100 device (typically via I2C) is beyond the scope of this document.

lib_xua$$$Options$$$I²S/TDM£££doc/rst/opt_i2s.html#i2s-tdm

I²S/TDM is typically fundamental to most products and is built into the XUA_AudioHub() thread.

Table 14 lists the defines that affect the I²S implementation.

The I²S code expects that the ports required for I²S (master clock, LR-clock, bit-clock and data lines) are defined in the application XN file on the relevant Tile. For example:

<Tile Number="0" Reference="tile[0]">
    <Port Location="XS1_PORT_1A"  Name="PORT_MCLK_IN"/>
    <Port Location="XS1_PORT_1B"  Name="PORT_I2S_LRCLK"/>
    <Port Location="XS1_PORT_1C"  Name="PORT_I2S_BCLK"/>
    <Port Location="XS1_PORT_1D"  Name="PORT_I2S_DAC0"/>
    <port Location="XS1_PORT_1E"  Name="PORT_I2S_DAC1"/>
    <Port Location="XS1_PORT_1F"  Name="PORT_I2S_ADC0"/>
    <Port Location="XS1_PORT_1G"  Name="PORT_I2S_ADC1"/>
</Tile>

All of the I²S/TDM related ports must be 1-bit ports.

lib_xua$$$Options$$$S/PDIF transmit£££doc/rst/opt_spdif_tx.html#s-pdif-transmit

The codebase supports a single, stereo, S/PDIF transmitter. This can be output over 75 Ω coaxial or optical fibre. In order to provide S/PDIF transmit functionality lib_xua uses lib_spdif.

Basic configuration of S/PDIF transmit functionality is achieved with the defines in Table 15.

In addition, the developer may choose which tile the S/PDIF transmitter runs on, see Table 16

The codebase expects the S/PDIF transmit port to be defined in the application XN file as PORT_SPDIF_OUT. This must be a 1-bit port, for example:

<Port Location="XS1_PORT_1A"  Name="PORT_SPDIF_OUT"/>

lib_xua$$$Options$$$S/PDIF receive£££doc/rst/opt_spdif_rx.html#s-pdif-receive

The codebase supports a single, stereo, S/PDIF receiver. This can be input via 75 Ω coaxial or optical fibre. In order to provide S/PDIF functionality lib_xua uses lib_spdif.

Basic configuration of S/PDIF receive functionality is achieved with the defines in Table 17

The codebase expects the S/PDIF receive port to be defined in the application XN file as PORT_SPDIF_IN. This must be a 1-bit port, for example:

<Port Location="XS1_PORT_1A"  Name="PORT_SPDIF_IN"/>

When S/PDIF receive is enabled the codebase expects to either drive a synchronisation signal to an external Cirrus Logic CS2100 device or use lib_sw_pll (xcore.ai only) for master-clock generation.

The programmer should ensure the defines in Table 18 are set appropriately

The codebase expects this reference signal port to be defined in the application XN file as PORT_PLL_REF. This may be a port of any bit-width, however, connection to bit[0] is assumed:

<Port Location="XS1_PORT_1A"  Name="PORT_PLL_REF"/>

Configuration of the external CS2100 device (typically via I2C) is beyond the scope of this document.

lib_xua$$$Options$$$ADAT transmit£££doc/rst/opt_adat_tx.html#adat-transmit

The codebase supports a single ADAT transmitter that can transmit eight channels of uncompressed digital audio at sample-rates of 44.1 or 48 kHz over an optical cable. Higher rates are supported with a reduced number of samples via S/MUX (‘sample multiplexing’). Using S/MUX, the ADAT transmitter can transmit four channels at 88.2 or 96 kHz or two channels at 176.4 or 192 kHz.

In order to provide ADAT transmit functionality lib_xua uses lib_adat.

Basic configuration of ADAT transmit functionality is achieved with the defines in Table 19.

The ADAT transmitter runs on the same tile as the Audio IO (AUDIO_IO_TILE)

The codebase expects the ADAT transmit port to be defined in the application XN file as PORT_ADAT_OUT. This must be a 1-bit port, for example:

<Port Location="XS1_PORT_1G"  Name="PORT_ADAT_OUT"/>

lib_xua$$$Options$$$ADAT receive£££doc/rst/opt_adat_rx.html#adat-receive

The codebase supports a single ADAT receiver that can receive up to eight channels of audio at a sample rate of 44.1kHz or 48kHz over an optical interface. Higher rates are supported with a reduced number of samples via S/MUX (‘sample multiplexing’). Using S/MUX, the ADAT receiver can receive four channels at 88.2 or 96 kHz or two channels at 176.4 or 192 kHz.

In order to provide ADAT functionality lib_xua uses lib_adat.

Basic configuration of ADAT receive functionality is achieved with the defines in Table 20.

The codebase expects the ADAT receive port to be defined in the application XN file as PORT_ADAT_IN. This must be a 1-bit port, for example:

<Port Location="XS1_PORT_1O"  Name="PORT_ADAT_IN"/>

When ADAT receive is enabled the codebase expects to either drive a synchronisation signal to an external Cirrus Logic CS2100 device or use lib_sw_pll (xcore.ai only) for generating a master clock that is synchronised to the ADAT digital stream.

The programmer should ensure the defines in Table 21 are set appropriately:

The codebase expects this reference signal port to be defined in the application XN file as PORT_PLL_REF. This may be a port of any bit-width, however, connection to bit[0] is assumed:

<Port Location="XS1_PORT_1A"  Name="PORT_PLL_REF"/>

Configuration of the external CS2100 device (typically via I²C) is beyond the scope of this document.

lib_xua$$$Options$$$MIDI£££doc/rst/opt_midi.html#midi

lib_xua supports MIDI input/output over USB as per Universal Serial Bus Device Class Definition for MIDI Devices.

MIDI functionality is enabled with the define in Table 22.

lib_xua supports MIDI receive on a 4-bit or 1-bit port, defaulting to using a 1-bit port. MIDI transmit is supported over a port of any bit-width. By default lib_xua assumes the transmit and receive I/O is connected to bit[0] of the port. This is configurable for the transmit port. Table 23 provides information on configuring these parameters.

The MIDI code expects that the ports for receive and transmit are defined in the application XN file on the relevant Tile. The expected names for the ports are PORT_MIDI_IN and PORT_MIDI_OUT, for example:

<Tile Number="0" Reference="tile[0]">
    <!-- MIDI -->
    <Port Location="XS1_PORT_1F"  Name="PORT_MIDI_IN"/>
    <Port Location="XS1_PORT_4C"  Name="PORT_MIDI_OUT"/>
</Tile>

lib_xua$$$Options$$$PDM microphones£££doc/rst/opt_pdm.html#pdm-microphones

lib_xua supports input from up to 8 PDM microphones although this is extensible.

PDM microphone support is provided via lib_mic_array. Settings for PDM microphones are controlled with the defines in Table 24.

Please see the PDM Microphones section for further details.

lib_xua$$$Options$$$Mixer£££doc/rst/opt_mixer.html#mixer

lib_xua supports audio mixing functionality with highly flexible routing options.

Essentially the mixer is capable of performing 8 separate mixes with up to 18 inputs at sample rates up to 96kHz and 2 mixes with up to 18 inputs at higher sample rates.

Inputs to the mixer can be selected from any device input (USB, S/PDIF, I2S etc) and outputs from the mixer can be routed to any device output (USB, S/PDIF, I2S etc).

See Digital mixer for full details of the mixer including control.

Basic configuration of mixer functionality is achieved with the the defines Table 25.

lib_xua$$$Options$$$Direct Stream Digital (DSD)£££doc/rst/opt_dsd.html#direct-stream-digital-dsd

Direct Stream Digital (DSD) is used for digitally encoding audio signals on Super Audio CDs (SACD). It uses pulse-density modulation (PDM) encoding.

lib_xua supports DSD playback from the host via “DSD over PCM” (DoP) and a “Native” implementation which is, while USB specification based, proprietary to XMOS.

DSD is enabled with by setting the following define to a non-zero value:

Typically this would be set to 2 for stereo output.

By default both “Native” and DoP functionality are enabled when DSD is enabled. The Native DSD implementation uses an alternative streaming interface such that the host can inform the device that DSD data is being streamed. See: Audio stream formats for details.

If only DoP functionality is desired the Native implementation can be disabled with the define in Table 27.

<Port Location="XS1_PORT_1M"  Name="PORT_DSD_DAC0"/>
<port Location="XS1_PORT_1N"  Name="PORT_DSD_DAC1"/>
<Port Location="XS1_PORT_1G"  Name="PORT_DSD_CLK"/>

lib_xua$$$Options$$$DFU£££doc/rst/opt_dfu.html#dfu

The codebase supports DFU over USB implementation compliant with version 1.1 of Universal Serial Bus Device Class Specification for Device Firmware Upgrade.

Table 28 lists the DFU related configuration options.

lib_xua$$$Options$$$Audio stream formats£££doc/rst/opt_audio_formats.html#audio-stream-formats

The design currently supports up to three different stream formats for playback, selectable at run time. This is implemented using standard Alternative Settings to the Audio Streaming interfaces.

An Audio Streaming interface can have Alternate Settings that can be used to change certain characteristics of the interface and underlying endpoint. A typical use of Alternate Settings is to provide a way to change the subframe size and/or number of channels on an active Audio Streaming interface. Whenever an Audio Streaming interface requires an isochronous data endpoint, it must at least provide the default Alternate Setting (Alternate Setting 0) with zero bandwidth requirements (no isochronous data endpoint defined) and an additional Alternate Setting that contains the actual isochronous data endpoint. This zero bandwidth alternative setting 0 is always implemented by the design.

For further information refer to 3.16.2 of USB Audio Device Class Definition for Audio Devices, release 2.0

Customisable parameters for the Alternate Settings provided by the design are as follows.:

• Audio sample resolution

• Audio sample subslot size

• Audio data format

By default the design exposes two sets of Alternative Settings for the playback Audio Streaming interface, one for 16-bit and another for 24-bit playback. When DSD is enabled an additional (32-bit) alternative is exposed.

lib_xua$$$Options$$$Other options£££doc/rst/opt_other.html#other-options

There are a few other, lesser used, options available. These are shown in Table 29.

lib_xua$$$Advanced usage$$$Core hardware resources£££doc/rst/using_adv_core_hw.html#core-hardware-resources

The user must declare and initialise relevant hardware resources (globally) and pass them to the relevant function of lib_xua.

As an absolute minimum the following resources are required:

• A 1-bit port for audio master clock input

• A clock-block, which will be clocked from the master clock input port

When using the default asynchronous mode of operation an additional port is required:

• A n-bit port for internal feedback calculation (typically a free, unused port is used e.g. XS1_PORT_16B)

Example declaration of these resources might look as follows:

in port p_mclk_in        = PORT_MCLK_IN;
in port p_for_mclk_count = PORT_MCLK_COUNT;   /* Extra port for counting master clock ticks */
clock clk_audio_mclk     = on tile[0]: XS1_CLKBLK_5;   /* Master clock */

The XUA_AudioHub() function typically requires an audio master clock input to clock the physical audio I/O such as S/PDIF transmit and I²S [1] . Less obvious is the reasoning for the XUA_Buffer() task having the same requirement when running in asynchronous mode - it is used for the USB feedback system and packet sizing.

Due to the above, if the XUD_AudioHub() and XUA_Buffer() cores must reside on separate tiles a separate master clock input port must be provided to each, for example:

/* Master clock for the audio IO tile */
in port p_mclk_in                   = PORT_MCLK_IN;

/* Resources for USB feedback */
in port p_mclk_in_usb               = PORT_MCLK_IN_USB;  /* Extra master clock input for the USB tile */

Whilst the hardware resources described in this section satisfy the basic requirements for the operation (or build) of lib_xua, projects typically also need some additional audio I/O, I²S or S/PDIF for example.

These should be passed into the various task functions as required - see API reference.

lib_xua$$$Advanced usage$$$Running the core components£££doc/rst/using_adv_core_comp.html#running-the-core-components

In their most basic form the core components can be run as follows:

par
{
    /* Endpoint 0 thread from lib_xua */
    XUA_Endpoint0(c_ep_out[0], c_ep_in[0], c_aud_ctl, ...);

    /* Buffering threads - handles audio data to/from EP's and gives/gets data to/from the audio I/O thread */
    /* Note, this spawns two threads */
    XUA_Buffer(c_ep_out[1], c_ep_in[1], c_sof, c_aud_ctl, p_for_mclk_count, c_aud);

    /* AudioHub/IO thread does most of the audio IO i.e. I2S (also serves as a hub for all audio) */
    XUA_AudioHub(c_aud, ...) ;
}

XUA_Buffer() expects the p_for_mclk_count argument to be clocked from the audio master clock before receiving it as a parameter. The following code satisfies this requirement:

{
    /* Connect master-clock clock-block to clock-block pin */

    /* Clock clock-block from mclk pin */
    set_clock_src(clk_audio_mclk_usb, p_mclk_in_usb);

    /* Clock the "count" port from the clock block */
    set_port_clock(p_for_mclk_count, clk_audio_mclk_usb);

    /* Set the clock off running */
    start_clock(clk_audio_mclk_usb);

    XUA_Buffer(c_ep_out[1], c_ep_in[1], c_sof, c_aud_ctl, p_for_mclk_count, c_aud);
}

For USB connectivity a call to XUD_Main() (from lib_xud) must also be made:

/* Low level USB device layer thread */
on tile[1]: XUD_Main(c_ep_out, 2, c_ep_in, 2, c_sof, epTypeTableOut, epTypeTableIn, null, null, -1, XUD_SPEED_HS, XUD_PWR_SELF);

Additionally, the required communication channels must also be declared:

/* Channel arrays for lib_xud */
chan c_ep_out[2];
chan c_ep_in[2];

/* Channel for communicating SOF notifications from XUD to the Buffering threads */
chan c_sof;

/* Channel for audio data between buffering threads and AudioHub/IO thread */
chan c_aud;

/* Channel for communicating control messages from EP0 to the rest of the device (via the buffering threads) */
chan c_aud_ctl;

This section provides enough information to implement a skeleton program for a USB Audio device. When running the xcore device will present itself as a USB Audio Class device on the bus. Audio streaming will be impaired since tasks relating to physical audio interfaces are yet to be instantiated.

lib_xua$$$Advanced usage$$$I²S/TDM£££doc/rst/using_adv_i2s.html#i2s-tdm

I²S/TDM is typically fundamental to most products and is built into the XUA_AudioHub() thread.

In order to enable I²S/TDM one must declare an array of ports for the data-lines (one for each direction):

/* Port declarations. Note, the defines come from the XN file */
buffered out port:32 p_i2s_dac[] = {PORT_I2S_DAC0}; /* I2S Data-line(s) */
buffered in port:32 p_i2s_adc[]  = {PORT_I2S_ADC0}; /* I2S Data-line(s) */

Ports for the sample and bit clocks are also required:

buffered out port:32 p_lrclk        = PORT_I2S_LRCLK; /* I2S Bit-clock */
buffered out port:32 p_bclk         = PORT_I2S_BCLK;  /* I2S L/R-clock */

These ports must then be passed to the XUA_AudioHub() task appropriately.

I²S/TDM functionality also requires two clock-blocks, one for bit-clock and another for the master clock e.g.:

/* Clock-block declarations */
clock clk_audio_bclk = on tile[0]: XS1_CLKBLK_4; /* Bit clock */
clock clk_audio_mclk = on tile[0]: XS1_CLKBLK_5; /* Master clock */

These hardware resources must be passed into the call to XUA_AudioHub():

/* AudioHub/IO thread does most of the audio IO i.e. I2S (also serves
 * as a hub for all audio) */

on tile[0]: XUA_AudioHub(c_aud, clk_audio_mclk, clk_audio_bclk, p_mclk_in,
    p_lrclk, p_bclk, p_i2s_dac, p_i2s_adc);

lib_xua$$$Advanced usage$$$Mixer£££doc/rst/using_adv_mixer.html#mixer

Since the mixer has no I/O the instantiation is straight forward. Communication wise, the mixer threads are inserted between the AudioHub and Buffering thread(s)

It takes three channel ends as parameters, one for audio to/from the buffering thread(s), one for audio to/from the AudioHub thread and another one for control requests from the Endpoint0 thread.

The mixer task will automatically handle the change in mix count based on the current sample frequency (communicated via the data channels from the buffering task).

An example of how the mixer task might be called is shown below (some parameter lists are abbreviated)

chan c_aud_0, c_aud_1, c_mix_ctl;

par
{
    XUA_Buffer(..., c_aud_0, ...);

    mixer(c_aud0, c_aud_1, c_mix_ctl);

    XUA_AudioHub(c_aud_1, ...);

    XUA_Endpoint0(..., c_mix_ctl, ...);
}

lib_xua$$$Additional features$$$S/PDIF transmit£££doc/rst/feat_spdif_tx.html#s-pdif-transmit

lib_xua supports the development of devices with S/PDIF transmit functionality through the use of lib_spdif. The XMOS S/PDIF transmitter runs on a single thread and supports rates up to 192 kHz.

The S/PDIF transmitter thread takes PCM audio samples via a channel and outputs them in S/PDIF format to a port. Samples are provided to the S/PDIF transmitter task from the XUA_AudioHub() task.

The channel should be declared as normal:

chan c_spdif_tx

In order to use the S/PDIF transmitter with lib_xua a 1-bit port must be declared e.g:

buffered out port:32 p_spdif_tx = PORT_SPDIF_OUT;     /* SPDIF transmit port */

This port should be clocked from the master-clock, lib_spdif provides a helper function for setting up the port:

spdif_tx_port_config(p_spdif_tx, clk_audio_mclk, p_mclk_in, delay);

Finally the S/PDIF transmitter task must be run - passing in the port and channel for communication with XUA_AudioHub. For example:

par
{
    while(1)
    {
        /* Run the S/PDIF transmitter task */
        spdif_tx(p_spdif_tx, c_spdif_tx);
    }

    /* AudioHub/IO thread does most of the audio IO i.e. I2S (also serves as
     * a hub for all audio).
     * Note, since we are not using I2S we pass in null for LR and Bit
     * clock ports and the I2S dataline ports */
    XUA_AudioHub(c_aud, clk_audio_mclk, null, p_mclk_in, null, null,
        null, null, c_spdif_tx);
}

For further details please see the documentation, application notes and examples provided for lib_spdif.

lib_xua$$$Additional features$$$S/PDIF receive£££doc/rst/feat_spdif_rx.html#s-pdif-receive

lib_xua supports the development of devices with S/PDIF receive functionality through the use of lib_spdif. The XMOS S/PDIF receiver runs on a single thread and supports rates up to 192 kHz.

The S/PDIF receiver inputs data via a port and outputs samples via a channel. It requires a 1-bit port. For example:

in port p_spdif_rx = PORT_SPDIF_IN;

It also requires a clock-block, for example:

clock clk_spd_rx = XS1_CLKBLK_1;

Finally, a channel for the output samples must be declared, note, this should be a streaming channel:

streaming chan c_spdif_rx;

The S/PDIF receiver should be called on the appropriate tile:

spdif_rx(c_spdif_rx, p_spdif_rx, clk_spd_rx, 192000);

With the steps above an S/PDIF stream can be captured by the xcore. To be functionally useful the audio master clock must be able to synchronise to this external digital stream. Additionally, the host can be notified regarding changes in the validity of this stream, it’s frequency etc.

To synchronise to external streams the codebase assumes the use of an external Cirrus Logic CS2100 device or lib_sw_pll on xcore.ai designs.

The ClockGen() task from lib_xua provides the reference signal to the CS2100 device or timing information to lib_sw_pll and also handles recording of clock validity etc. See External clock recovery (Clock Gen) for full details regarding ClockGen().

It also provides a small FIFO for S/PDIF samples before they are forwarded to the AudioHub thread. As such it is required to be inserted in the communication path between the S/PDIF receiver and the AudioHub thread. For example:

chan c_dig_rx;
streaming chan c_spdif_rx;

par
{
    SpdifReceive(..., c_spdif_rx, ...);

    clockGen(c_spdif_rx, ..., c_dig_rx, ...);

    XUA_AudioHub(..., c_dig_rx, ...);
}

lib_xua$$$Additional features$$$ADAT transmit£££doc/rst/feat_adat_tx.html#adat-transmit

lib_xua supports the development of devices with ADAT transmit functionality through the use of lib_adat. The XMOS ADAT transmitter runs on a single thread and supports transmitting 8 channels of digital audio at 44.1 or 48 kHz. Higher rates are supported with a reduced number of samples via S/MUX (‘sample multiplexing’). Using S/MUX, the ADAT transmitter can transmit four channels at 88.2 or 96 kHz (SMUX II) or two channels at 176.4 or 192 kHz (SMUX IV).

ADAT transmitter requires a thread to run on. Blocks of audio samples are transmitted from the XUA_AudioHub() to the ADAT transmitter over either a dedicated channel or a combination of a channel and shared memory.

Each block of audio samples is made of 8 samples. At sampling rates 44.1/48 kHz (SMUX I), this consists of a single sample of each of the eight ADAT channels:

• Channel 0 sample

• Channel 1 sample

• Channel 2 sample

• Channel 3 sample

• Channel 4 sample

• Channel 5 sample

• Channel 6 sample

• Channel 7 sample

At 88.2/96 kHz (SMUX II), the audio sample block consists of two samples per four ADAT channels:

• Channel 0 sample 0

• Channel 0 sample 1

• Channel 1 sample 0

• Channel 1 sample 1

• Channel 2 sample 0

• Channel 2 sample 1

• Channel 3 sample 0

• Channel 3 sample 1

At 176.4/192 kHz (SMUX IV), the audio sample block consists of four samples per two ADAT channels:

• Channel 0 sample 0

• Channel 0 sample 1

• Channel 0 sample 2

• Channel 0 sample 3

• Channel 1 sample 0

• Channel 1 sample 1

• Channel 1 sample 2

• Channel 1 sample 3

The configuration option ADAT_TX_USE_SHARED_BUFF determines whether the audio samples block is transmitted using only a channel (ADAT_TX_USE_SHARED_BUFF is not defined) or a channel + shared memory (ADAT_TX_USE_SHARED_BUFF is defined). When using a channel + shared memory for samples transfer, it is required that the ADAT transmitter and the XUA_AudioHub() tasks run on the same tile.

The USB Audio reference applications with ADAT interface enabled in sw_usb_audio are only tested with ADAT_TX_USE_SHARED_BUFF defined. The sample transfer sequence described in Sample communication assumes that ADAT_TX_USE_SHARED_BUFF is defined.

chan c_adat_out

on stdcore[AUDIO_IO_TILE] : buffered out port:32 p_adat_tx  = PORT_ADAT_OUT;

configure_out_port_no_ready(p_adat_tx, clk_audio_mclk, 0);
set_clock_fall_delay(clk_audio_mclk, 7);

adat_tx_port(c_adat_out, p_adat_tx);

lib_xua$$$Additional features$$$ADAT transmit$$$Sample communication£££doc/rst/feat_adat_tx.html#sample-communication

Samples are communicated between XUA_AudioHub() and the adat_tx_port() task.

The interface to the ADAT transmitter task is via a normal channel with streaming builtins (outuint, inuint).

To begin with, XUA_AudioHub sends two values on the channel - the master clock multiplier and the S/MUX setting.

The master clock multiplier is the ratio between the mclk freqency and the sampling frequency. The S/MUX setting is 1, 2 or 4, depending on the sampling frequency:

            /* Calculate what master clock we should be using */
            if (((MCLK_441) % curSamFreq) == 0)
            {
                mClk = MCLK_441;
#if (XUA_ADAT_TX_EN)
                /* Calculate ADAT SMUX mode (1, 2, 4) */
                adatSmuxMode = curSamFreq / 44100;
                adatMultiple = mClk / 44100;
#endif
            }
            else if (((MCLK_48) % curSamFreq) == 0)
            {
                mClk = MCLK_48;
#if (XUA_ADAT_TX_EN)
                /* Calculate ADAT SMUX mode (1, 2, 4) */
                adatSmuxMode = curSamFreq / 48000;
                adatMultiple = mClk / 48000;
#endif
            }

This is followed by communicating the address of a block of memory holding the audio samples block. The XUA_AudioHub “runs ahead” of the ADAT transmitter task, assembling the next sample block while the ADAT transmitter converts the current block into an ADAT stream to transmit over the optical interface.

The ADAT transmitter, once done processing the current block, acknowledges this by sending a data token over the channel to XUA_AudioHub as a handshake mechanism. On receiving this handshake, XUA_AudioHub sends the address of the next block of samples over the channel.

Note that a XS1_CT_END control token is not sent between blocks of data, leading to the channel remaining open and getting used as a streaming channel.

XUA_AudioHub only terminates the connection by sending a XS1_CT_END token when there’s a sampling frequency change that requires the XUA_AudioHub task to re-communicate the master clock multiplier and the S/MUX setting.

In case of a sampling frequency change, the XUA_AudioHub() task receives the pending handshake from the ADAT transmitter, followed by sending the XS1_CT_END token indicating the end of data streaming to the ADAT task. A fresh transmission is then started by sending the new master clock multiplier and the S/MUX setting to the ADAT transmitter, followed by audio blocks transfer as described above.

Fig. 2 describes the communication between XUA_AudioHub and the ADAT transmitter:

For further details please see the documentation and examples provided with lib_adat.

lib_xua$$$Additional features$$$ADAT receive£££doc/rst/feat_adat_rx.html#adat-receive

lib_xua supports the development of devices with ADAT receive functionality through the use of lib_adat. The XMOS ADAT receiver runs on a single thread.

The ADAT receive component receives up to eight channels of audio at a sample rate of 44.1kHz or 48kHz. The API for calling the receiver functions is described in the ADAT receive example in lib_adat .

The component outputs 32 bits words split into nine word frames. The frames are laid out in the following manner:

• Control byte

• Channel 0 sample

• Channel 1 sample

• Channel 2 sample

• Channel 3 sample

• Channel 4 sample

• Channel 5 sample

• Channel 6 sample

• Channel 7 sample

An example of how to read the output of the ADAT component is shown below:

control = inuint(oChan);

for(int i = 0; i < 8; i++)
{
    sample[i] = inuint(oChan);
}

Samples are 24-bit values contained in the lower 24 bits of the word.

The control word comprises four control bits in bits [11..8] and the value 0b00000001 in bits [7..0]. This control word enables synchronization at a higher level, in that, on the channel, a single odd word is always read followed by eight words of data.

lib_xua$$$Implementation detail$$$Audio Hub and I²S£££doc/rst/sw_audio.html#audio-hub-and-i2s

The AudioHub task performs many functions. It receives and transmits samples from/to the Decoupler or Mixer thread over a channel.

It also drives several in and out I²S/TDM channels to/from a CODEC, DAC, ADC etc. From now on these external devices will be termed “audio hardware”.

If the firmware is configured with the xcore as I²S master the required clock lines will also be driven from this task. It also has the task of forwarding on and receiving samples to/from other audio related tasks/threads such as S/PDIF tasks, ADAT etc.

In master mode, the xcore generates the I²S “Continuous Serial Clock” (SCK), or “Bit-Clock” (BCLK) and the “Word Select” (WS) or “Left-Right Clock” (LRCLK) signals. Any CODEC or DAC/ADC combination that supports I²S and can be used.

The LR-clock, bit-clock and data are all derived from the incoming master clock (typically the output of the external oscillator or PLL). This is not part of the I²S standard but is commonly included for synchronizing the internal operation of the analog/digital converters.

The Audio Hub task is implemented in the file xua_audiohub.xc.

Table 30 shows the signals used to communicate audio between the XMOS device and the external audio hardware.

The bit clock controls the rate at which data is transmitted to and from the external audio hardware.

In the case where the xcore is the master, it divides the MCLK to generate the required signals for both BCLK and LRCLK, with BCLK then being used to clock data in (SDIN) and data out (SDOUT) of the external audio hardware.

Table 31 shows some example clock frequencies and divides for different sample rates:

For xcore-200 devices the master clock must be supplied by an external source e.g. clock generator, fixed oscillators, PLL etc. xcore.ai devices may use the integrated secondary PLL.

Two master clock frequencies are required to support 44.1 kHz and 48 kHz audio frequencies (e.g. 11.2896/22.5792MHz and 12.288/24.576MHz respectively). This master clock input is then provided to the external audio hardware and the xcore device.

lib_xua$$$Implementation detail$$$Audio Hub and I²S$$$Port configuration (xcore master)£££doc/rst/sw_audio.html#port-configuration-xcore-master

The default software configuration is of xcore being the I²S master. That is, the xcore device provides the BCLK and LRCLK signals to the external audio hardware

xcore ports and clocks provide many valuable features for implementing I²S. This section describes how these are configured and used to drive the I²S interface.

The code to configure the ports and clocks is in the ConfigAudioPorts() function. Developers should not need to modify this.

The xcore inputs MCLK and divides it down to generate BCLK and LRCLK.

To achieve this MCLK is input into the device using the 1-bit port p_mclk. This is attached to the clock block clk_audio_mclk, which is in turn used to clock the BCLK port, p_bclk. BCLK is used to clock the LRCLK (p_lrclk) and data signals SDIN (p_sdin) and SDOUT (p_sdout).

Again, a clock block is used (clk_audio_bclk) which has p_bclk as its input and is used to clock the ports p_lrclk, p_sdin and p_sdout. Fig. 3 shows the connectivity of ports and clock blocks.

p_sdin and p_sdout are configured as buffered ports with a transfer width of 32, so all 32 bits are input in one input statement. This allows the software to input, process and output 32-bit words, whilst the ports serialize and deserialize to the single I/O pin connected to each port.

Unlike previous xcore devices, xcore-200 (XS2 architecture) and xcore.ai (XS3 architecture) series devices have the ability to divide an external clock in a clock-block.

The bit clock outputs 32 clock cycles per sample. In the special case where the divide is 1 (i.e. the bit clock frequency equals the master clock frequency), the p_bclk port is set to a special mode where it simply outputs its clock input (i.e. p_mclk). See configure_port_clock_output() in xs1.h for details.

p_lrclk is clocked by p_bclk. In I²S mode the port outputs the pattern 0x7fffffff followed by 0x80000000 repeatedly. This gives a signal that has a transition one bit-clock before the data (as required by the I²S standard) and alternates between high and low for the left and right channels of audio.

lib_xua$$$Implementation detail$$$Endpoint 0: Management and control£££doc/rst/sw_ep0.html#endpoint-0-management-and-control

All USB devices must support a mandatory control endpoint, Endpoint 0. This controls the management tasks of the USB device.

These tasks can be generally split into enumeration, audio configuration and firmware upgrade requests.

lib_xua$$$Implementation detail$$$Audio endpoints (Endpoint Buffer and Decoupler)£££doc/rst/sw_ep0.html#audio-endpoints-endpoint-buffer-and-decoupler

lib_xua$$$Implementation detail$$$XMOS USB Device (XUD) library£££doc/rst/sw_xud.html#xmos-usb-device-xud-library

All low level communication with the USB host is handled by the XMOS USB Device (XUD) library - lib_xud

The XUD_Main() function runs in its own thread and communicates with endpoint threads though a mixture of shared memory and channel communications.

For more details and full XUD API documentation please refer to lib_xud.

Fig. 1 shows the XUD library communicating with two other threads:

• Endpoint 0: This thread controls the enumeration/configuration tasks of the USB device.

• Endpoint Buffer: This thread sends/receives data packets from the XUD library. The thread receives audio data from the AudioHub, MIDI data from the MIDI thread etc.

lib_xua$$$Implementation detail$$$External clock recovery (Clock Gen)£££doc/rst/sw_clocking.html#external-clock-recovery-clock-gen

To provide an audio master clock an application may use selectable oscillators, clock generation IC or, in the case of xcore.ai devices, an integrated secondary PLL, to generate fixed master clock frequencies.

It may also use an external PLL/Clock Multiplier to generate a master clock based on a reference from the xcore.

Using the internal secondary PLL on an external PLL/Clock Multiplier allows an Asynchronous mode design to lock to an external clock source from a digital stream (e.g. S/PDIF or ADAT input). lib_xua supports the Cirrus Logic CS2100 device or use of lib_sw_pll (xcore.ai only) for this purpose. Other devices may be supported via code modification.

The Clock Recovery thread (Clock Gen) is responsible for either generating the reference frequency to the CS2100 device or driving lib_sw_pll from time measurements based on the local master clock and the time of received samples. Clock Gen (via CS2100 or lib_sw_pll) generates the master clock used over the whole design. This thread also serves as a smaller buffer between ADAT and S/PDIF receiving threads and the Audio Hub thread.

When using lib_sw_pll (xcore.ai only) a further thread is instantiated which performs the sigma-delta modulation of the xcore PLL to ensure the lowest jitter over the audio band. See lib_sw_pll documentation for further details.

When running in Internal Clock mode this thread simply generates this clock using a local timer, based on the xcore’s internal 100 MHz reference clock.

When running in an external clock mode (i.e. S/PDIF Clock” or “ADAT Clock” mode) samples are received from the S/PDIF and/or ADAT receive thread. The external frequency is calculated through counting samples in a given period. Either the reference clock to the CS2100 is then generated based on the reception of these samples or the timing information is provided to lib_sw_pll to generate the phase-locked clock on-chip (xcore.ai only).

If an external stream becomes invalid, the Internal Clock timer event will fire to ensure that valid master clock generation continues regardless of cable unplugs etc. Efforts are made to ensure that the transitions between these clocks are relatively seamless. Additionally efforts are also made to try and keep the jitter on the reference clock as low as possible, regardless of activity level of the Clock Gen thread. The is achieved though the use of port times to schedule pin toggling rather than directly outputting to the port in the case of using the CS2100. For lib_sw_pll cases the last setting is kept for the sigma-delta modulator ensuring clock continuity.

The Clock Gen thread gets clock selection Get/Set commands from Endpoint 0 via the c_clk_ctl channel. This thread also records the validity of external clocks, which is also queried through the same channel from Endpoint 0. Note, the Internal Clock is always reported as being valid. It should be noted that the device always reports the current device sample rate regardless of the clock being interrogated. This results in improved user experience for most driver/operating system combinations

To inform the host of any status change, the Clock Gen thread can also cause the Decouple thread to request an interrupt packet on change of clock validity. This functionality is based on the Audio Class 2.0 status/interrupt endpoint feature.

lib_xua$$$Implementation detail$$$Digital mixer£££doc/rst/sw_mixer.html#digital-mixer

The Mixer thread(s) take outgoing audio from the Decouple thread and incoming audio from the Audio Hub thread. It then applies the volume to each channel and passes incoming audio on to Decouple and outgoing audio to Audio Hub. The volume update is achieved using the built-in 32bit to 64bit signed multiply-accumulate function (macs). The mixer is implemented in the file mixer.xc.

The mixer takes (up to) two threads and can perform eight mixes with up to 18 inputs at sample rates up to 96kHz and two mixes with up to 18 inputs at higher sample rates. The component automatically reverts to generating two mixes when running at the higher rate.

The mixer can take inputs from either:

• The USB outputs from the host—these samples come from the Decouple thread.

• The inputs from the audio interfaces on the device—these samples come from the Audio Hub thread and includes samples from digital input streams.

Since the sum of these inputs may be more than the 18 possible mix inputs to each mixer, there is a mapping from all the possible inputs to the mixer inputs.

After the mix occurs, the final outputs are created. There are two possible output destinations for each mix.

• The USB inputs to the host—these samples are sent to the Decouple thread.

• The outputs to the audio interface on the device—these samples are sent to the Audio Hub thread

For each possible output from the device, a mapping exists to inform the mixer what its source is. The possible sources are the output from the USB host, the inputs from the Audio Hub thread or the outputs from the mixes.

Essentially the mixer/router can be configured such that any device input can be used as an input to any mix or routed directly to any device output. Additionally, any device output can be derived from any mixer output or any device input.

As mentioned in Audio Request: Volume control, the mixer can also handle processing of volume controls. If the mixer is configured to handle volume but the number of mixes is set to zero (such that the thread is solely doing volume setting) then the component will use only one thread. This is sometimes a useful configuration for large channel count devices since it offloads volume processing from the buffering sub-system.

A sequence diagram showing the communication between Audio Hub, Decouple and mixer threads is shown in Fig. 5. mixer1 thread exchanges data with Decouple and Audio Hub along with any volume control operations and performs the mixing operations for the even output channel numbers. The mixing for the odd channels is offloaded to the mixer2 thread.

The mixer can also be configured in passthrough mode (MAX_MIX_COUNT = 0), as shown in Fig. 7. In this mode, the mixer2 thread is not present and the mixer1 exchanges data with Audio Hub and Decouple along with any volume control operations without doing any actual mixing.

$ ./xmos_mixer --help

$ ./xmos_mixer --display-aud-channel-map

  Audio Output Channel Map
  ------------------------

0 (DEVICE OUT - Analogue 1) source is  0 (DAW OUT - Analogue 1)
1 (DEVICE OUT - Analogue 2) source is  1 (DAW OUT - Analogue 2)
2 (DEVICE OUT - SPDIF 1) source is  2 (DAW OUT - SPDIF 1)
3 (DEVICE OUT - SPDIF 2) source is  3 (DAW OUT - SPDIF 2)
$ _

$ ./xmos_mixer --display-daw-channel-map

  DAW Output To Host Channel Map
  ------------------------

0 (DEVICE IN - Analogue 1) source is  4 (DEVICE IN - Analogue 1)
1 (DEVICE IN - Analogue 2) source is  5 (DEVICE IN - Analogue 2)
$ _

$ ./xmos_mixer --display-aud-channel-map-sources

  Audio Output Channel Map Source List
  ------------------------------------

0 (DAW OUT - Analogue 1)
1 (DAW OUT - Analogue 2)
2 (DAW OUT - SPDIF 1)
3 (DAW OUT - SPDIF 2)
4 (DEVICE IN - Analogue 1)
5 (DEVICE IN - Analogue 2)
6 (MIX - Mix 1)
7 (MIX - Mix 2)
$ _

$ ./xmos_mixer --set-aud-channel-map 0 6
$ ./xmos_mixer --set-aud-channel-map 1 7
$ _

$ ./xmos_mixer --display-aud-channel-map

  Audio Output Channel Map
  ------------------------

0 (DEVICE OUT - Analogue 1) source is  6 (MIX - Mix 1)
1 (DEVICE OUT - Analogue 2) source is  7 (MIX - Mix 2)
2 (DEVICE OUT - SPDIF 1) source is  2 (DAW OUT - SPDIF 1)
3 (DEVICE OUT - SPDIF 2) source is  3 (DAW OUT - SPDIF 2)
$ _

$ ./xmos_mixer --display-mixer-nodes 0

  Mixer Values (0)
  ----------------

                       Mixer outputs
                                1              2
  DAW - Analogue 1       0:[0000.000]   1:[  -inf  ]
  DAW - Analogue 2       2:[  -inf  ]   3:[0000.000]
  DAW - SPDIF 1          4:[  -inf  ]   5:[  -inf  ]
  DAW - SPDIF 2          6:[  -inf  ]   7:[  -inf  ]
  AUD - Analogue 1       8:[  -inf  ]   9:[  -inf  ]
  AUD - Analogue 2      10:[  -inf  ]  11:[  -inf  ]
$ _

$ ./xmos_mixer --set-value 0 8 0
$ ./xmos_mixer --set-value 0 11 0
$ _

$ ./xmos_mixer --set-value 0 0 -inf
$ ./xmos_mixer --set-value 0 3 -inf
$ _

$ ./xmos_mixer --set-value 0 8 -inf
$ ./xmos_mixer --set-value 0 11 -inf
$ ./xmos_mixer --set-value 0 0 0
$ ./xmos_mixer --set-value 0 3 0
$ _

$ ./xmos_mixer --set-mixer-source 0 0 4

   Set mixer(0) input 0 to device input 4 (AUD - Analogue 1)
$ ./xmos_mixer --set-mixer-source 0 1 5

   Set mixer(0) input 1 to device input 5 (AUD - Analogue 2)
$ _

$ ./xmos_mixer --display-mixer-nodes 0

lib_xua$$$Implementation detail$$$S/PDIF transmit£££doc/rst/sw_spdif.html#s-pdif-transmit

lib_xua supports the development of devices with S/PDIF transmit through the use of lib_spdif. The XMOS S/SPDIF transmitter component runs in a single thread and supports sample-rates upto 192 kHz.

The S/PDIF transmitter thread takes PCM audio samples via a channel and outputs them in S/PDIF format to a port. A lookup table is used to encode the audio data into the required format.

It receives samples from the Audio I/O thread two at a time (for left and right). For each sample, it performs a lookup on each byte, generating 16 bits of encoded data which it outputs to a port.

S/PDIF sends data in frames, each containing 192 samples of the left and right channels.

Audio samples are encapsulated into S/PDIF words (adding preamble, parity, channel status and validity bits) and transmitted in biphase-mark encoding (BMC) with respect to an external master clock.

lib_xua$$$Implementation detail$$$S/PDIF transmit$$$Clocking£££doc/rst/sw_spdif.html#clocking

The S/PDIF signal is output at a rate dictated by the external master clock. The master clock must be 1x 2x or 4x the BMC bit rate (that is 128x 256x or 512x audio sample rate, respectively). For example, the minimum master clock frequency for 192kHz is therefore 24.576 MHz.

This resamples the master clock to its clock domain (oscillator), which introduces jitter of 2.5-5 ns on the S/PDIF signal. A typical jitter-reduction scheme is an external D-type flip-flop clocked from the master clock (as shown in Fig. 9).

lib_xua$$$Implementation detail$$$S/PDIF receive£££doc/rst/sw_spdif_rx.html#s-pdif-receive

xcore devices can support S/PDIF receive up to 192 kHz - see lib_spdif for full specifications.

The S/PDIF receiver module uses a clock-block and a buffered one-bit port. The clock-block is divided off a 100 MHz reference clock. The one bit port is buffered to 32 bits. The receiver code uses this clock to over sample the input data.

The receiver outputs audio samples over a streaming channel end where data can be input using the built-in input operator. lib_spdif also provides API functions that wrap up this communication.

The S/PDIF receive function never returns. The 32-bit value from the channel input comprises of fields shown in Table 39.

The tag has one of three values, as shown in Table 40.

See S/PDIF, IEC 60958-3:2006, specification for further details on format, user bits etc.

                /* Check parity and ignore if bad */
                if(spdif_rx_check_parity(spdifRxData))
                    continue;

while(1)
{
   c_spdif_rx :> data;

   if(spdif_check_parity(data)
     continue;

   tag = data & SPDIF_RX_PREAMBLE_MASK;

   /* Extract 24bit audio sample */
   sample = SPDIF_RX_EXTRACT_SAMPLE(data);

   switch(tag)
   {
     case SPDIF_FRAME_X:
     case SPDIF_FRAME_X:
       // Store left sample
       break;

     case SPDIF)FRAME_Z:
       // Store right sample
       break;
   }
}

lib_xua$$$Implementation detail$$$MIDI£££doc/rst/sw_midi.html#midi

The MIDI thread implements a 31250 baud UART (8-N-1) for both input and output. It uses a single dedicated thread which performs multiple functions:

• UART transmit (tx) peripheral.

• UART transmit FIFO of 1024 bytes (may be configured by the user).

• Decoding of USB MIDI message to bytes.

• UART receive (rx) peripheral.

• Packing of received MIDI bytes into USB MIDI messages/events.

It is connected via a channel to the Endpoint Buffer thread meaning that it can be placed on any xcore tile in the system subject to resource availability.

The Endpoint Buffer thread implements the two Bulk endpoints (one In and one Out) as well as interacting with small, shared-memory, FIFOs for each endpoint.

On receiving 32-bit USB MIDI events from the Endpoint Buffer thread over the channel, the MIDI thread parses these and translates them to 8-bit MIDI messages which are sent out over the UART. Up to 1024 bytes may be buffered by the MIDI task for outgoing messages in the default configuration. If the outgoing buffer is full then it will cause the USB endpoint to be NACKed which provides flow control in the case that the host application sends messages faster than the UART can transmit them. This is important because the USB bandwidth far exceeds the MIDI UART bandwidth by many orders of magnitude. The combination of buffering and flow control ensures outgoing messages are not dropped during normal operation.

Incoming 8-bit MIDI messages from the UART receiver are packed into 32-bit USB MIDI events and passed on to the Endpoint Buffer thread. Since the rate of ingress to the MIDI port is tiny in comparison to the host USB bandwidth, no buffering is required in the MIDI thread and the MIDI events are always forwarded on directly to USB immediately.

All MIDI message types are supported including Sysex (MIDI System Exclusive) strings allowing custom function such as bank updates and patches, backup and device firmware upgrade (DFU) where supported by the MIDI device.

The MIDI thread is implemented in the file usb_midi.xc and the USB buffering is handled in the file ep_buffer.xc.

lib_xua$$$Implementation detail$$$PDM microphones£££doc/rst/sw_pdm.html#pdm-microphones

lib_xua is capable of integrating with PDM microphones. The PDM stream from the microphones is converted to PCM and output to the host via USB.

Interfacing to the PDM microphones is done using the XMOS microphone array library (lib_mic_array). lib_mic_array is designed to allow interfacing to PDM microphones coupled to efficient decimation filters at a user configurable output sample rate. Currently dynamic sample rate changing is not supported.

Up to eight PDM microphones can be attached the PDM interface (mic_array_task()) but it is possible to extend this.

After PDM capture and decimation to the output sample-rate various other steps take place e.g. DC offset elimination etc. Please refer to the documentation provided with lib_mic_array for further implementation detail and a complete feature set.

By default the sample rates supported are 16 kHz, 32 kHz and 48 kHz although other rates are supportable with some modifications.

Please see AN00248 Using lib_xua with lib_mic_array for a practical example of this feature.

void user_pdm_init();
void user_pdm_process(int32_t mic_audio[MIC_ARRAY_CONFIG_MIC_COUNT]);

lib_xua$$$Implementation detail$$$Audio controls via Human Interface Device (HID)£££doc/rst/sw_hid.html#audio-controls-via-human-interface-device-hid

The design supports simple audio controls such as play/pause, volume up/down etc via the USB Human Interface Device Class Specification.

This functionality is enabled by setting the HID_CONTROLS define to 1. Setting to 0 disables this feature.

When turned on the following items are enabled:

1. HID descriptors are enabled in the Configuration Descriptor informing the host that the device has a HID interface.

2. A Get Report Descriptor request is enabled in endpoint0.

3. Endpoint data handling is enabled in the buffer thread.

The Get Descriptor Request enabled in endpoint 0 returns the report descriptor for the HID device. This details the format of the HID reports returned from the device to the host. It maps a bit in the report to a function such as play/pause.

The USB Audio Framework implements a report descriptor that should fit most basic audio device controls. If further controls are necessary the HID Report Descriptor in hid_report_descriptor.h should be modified. The default report size is 1 byte with the format as follows:

On each HID report request from the host the function UserHIDGetData() is called from XUA_Buffer_Ep(). This function is passed an array hidData[] by reference. The programmer should report the state of the buttons into this array. For example, if a volume up command is desired, bit 3 should be set to 1, else 0.

Since the UserHIDGetData() function is called from the XUA_Buffer_Ep() thread, care should be taken not to add to much execution time to this function since this could cause issues with servicing other endpoints.

lib_xua$$$Implementation detail$$$Device Firmware Upgrade (DFU) over USB£££doc/rst/sw_dfu.html#device-firmware-upgrade-dfu-over-usb

The DFU implementation in lib_xua is compliant with version 1.1 of Universal Serial Bus Device Class Specification for Device Firmware Upgrade.

This section describes the DFU implementation in lib_xua. For information about using a DFU loader to send DFU commands to the USB Audio device, refer to appnote AN02019: Using Device Firmware Upgrade (DFU) in USB Audio.

The USB device descriptors expose a DFU interface that handles updates to the boot image of the device over USB.

The host sends DFU requests as Host to Device Class requests to the DFU interface. On receiving DFU commands from the host, the DFUDeviceRequests function is called from the Endpoint 0 thread. This function calls the DFU handler functions over the dfuInterface XC interface. The DFU handler thread, DFUHandler that implements the server side of the dfuInterface has to be scheduled on the same tile as the flash so it can access the flash memory. The dfuInterface interface essentially links USB to the XMOS flash user library.

The DFU interface is enabled by default (See XUA_DFU_EN define in xua_conf_default.h). When DFU is enabled, there are two sets of descriptors that the device can export, depending on the mode in which it operates. There is a descriptor set for the runtime mode, which is the mode the device normally operates in and a set of descriptors for the DFU mode.

In the runtime mode, the DFU interface is one of potentially multiple interfaces that the device exposes. Fig. 11 shows the DFU interface descriptors when enumerating in runtime mode as seen in a Beagle USB analyser trace.

Note the bInterfaceProtocol field set to Runtime.

In DFU mode, the device exports the DFU descriptor set. The DFU mode descriptors specify only one interface, the DFU interface. Fig. 12 shows the DFU interface descriptors when enumerating in DFU mode as seen in a Beagle USB analyser trace.

Note the bInterfaceProtocol field set to DFU mode.

Before starting the DFU upload or download process, the host sends a DFU_DETACH command to detach the device from runtime to DFU mode. In response to the DFU_DETACH command, the device reboots itself into DFU mode and enumerates using the DFU mode descriptors. Once the device is in DFU mode, the DFU interface can accept commands defined by the DFU 1.1 class specification.

After detaching the device, the host proceeds with the DFU download/upload commands to write/read the firmware upgrade image to/from the device. Once the DFU download or upload process is complete, the host sends a DETACH command, and the device reboots itself back in runtime mode.

During the DFU download process, on receiving the first DFU_DNLOAD command (wBlockNum = 0), the device erases FLASH_MAX_UPGRADE_SIZE bytes of the upgrade section of the flash. This is done by repeatedly calling flash_cmd_start_write_image and can take several seconds. To avoid the DFU_DNLOAD request timing out, the flash erase is instead done in the DFU_GETSTATUS handling code for block 0. So for block 0, the device ends up returning the status as dfuDNBUSY several times while the flash erase is in progress. Fig. 13 describes the DFU download process.

#define REQUEST_GET_MS_DESCRIPTOR   0x20

lib_xua$$$Implementation detail$$$Resource usage£££doc/rst/sw_resource.html#resource-usage

The following table details the resource usage of each component of the reference design software. Note, memory usage is approximate and varies based on device used, compiler settings etc.

These resource estimates are based on the multichannel reference design with all options of that design enabled. For fewer channels, the resource usage is likely to decrease.

lib_xua$$$API reference$$$Configuration defines£££doc/rst/api_defines.html#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).

lib_xua$$$API reference$$$User function definitions£££doc/rst/api_user_functions.html#user-function-definitions

The following functions can be defined by an application using lib_xua.

lib_xua$$$API reference$$$Component API£££doc/rst/api_component.html#component-api

The following functions can be called from the top level main of an application and implement the various components described in Software architecture.

When using the USB audio framework the c_ep_in array is always composed in the following order:

• Endpoint 0 (in)

• Audio Feedback endpoint (if output enabled)

• Audio IN endpoint (if input enabled)

• MIDI IN endpoint (if MIDI enabled)

• Clock Interrupt endpoint

The array c_ep_out is always composed in the following order:

• Endpoint 0 (out)

• Audio OUT endpoint (if output enabled)

• MIDI OUT endpoint (if MIDI enabled)

void XUA_Endpoint0(

chanend c_ep0_out,

chanend c_ep0_in,

NULLABLE_RESOURCE(chanend, c_aud_ctl),

NULLABLE_RESOURCE(chanend, c_mix_ctl),

NULLABLE_RESOURCE(chanend, c_clk_ctl),

NULLABLE_CLIENT_INTERFACE(i_dfu, dfuInterface),

)

Endpoint 0 task for USB Audio devices

Function implementing Endpoint 0 for enumeration, control and configuration of USB audio devices. It uses the descriptors defined in xua_ep0_descriptors.h.

Parameters:

• c_ep0_out – Chanend connected to the XUD_Main() out endpoint array

• c_ep0_in – Chanend connected to the XUD_Main() in endpoint array

• c_aud_ctl – Chanend connected to the decouple thread for control audio (sample rate changes etc.). Note when nulled, the audio device only supports single sample rate/format and DFU is not supported either since this channel is used to carry messages about format, rate and DFU state

• c_mix_ctl – Optional chanend to be connected to the mixer core(s) if present

• c_clk_ctl – Optional chanend to be connected to the clockgen core if present

• dfuInterface – Interface to DFU task (this task must be run on a tile connected to boot flash.

void XUA_Buffer(

chanend c_aud_out,

chanend c_aud_in,

chanend c_aud_fb,

chanend c_midi_from_host,

chanend c_midi_to_host,

chanend c_midi,

NULLABLE_RESOURCE(chanend, c_int),

NULLABLE_RESOURCE(chanend, c_clk_int),

chanend c_sof,

chanend c_aud_ctl,

NULLABLE_RESOURCE(in_port_t, p_off_mclk),

chanend c_hid,

chanend c_aud,

chanend c_audio_rate_change,

CLIENT_INTERFACE(pll_ref_if, i_pll_ref),

chanend c_swpll_update,

)

USB Audio Buffering Core(s).

This function buffers USB audio data between the XUD and the audio subsystem. Most of the chanend parameters to the function should be connected to XUD_Manager(). The uses two cores.

Parameters:

• c_aud_out – Audio OUT endpoint channel connected to the XUD

• c_aud_in – Audio IN endpoint channel connected to the XUD

• c_aud_fb – Audio feedback endpoint channel connected to the XUD

• c_midi_from_host – MIDI OUT endpoint channel connected to the XUD

• c_midi_to_host – MIDI IN endpoint channel connected to the XUD

• c_midi – Channel connected to MIDI thread

• c_int – Audio clocking interrupt endpoint channel connected to the XUD

• c_clk_int – Optional chanend connected to the clockGen() thread if present

• c_sof – Start of frame channel connected to the XUD

• c_aud_ctl – Audio control channel connected to Endpoint0()

• p_off_mclk – A port that is clocked of the MCLK input (not the MCLK input itself)

• c_hid – Channel connected to the HID handler thread

• c_aud – Channel connected to XUA_AudioHub() thread

• c_audio_rate_change – Channel to notify and synchronise on audio rate change

• i_pll_ref – Interface to task that toggles reference pin to CS2100

• c_swpll_update – Channel connected to software PLL task. Expects master clock counts based on USB frames.

void XUA_AudioHub(

NULLABLE_RESOURCE(chanend, c_aud),

NULLABLE_RESOURCE(clock, clk_audio_mclk),

NULLABLE_RESOURCE(clock, clk_audio_bclk),

NULLABLE_RESOURCE(in_port_t, p_mclk_in),

NULLABLE_RESOURCE(i2s_clk_port_type, p_lrclk),

NULLABLE_RESOURCE(i2s_clk_port_type, p_bclk),

NULLABLE_ARRAY_OF_SIZE(out_buffered_port_32_t, p_i2s_dac, I2S_WIRES_DAC),

NULLABLE_ARRAY_OF_SIZE(in_buffered_port_32_t, p_i2s_adc, I2S_WIRES_ADC),

chanend c_spdif_tx,

chanend c_dig,

chanend c_audio_rate_change,

NULLABLE_SERVER_INTERFACE(i_dfu, dfuInterface),

chanend c_pdm_in,

)

The audio driver thread.

This function drives I2S ports and handles samples to/from other digital I/O threads.

Parameters:

• c_aud – Audio sample channel connected to the mixer() thread or the decouple() thread

• clk_audio_mclk – Nullable clockblock to be clocked from master clock

• clk_audio_bclk – Nullable clockblock to be clocked from i2s bit clock

• p_mclk_in – Master clock inport port (must be 1-bit). Use null when xcore is slave

• p_lrclk – Nullable port for I2S sample clock

• p_bclk – Nullable port for I2S bit clock

• p_i2s_dac – Nullable array of ports for I2S data output lines

• p_i2s_adc – Nullable array of ports for I2S data input lines

• i_SoftPll – Interface to software PLL task

• c_spdif_tx – Channel connected to S/PDIF transmitter core from lib_spdif

• c_dig – Channel connected to the clockGen() thread for receiving/transmitting samples

• c_audio_rate_change – Channel notifying ep_buffer of an mclk frequency change and sync for stable clock

• dfuInterface – Interface supporting DFU methods

• c_pdm_in – Channel for receiving decimated PDM samples

void mixer(chanend c_to_host, chanend c_to_audio, chanend c_mix_ctl)

Digital sample mixer.

This thread mixes audio streams between the decouple() thread and the audio() thread.

Parameters:

• c_to_host – a chanend connected to the decouple() thread for receiving/transmitting samples

• c_to_audio – a chanend connected to the audio() thread for receiving/transmitting samples

• c_mix_ctl – a chanend connected to the Endpoint0() thread for receiving control commands

void clockGen(

NULLABLE_RESOURCE(streaming_chanend_t, c_spdif_rx),

NULLABLE_RESOURCE(streaming_chanend_t, c_adat_rx),

CLIENT_INTERFACE(pll_ref_if, i_pll_ref),

chanend c_audio,

chanend c_clk_ctl,

chanend c_clk_int,

chanend c_audio_rate_change,

)

Clock generation and digital audio I/O handling.

Parameters:

• c_spdif_rx – channel connected to S/PDIF receive thread

• c_adat_rx – channel connect to ADAT receive thread

• i_pll_ref – interface to taslk that outputs clock signal to drive external frequency synthesizer

• c_audio – channel connected to the audio() thread

• c_clk_ctl – channel connected to Endpoint0() for configuration of the clock

• c_clk_int – channel connected to the decouple() thread for clock interrupts

• c_audio_rate_change – channel to notify of master clock change

• p_for_mclk_count_aud – port used for counting mclk and providing a timestamp

• c_sw_pll – channel used to communicate with software PLL task

void usb_midi(

NULLABLE_RESOURCE(in_buffered_port_1_t, p_midi_in),

NULLABLE_RESOURCE(port, p_midi_out),

NULLABLE_RESOURCE(clock, clk_midi),

NULLABLE_RESOURCE(chanend, c_midi),

unsigned cable_number,

)

USB MIDI I/O task.

This function passes MIDI data between XUA_Buffer and MIDI UART I/O.

Parameters:

• p_midi_in – 1-bit input port for MIDI

• p_midi_out – 1-bit output port for MIDI

• clk_midi – Clock block used for clockin the UART; should have a rate of 100MHz

• c_midi – Chanend connected to the decouple() thread

• cable_number – The cable number of the MIDI implementation. This should be set to 0.