Vergil_Wong/lib_xua
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updates to documentation (#280)

Browse Source 
Documentation updates (including moving of header files
This commit is contained in:
Ross Owen
2022-09-30 16:11:53 +01:00
committed by GitHub
parent 0c368e0356
commit eb86a72882
66 changed files with 2294 additions and 955 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
README.rst
View File

@@ -8,22 +8,22 @@ lib_xua
Summary
-------
USB Audio Shared Components for use in the XMOS USB Audio Refererence Designs.
lib_xua contains shared components for use in the XMOS USB Audio (XUA) Reference Designs.
This library enables the development of USB Audio devices on the XMOS xCORE architecture.
These components enable the development of USB Audio devices on the XMOS xCORE architecture.
Features
........
~~~~~~~~
Key features of the various applications in this repository are as follows
Key features of the various components in this repository are as follows
- USB Audio Class 1.0/2.0 Compliant
- Fully Asynchronous operation
- Fully Asynchronous operation (synchronous mode as an option)
- Support for the following sample frequencies: 8, 11.025, 12, 16, 32, 44.1, 48, 88.2, 96, 176.4, 192, 352.8, 384kHz
- Input/output channel and individual volume/mute controls supported
- Volume/mute controls for input/output (for both master and individual channels)
- Support for dynamically selectable output audio formats (e.g. resolution)
@@ -37,7 +37,7 @@ Key features of the various applications in this repository are as follows
- ADAT input
- Synchronisation to external digital streams i.e. S/PDIF or ADAT
- Synchronisation to external digital streams i.e. S/PDIF or ADAT (when in asynchronous mode)
- I2S slave & master modes
@@ -45,24 +45,30 @@ Key features of the various applications in this repository are as follows
- MIDI input/output (Compliant to USB Class Specification for MIDI devices)
- DSD output (Native and DoP mode) at DSD64 and DSD128 rates
- DSD output ("native" and DoP mode) at DSD64 and DSD128 rates
- Mixer with flexible routing
- Simple playback controls via Human Interface Device (HID)
- Simple playback controls via USB Human Interface Device (HID) Class
- Support for operation with Apple devices (requires software module sc_mfi for MFI licensees only - please contact XMOS)
Note, not all features may be supported at all sample frequencies, simultaneously or on all devices.
Some features may also require specific host driver support.
Note, not all features may be supported at all sample frequencies, simultaneously or on all devices. Some features also require specific host driver support.
Host System Requirements
~~~~~~~~~~~~~~~~~~~~~~~~
Software version and dependencies
.................................
USB Audio devices built using `lib_xua` have the following host system requirements.
The CHANGELOG contains information about the current and previous versions.
For a list of direct dependencies, look for DEPENDENT_MODULES in lib_xua/module_build_info.
- Mac OSX version 10.6 or later
- Windows Vista, 7, 8 or 10 with Thesycon Audio Class 2.0 driver for Windows (Tested against version 3.20). Please contact XMOS for details.
- Windows Vista, 7, 8 or 10 with built-in USB Audio Class 1.0 driver.
Older versions of Windows are not guaranteed to operate as expected. Devices are also expected to operate with various Linux distributions including mobile variants.
Related Application Notes
.........................
~~~~~~~~~~~~~~~~~~~~~~~~~
The following application notes use this library:
@@ -70,14 +76,14 @@ The following application notes use this library:
* AN000247 - Using lib_xua with lib_spdif (transmit)
* AN000248 - Using lib_xua with lib_mic_array
Required software (dependencies)
================================
Required Software (dependencies)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* lib_logging (git@github.com:xmos/lib_logging.git)
* lib_xassert (git@github.com:xmos/lib_xassert.git)
* lib_xud (git@github.com:xmos/lib_xud.git)
* lib_spdif (git@github.com:xmos/lib_spdif.git)
* lib_mic_array (git@github.com:xmos/lib_mic_array.git)
* lib_dsp (git@github.com:xmos/lib_dsp)
* lib_locks (git@github.com:xmos/lib_locks.git)
* lib_logging (https://github.com:xmos/lib_logging)
* lib_xassert (https://github.com:xmos/lib_xassert)
* lib_xud (https://github.com:xmos/lib_xud)
* lib_spdif (https://github.com:xmos/lib_spdif)
* lib_mic_array (https://github.com:xmos/lib_mic_array)
* lib_dsp (https://github.com:xmos/lib_dsp)
* lib_locks (https://github.com:xmos/lib_locks)

12
lib_xua/api/xua.h
View File

@@ -1,20 +1,22 @@
// Copyright 2017-2021 XMOS LIMITED.
// Copyright 2017-2022 XMOS LIMITED.
// This Software is subject to the terms of the XMOS Public Licence: Version 1.
#ifndef _XUA_H_
#define _XUA_H_
#ifndef __XUA_H__
#define __XUA_H__
#include <xs1.h>
#include "xua_conf_full.h"
#if __XC__ || __STDC__
#include "xua_audiohub.h"
#include "xua_endpoint0.h"
#include "xua_buffer.h"
#include "xua_mixer.h"
#endif
#if __XC__
#include "xua_clocking.h"
#include "xua_midi.h"
#if XUA_NUM_PDM_MICS > 0
#include "xua_pdm_mic.h"
#endif

10
lib_xua/api/xua_audiohub.h
View File

@@ -22,7 +22,7 @@
*
* \param clk_audio_mclk Nullable clockblock to be clocked from master clock
*
* \param clk_audio_mclk Nullable clockblock to be clocked from i2s clock
* \param clk_audio_bclk Nullable clockblock to be clocked from i2s bit clock
*
* \param p_mclk_in Master clock inport port (must be 1-bit)
*
@@ -34,7 +34,9 @@
*
* \param p_i2s_adc Nullable array of ports for I2S data input lines
*
* \param c_dig channel connected to the clockGen() thread for
* \param c_spdif_tx Channel connected to S/PDIF transmiter core from lib_spdif
*
* \param c_dig Channel connected to the clockGen() thread for
* receiving/transmitting samples
*/
void XUA_AudioHub(chanend ?c_aud,
@@ -45,10 +47,10 @@ void XUA_AudioHub(chanend ?c_aud,
buffered _XUA_CLK_DIR port:32 ?p_bclk,
buffered out port:32 (&?p_i2s_dac)[I2S_WIRES_DAC],
buffered in port:32 (&?p_i2s_adc)[I2S_WIRES_ADC]
#if (XUA_SPDIF_TX_EN) //&& (SPDIF_TX_TILE != AUDIO_IO_TILE)
#if (XUA_SPDIF_TX_EN) || defined(__DOXYGEN__)
, chanend c_spdif_tx
#endif
#if (XUA_SPDIF_RX_EN || XUA_ADAT_RX_EN)
#if (XUA_SPDIF_RX_EN || XUA_ADAT_RX_EN || defined(__DOXYGEN__))
, chanend c_dig
#endif
#if (XUD_TILE != 0) && (AUDIO_IO_TILE == 0) && (XUA_DFU_EN == 1)

51
lib_xua/api/xua_buffer.h
View File

@@ -5,58 +5,59 @@
#if __XC__
#include "xua.h"
#include "clocking.h"
#include "xua_clocking.h" /* Required for pll_ref_if */
/** USB Audio Buffering Core.
/** USB Audio Buffering Core(s).
*
* This function buffers USB audio data between the XUD layer and the decouple
* thread. Most of the chanend parameters to the function should be connected to
* XUD_Manager()
* 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.
*
* \param c_aud_out Audio OUT endpoint channel connected to the XUD
* \param c_aud_in Audio IN endpoint channel connected to the XUD
* \param c_aud_fb Audio feedback endpoint channel connected to the XUD
* \param c_midi_from_host MIDI OUT endpoint channel connected to the XUD
* \param c_midi_to_host MIDI IN endpoint channel connected to the XUD
* \param c_int Audio clocking interrupt endpoint channel connected to the XUD
* \param c_clk_int Optional chanend connected to the clockGen() thread if present
* \param c_sof Start of frame channel connected to the XUD
* \param c_aud_ctl Audio control channel connected to Endpoint0()
* \param p_off_mclk A port that is clocked of the MCLK input (not the MCLK input itself)
* \param c_aud_out Audio OUT endpoint channel connected to the XUD
* \param c_aud_in Audio IN endpoint channel connected to the XUD
* \param c_aud_fb Audio feedback endpoint channel connected to the XUD
* \param c_midi_from_host MIDI OUT endpoint channel connected to the XUD
* \param c_midi_to_host MIDI IN endpoint channel connected to the XUD
* \param c_midi Channel connected to MIDI core
* \param c_int Audio clocking interrupt endpoint channel connected to the XUD
* \param c_clk_int Optional chanend connected to the clockGen() thread if present
* \param c_sof Start of frame channel connected to the XUD
* \param c_aud_ctl Audio control channel connected to Endpoint0()
* \param p_off_mclk A port that is clocked of the MCLK input (not the MCLK input itself)
* \param c_aud Channel connected to XUA_AudioHub() core
* \param i_pll_ref Interface to task that toggles reference pin to CS2100
*/
void XUA_Buffer(
chanend c_aud_out,
#if (NUM_USB_CHAN_IN > 0)
#if (NUM_USB_CHAN_IN > 0) || defined(__DOXYGEN__)
chanend c_aud_in,
#endif
#if (NUM_USB_CHAN_IN == 0) || defined (UAC_FORCE_FEEDBACK_EP)
#if (NUM_USB_CHAN_IN == 0) || defined (UAC_FORCE_FEEDBACK_EP)
chanend c_aud_fb,
#endif
#ifdef MIDI
#if defined(MIDI) || defined(__DOXYGEN__)
chanend c_midi_from_host,
chanend c_midi_to_host,
chanend c_midi,
#endif
#if (XUA_SPDIF_RX_EN) || (XUA_ADAT_RX_EN)
#if XUA_SPDIF_RX_EN || XUA_ADAT_RX_EN || defined(__DOXYGEN__)
chanend ?c_int,
chanend ?c_clk_int,
#endif
chanend c_sof,
chanend c_aud_ctl,
in port p_off_mclk
#if (HID_CONTROLS )
#if (HID_CONTROLS)
, chanend c_hid
#endif
, chanend c_aud
#if (XUA_SYNCMODE == XUA_SYNCMODE_SYNC)
#if (XUA_SYNCMODE == XUA_SYNCMODE_SYNC) || defined(__DOXYGEN__)
, client interface pll_ref_if i_pll_ref
#endif
);
void XUA_Buffer_Ep(chanend c_aud_out,
#if (NUM_USB_CHAN_IN > 0)
#if (NUM_USB_CHAN_IN > 0) || defined(__DOXYGEN__)
chanend c_aud_in,
#endif
#if (NUM_USB_CHAN_IN == 0) || defined (UAC_FORCE_FEEDBACK_EP)
@@ -80,7 +81,7 @@ void XUA_Buffer_Ep(chanend c_aud_out,
#ifdef CHAN_BUFF_CTRL
, chanend c_buff_ctrl
#endif
#if (XUA_SYNCMODE == XUA_SYNCMODE_SYNC)
#if (XUA_SYNCMODE == XUA_SYNCMODE_SYNC) || defined(__DOXYGEN__)
, client interface pll_ref_if i_pll_ref
#endif
);

2
lib_xua/src/core/clocking/clocking.h → lib_xua/api/xua_clocking.h
View File

@@ -4,6 +4,8 @@
#ifndef _CLOCKING_H_
#define _CLOCKING_H_
#include <xs1.h>
interface pll_ref_if
{
void toggle();

77
lib_xua/api/xua_conf_default.h
View File

@@ -17,21 +17,14 @@
* @brief Location (tile) of audio I/O. Default: 0
*/
#ifndef AUDIO_IO_TILE
#define AUDIO_IO_TILE 0
#define AUDIO_IO_TILE (0)
#endif
/**
* @brief Location (tile) of audio I/O. Default: 0
*/
#ifndef XUD_TILE
#define XUD_TILE 0
#endif
/**
* @brief Location (tile) of IAP. Default: AUDIO_IO_TILE
*/
#ifndef IAP_TILE
#define IAP_TILE AUDIO_IO_TILE
#define XUD_TILE (0)
#endif
/**
@@ -66,7 +59,7 @@
* @brief Disable USB functionalty just leaving AudioHub
*/
#ifndef XUA_USB_EN
#define XUA_USB_EN 1
#define XUA_USB_EN (1)
#endif
/**
@@ -438,7 +431,8 @@
#define HID_CONTROLS (0)
#endif
/* @brief Defines whether XMOS device runs as master (i.e. drives LR and Bit clocks)
/**
* @brief Defines whether XMOS device runs as master (i.e. drives LR and Bit clocks)
*
* 0: XMOS is I2S master. 1: CODEC is I2s master.
*
@@ -457,7 +451,6 @@
#define SERIAL_STR ""
#endif
/**
* @brief Vendor String used by the device. This is also pre-pended to various strings used by the design.
*
@@ -1154,6 +1147,26 @@
#undef UAC_FORCE_FEEDBACK_EP
#endif
/* Synchronisation defines */
#define XUA_SYNCMODE_ASYNC (1) // USB_ENDPOINT_SYNCTYPE_ASYNC
#define XUA_SYNCMODE_ADAPT (2) // USB_ENDPOINT_SYNCTYPE_ADAPT
#define XUA_SYNCMODE_SYNC (3) // USB_ENDPOINT_SYNCTYPE_SYNC
#ifndef XUA_SYNCMODE
#define XUA_SYNCMODE XUA_SYNCMODE_ASYNC
#endif
#if (XUA_SYNCMODE == XUA_SYNCMODE_SYNC)
#if (XUA_SPDIF_RX_EN|| ADAT_RX)
#error "Digital input streams not supported in Sync mode"
#endif
#endif
/*********************************************************/
/*** Internal defines below here. NOT FOR MODIFICATION ***/
/*********************************************************/
#ifndef __ASSEMBLER__
/* Endpoint addresses enums */
enum USBEndpointNumber_In
@@ -1200,40 +1213,37 @@ enum USBEndpointNumber_Out
XUA_ENDPOINT_COUNT_OUT /* End marker */
};
#ifndef XUA_ENDPOINT_COUNT_CUSTOM_OUT
#define XUA_ENDPOINT_COUNT_CUSTOM_OUT 0
#define XUA_ENDPOINT_COUNT_CUSTOM_OUT (0)
#endif
#ifndef XUA_ENDPOINT_COUNT_CUSTOM_IN
#define XUA_ENDPOINT_COUNT_CUSTOM_IN 0
#define XUA_ENDPOINT_COUNT_CUSTOM_IN (0)
#endif
#define ENDPOINT_COUNT_IN (XUA_ENDPOINT_COUNT_IN + XUA_ENDPOINT_COUNT_CUSTOM_IN)
#define ENDPOINT_COUNT_OUT (XUA_ENDPOINT_COUNT_OUT + XUA_ENDPOINT_COUNT_CUSTOM_OUT)
#define ENDPOINT_COUNT_IN (XUA_ENDPOINT_COUNT_IN + XUA_ENDPOINT_COUNT_CUSTOM_IN)
#define ENDPOINT_COUNT_OUT (XUA_ENDPOINT_COUNT_OUT + XUA_ENDPOINT_COUNT_CUSTOM_OUT)
#endif
#endif /* __ASSEMBLER__ */
/*** Internal defines below here. NOT FOR MODIFICATION ***/
#define AUDIO_STOP_FOR_DFU (0x12345678)
#define AUDIO_START_FROM_DFU (0x87654321)
#define AUDIO_REBOOT_FROM_DFU (0xa5a5a5a5)
#define AUDIO_STOP_FOR_DFU (0x12345678)
#define AUDIO_START_FROM_DFU (0x87654321)
#define AUDIO_REBOOT_FROM_DFU (0xa5a5a5a5)
#define MAX_VOL (0x20000000)
#define MAX_VOL (0x20000000)
#if defined(LEVEL_METER_LEDS) && !defined(LEVEL_UPDATE_RATE)
#define LEVEL_UPDATE_RATE 400000
#define LEVEL_UPDATE_RATE (400000)
#endif
/* The number of clock ticks to wait for the audio feeback to stabalise
* Note, feedback always counts 128 SOFs (16ms @ HS, 128ms @ FS) */
#ifndef FEEDBACK_STABILITY_DELAY_HS
#define FEEDBACK_STABILITY_DELAY_HS (2000000)
#define FEEDBACK_STABILITY_DELAY_HS (2000000)
#endif
#ifndef FEEDBACK_STABILITY_DELAY_FS
#define FEEDBACK_STABILITY_DELAY_FS (20000000)
#define FEEDBACK_STABILITY_DELAY_FS (20000000)
#endif
/* Length of clock unit/clock-selector units */
@@ -1458,16 +1468,3 @@ enum USBEndpointNumber_Out
#error CODEC_MASTER with DSD is currently unsupported
#endif
#define XUA_SYNCMODE_ASYNC (1) // USB_ENDPOINT_SYNCTYPE_ASYNC
#define XUA_SYNCMODE_ADAPT (2) // USB_ENDPOINT_SYNCTYPE_ADAPT
#define XUA_SYNCMODE_SYNC (3) // USB_ENDPOINT_SYNCTYPE_SYNC
#ifndef XUA_SYNCMODE
#define XUA_SYNCMODE XUA_SYNCMODE_ASYNC
#endif
#if (XUA_SYNCMODE == XUA_SYNCMODE_SYNC)
#if (XUA_SPDIF_RX_EN || XUA_ADAT_RX_EN)
#error "Digital input streams not supported in Sync mode"
#endif
#endif

43
lib_xua/api/xua_endpoint0.h
View File

@@ -1,36 +1,41 @@
// Copyright 2011-2021 XMOS LIMITED.
// Copyright 2011-2022 XMOS LIMITED.
// This Software is subject to the terms of the XMOS Public Licence: Version 1.
#ifndef _XUA_ENDPOINT0_H_
#define _XUA_ENDPOINT0_H_
#include "xua.h"
#include "dfu_interface.h"
#include "vendorrequests.h"
#if __XC__
/** Function implementing Endpoint 0 for enumeration, control and configuration
* of USB audio devices. It uses the descriptors defined in ``descriptors_2.h``.
*
* \param c_ep0_out Chanend connected to the XUD_Manager() out endpoint array
* \param c_ep0_in Chanend connected to the XUD_Manager() in endpoint array
* \param c_audioCtrl 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
* \param c_mix_ctl Optional chanend to be connected to the mixer thread if
* present
* \param c_clk_ctl Optional chanend to be connected to the clockgen thread if
* present.
* \param c_usb_test Optional chanend to be connected to XUD if test modes required.
* of USB audio devices. It uses the descriptors defined in ``xua_ep0_descriptors.h``.
*
* \param c_ep0_out Chanend connected to the XUD_Manager() out endpoint array
* \param c_ep0_in Chanend connected to the XUD_Manager() in endpoint array
* \param c_audioCtrl 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
* \param c_mix_ctl Optional chanend to be connected to the mixer core(s) if
* present
* \param c_clk_ctl Optional chanend to be connected to the clockgen core if
* present
* \param dfuInterface Interface to DFU task (this task must be run on a tile
* connected to boot flash.
* \param c_EANativeTransport_ctrl Optional chanend to be connected to EA Native
* endpoint manager if present
*/
void XUA_Endpoint0(chanend c_ep0_out, chanend c_ep0_in, chanend ?c_audioCtrl,
chanend ?c_mix_ctl,chanend ?c_clk_ctl, chanend ?c_EANativeTransport_ctr, client interface i_dfu ?dfuInterface
VENDOR_REQUESTS_PARAMS_DEC_);
void XUA_Endpoint0(chanend c_ep0_out,
chanend c_ep0_in, chanend ?c_audioCtrl,
chanend ?c_mix_ctl, chanend ?c_clk_ctl,
chanend ?c_EANativeTransport_ctrl,
client interface i_dfu ?dfuInterface
#if !defined(__DOXYGEN__)
VENDOR_REQUESTS_PARAMS_DEC_
#endif
);
/** Function to set the Vendor ID value
*

38
lib_xua/src/midi/usb_midi.h → lib_xua/api/xua_midi.h
View File

@@ -1,34 +1,40 @@
// Copyright 2011-2021 XMOS LIMITED.
// Copyright 2011-2022 XMOS LIMITED.
// This Software is subject to the terms of the XMOS Public Licence: Version 1.
#ifndef __usb_midi_h__
#define __usb_midi_h__
#ifndef _XUA_MIDI_H_
#define _XUA_MIDI_H_
#include "xua.h"
/** USB MIDI I/O thread.
#ifndef MIDI_SHIFT_TX
#define MIDI_SHIFT_TX (0)
#endif
/** USB MIDI I/O task.
*
* This function passes MIDI data from USB to UART I/O.
* This function passes MIDI data between XUA_Buffer and MIDI UART I/O.
*
* \param p_midi_in 1-bit input port for MIDI
* \param p_midi_out 1-bit output port for MIDI
* \param clk_midi clock block used for clockin the UART; should have
* a rate of 100MHz
* \param c_midi chanend connected to the decouple() thread
* \param cable_number the cable number of the MIDI implementation.
* \param p_midi_in 1-bit input port for MIDI
* \param p_midi_out 1-bit output port for MIDI
* \param clk_midi Clock block used for clockin the UART; should have
* a rate of 100MHz
* \param c_midi Chanend connected to the decouple() thread
* \param cable_number The cable number of the MIDI implementation.
* This should be set to 0.
**/
void usb_midi(
#if (MIDI_RX_PORT_WIDTH == 4)
buffered in port:4 ?p_midi_in,
buffered in port:4 ?p_midi_in,
#else
buffered in port:1 ?p_midi_in,
buffered in port:1 ?p_midi_in,
#endif
port ?p_midi_out,
clock ?clk_midi,
chanend ?c_midi,
unsigned cable_number,
chanend ?c_iap, chanend ?c_i2c, // iOS stuff
unsigned cable_number
#ifdef IAP
, chanend ?c_iap, chanend ?c_i2c, // iOS stuff
port ?p_scl, port ?p_sda
#endif
);
#define MAX_USB_MIDI_PACKET_SIZE 1024
@@ -72,4 +78,4 @@ INLINE void midi_send_ack(chanend c) {
#define MIDI_RATE (31250)
#define MIDI_BITTIME (XS1_TIMER_MHZ * 1000000 / MIDI_RATE)
#define MIDI_BITTIME_2 (MIDI_BITTIME>>1)
#endif // __usb_midi_h__
#endif // _XUA_MIDI_H_

6
lib_xua/src/core/mixer/mixer.h → lib_xua/api/xua_mixer.h
View File

@@ -1,7 +1,7 @@
// Copyright 2011-2021 XMOS LIMITED.
// Copyright 2011-2022 XMOS LIMITED.
// This Software is subject to the terms of the XMOS Public Licence: Version 1.
#ifndef __mixer_h__
#define __mixer_h__
#ifndef _XUA_MIXER_H_
#define _XUA_MIXER_H_
enum mix_ctl_cmd {
SET_SAMPLES_TO_HOST_MAP,

27
lib_xua/doc/rst/add.rst Normal file
View File

@@ -0,0 +1,27 @@
Additional Features
-------------------
The previous sections describes only the basic core set of ``lib_xua`` details on enabling additional features e.g. S/PDIF are discussed in this section.
Where something must be defined, it is recommended this is done in `xua_conf.h` but could also be done in the application Makefile.
For each feature steps are listed for if calling ``lib_xua`` functions manually - if using the "codeless" programming model then these steps are informational only.
Each section also includes a sub-section on enabling the feature using the "codeless" model.
For full details of all options please see the API section
.. toctree::
S/PDIF Transmit <feat_spdif_tx>

13
lib_xua/doc/rst/api.rst Normal file
View File

@@ -0,0 +1,13 @@
.. _sec_api:
API Reference
-------------
.. toctree::
api_defines
api_user_functions
api_component

35
lib_xua/doc/rst/api_component.rst Normal file
View File

@@ -0,0 +1,35 @@
.. _sec_api_component:
Component API
-------------
The following functions can be called from the top level main of an
application and implement the various components described in
:ref:`usb_audio_sec_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)
.. doxygenfunction:: XUA_Endpoint0
.. doxygenfunction:: XUA_Buffer
.. doxygenfunction:: XUA_AudioHub
.. doxygenfunction:: mixer
.. doxygenfunction:: clockGen
.. doxygenfunction:: usb_midi

170
lib_xua/doc/rst/api_defines.rst Normal file
View File

@@ -0,0 +1,170 @@
.. _sec_api_defines:
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 over-ridden in an optional header file ``xua_conf.h`` file or in the ``Makefile``
for a relevant build configuration.
This section fully documents all of the settable defines and their default values (where appropriate).
Code Location (tile)
~~~~~~~~~~~~~~~~~~~~
.. doxygendefine:: AUDIO_IO_TILE
.. doxygendefine:: XUD_TILE
.. doxygendefine:: MIDI_TILE
.. doxygendefine:: SPDIF_TX_TILE
.. doxygendefine:: PDM_TILE
.. doxygendefine:: PLL_REF_TILE
Channel Counts
~~~~~~~~~~~~~~
.. doxygendefine:: NUM_USB_CHAN_OUT
.. doxygendefine:: NUM_USB_CHAN_IN
.. doxygendefine:: I2S_CHANS_DAC
.. doxygendefine:: I2S_CHANS_ADC
Frequencies and Clocks
~~~~~~~~~~~~~~~~~~~~~~
.. doxygendefine:: MAX_FREQ
.. doxygendefine:: MIN_FREQ
.. doxygendefine:: DEFAULT_FREQ
.. doxygendefine:: MCLK_441
.. doxygendefine:: MCLK_48
Audio Class
~~~~~~~~~~~
.. doxygendefine:: AUDIO_CLASS
.. doxygendefine:: AUDIO_CLASS_FALLBACK
.. doxygendefine:: FULL_SPEED_AUDIO_2
System Feature Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MIDI
....
.. doxygendefine:: MIDI
.. doxygendefine:: MIDI_RX_PORT_WIDTH
S/PDIF
......
.. doxygendefine:: XUA_SPDIF_TX_EN
.. doxygendefine:: SPDIF_TX_INDEX
.. doxygendefine:: XUA_SPDIF_RX_EN
.. doxygendefine:: SPDIF_RX_INDEX
ADAT
....
.. doxygendefine:: XUA_ADAT_RX_EN
.. doxygendefine:: ADAT_RX_INDEX
PDM Microphones
...............
.. doxygendefine:: XUA_NUM_PDM_MICS
DFU
...
.. doxygendefine:: XUA_DFU_EN
.. .. doxygendefine:: DFU_FLASH_DEVICE
HID
...
.. doxygendefine:: HID_CONTROLS
CODEC Interface
...............
.. doxygendefine:: CODEC_MASTER
USB Device Configuration
~~~~~~~~~~~~~~~~~~~~~~~~
.. doxygendefine:: VENDOR_STR
.. doxygendefine:: VENDOR_ID
.. doxygendefine:: PRODUCT_STR
.. doxygendefine:: PRODUCT_STR_A2
.. doxygendefine:: PRODUCT_STR_A1
.. doxygendefine:: PID_AUDIO_1
.. doxygendefine:: PID_AUDIO_2
.. doxygendefine:: BCD_DEVICE
Stream Formats
~~~~~~~~~~~~~~
Output/Playback
...............
.. doxygendefine:: OUTPUT_FORMAT_COUNT
.. doxygendefine:: STREAM_FORMAT_OUTPUT_1_RESOLUTION_BITS
.. doxygendefine:: STREAM_FORMAT_OUTPUT_2_RESOLUTION_BITS
.. doxygendefine:: STREAM_FORMAT_OUTPUT_3_RESOLUTION_BITS
.. doxygendefine:: HS_STREAM_FORMAT_OUTPUT_1_SUBSLOT_BYTES
.. doxygendefine:: HS_STREAM_FORMAT_OUTPUT_2_SUBSLOT_BYTES
.. doxygendefine:: HS_STREAM_FORMAT_OUTPUT_3_SUBSLOT_BYTES
.. doxygendefine:: FS_STREAM_FORMAT_OUTPUT_1_SUBSLOT_BYTES
.. doxygendefine:: FS_STREAM_FORMAT_OUTPUT_2_SUBSLOT_BYTES
.. doxygendefine:: FS_STREAM_FORMAT_OUTPUT_3_SUBSLOT_BYTES
.. doxygendefine:: STREAM_FORMAT_OUTPUT_1_DATAFORMAT
.. doxygendefine:: STREAM_FORMAT_OUTPUT_2_DATAFORMAT
.. doxygendefine:: STREAM_FORMAT_OUTPUT_3_DATAFORMAT
Input/Recording
...............
.. doxygendefine:: INPUT_FORMAT_COUNT
.. doxygendefine:: STREAM_FORMAT_INPUT_1_RESOLUTION_BITS
.. doxygendefine:: HS_STREAM_FORMAT_INPUT_1_SUBSLOT_BYTES
.. doxygendefine:: FS_STREAM_FORMAT_INPUT_1_SUBSLOT_BYTES
.. doxygendefine:: STREAM_FORMAT_INPUT_1_DATAFORMAT
Volume Control
~~~~~~~~~~~~~~
.. doxygendefine:: OUTPUT_VOLUME_CONTROL
.. doxygendefine:: INPUT_VOLUME_CONTROL
.. doxygendefine:: MIN_VOLUME
.. doxygendefine:: MAX_VOLUME
.. doxygendefine:: VOLUME_RES
Mixing Parameters
~~~~~~~~~~~~~~~~~
.. doxygendefine:: MIXER
.. doxygendefine:: MAX_MIX_COUNT
.. doxygendefine:: MIX_INPUTS
.. doxygendefine:: MIN_MIXER_VOLUME
.. doxygendefine:: MAX_MIXER_VOLUME
.. doxygendefine:: VOLUME_RES_MIXER
Power
~~~~~
.. doxygendefine:: SELF_POWERED
.. doxygendefine:: BMAX_POWER

73
lib_xua/doc/rst/api_user_functions.rst Normal file
View File

@@ -0,0 +1,73 @@
Required User Function Definitions
----------------------------------
The following functions need to be defined by an application using the XMOS USB Audio framework.
External Audio Hardware Configuration Functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. c:function:: void AudioHwInit(chanend ?c_codec)
This function is called when the audio core starts after the
device boots up and should initialize the external audio harware e.g. clocking, DAC, ADC etc
:param c_codec: An optional chanend that was original passed into
:c:func:`audio` that can be used to communicate
with other cores.
.. c:function:: void AudioHwConfig(unsigned samFreq, unsigned mclk, chanend ?c_codec, unsigned dsdMode, unsigned sampRes_DAC, unsigned sampRes_ADC)
This function is called when the audio core starts or changes
sample rate. It should configure the extenal audio hardware to run at the specified
sample rate given the supplied master clock frequency.
:param samFreq: The sample frequency in Hz that the hardware should be configured to (in Hz).
:param mclk: The master clock frequency that is required in Hz.
:param c_codec: An optional chanend that was original passed into
:c:func:`audio` that can be used to communicate
with other cores.
:param dsdMode: Signifies if the audio hardware should be configured for DSD operation
:param sampRes_DAC: The sample resolution of the DAC stream
:param sampRes_ADC: The sample resolution of the ADC stream
Audio Streaming Functions
~~~~~~~~~~~~~~~~~~~~~~~~~
The following functions can be optionally used by the design. They can be useful for mute lines etc.
.. c:function:: void AudioStreamStart(void)
This function is called when the audio stream from device to host
starts.
.. c:function:: void AudioStreamStop(void)
This function is called when the audio stream from device to host stops.
Host Active
~~~~~~~~~~~
The following function can be used to signal that the device is connected to a valid host.
This is called on a change in state.
.. c:function:: void AudioStreamStart(int active)
:param active: Indicates if the host is active or not. 1 for active else 0.
HID Controls
~~~~~~~~~~~~
The following function is called when the device wishes to read physical user input (buttons etc).
.. c:function:: void UserReadHIDButtons(unsigned char hidData[])
:param hidData: The function should write relevant HID bits into this array. The bit ordering and functionality is defined by the HID report descriptor used.

92
lib_xua/doc/rst/arch.rst Normal file
View File

@@ -0,0 +1,92 @@
.. _usb_audio_sec_architecture:
Software Architecture
---------------------
This section describes the required software architecture of a USB Audio device implemented using `lib_xua`, its dependencies and other supporting libraries.
`lib_xua` provides fundamental building blocks for producing USB Audio products on XMOS devices. Every system is required to have the components from `lib_xua` listed in :ref:`usb_audio_shared_components`.
.. tabularcolumns:: lp{5cm}l
.. _usb_audio_shared_components:
.. list-table:: Required XUA Components
:header-rows: 1
:widths: 40 60
* - Component
- Description
* - Endpoint 0
- Provides the logic for Endpoint 0 which handles
enumeration and control of the device including DFU related requests.
* - Endpoint buffer
- Buffers endpoint data packets to and from the host. Manages delivery of audio packets between the endpoint buffer
component and the audio components. It can also handle volume control processing. Note, this currently utilises two cores
* - AudioHub
- Handles audio I/O over I2S and manages audio data
to/from other digital audio I/O components.
In addition low-level USB I/0 is required and is provided by the external dependency `lib_xud`
.. tabularcolumns:: lp{5cm}l
.. list-table:: Additional Components Required
:header-rows: 1
:widths: 100 60
* - Component
- Description
* - XMOS USB Device Driver (XUD)
- Handles the low level USB I/O.
In addition :ref:`usb_audio_optional_components` shows optional components that can be added/enabled from within `lib_xua`
.. tabularcolumns:: lp{5cm}l
.. _usb_audio_optional_components:
.. list-table:: Optional Components
:header-rows: 1
:widths: 40 60
* - Component
- Description
* - Mixer
- Allows digital mixing of input and output channels. It can also
handle volume control instead of the decoupler.
* - Clockgen
- Drives an external frequency generator (PLL) and manages
changes between internal clocks and external clocks arising
from digital input.
* - MIDI
- Outputs and inputs MIDI over a serial UART interface.
`lib_xua` also provides optional support for integrating with the following external dependencies listed in :ref:`usb_audio_external_components`
.. tabularcolumns:: lp{5cm}l
.. _usb_audio_external_components:
.. list-table:: External Components
:header-rows: 1
:widths: 40 60
* - Component
- Description
* - S/PDIF Transmitter (lib_spdif)
- Outputs samples of an S/PDIF digital audio interface.
* - S/PDIF Receiver (lib_spdif)
- Inputs samples of an S/PDIF digital audio interface (requires the
clockgen component).
* - ADAT Receiver (lib_adat)
- Inputs samples of an ADAT digital audio interface (requires the
clockgen component).
* - PDM Microphones (lib_mic_array)
- Receives PDM data from microphones and performs PDM to PCM conversion
.. _usb_audio_threads:
.. figure:: images/threads-crop.*
:width: 100%
USB Audio Core Diagram
:ref:`usb_audio_threads` shows how the components interact with each
other in a typical system. The green circles represent cores with arrows indicating inter-core communications.

121
lib_xua/doc/rst/feat.rst
View File

@@ -2,116 +2,23 @@
Features & Options
------------------
The previous sections describes only the basic core set of ``lib_xua`` details on enabling additional features e.g. S/PDIF are discussed in this section.
The previous section describes the use of core functionality contained within ``lib_xua``
This seciton details enabling additional features with supported external dependencies, for example,
``lib_xua`` can provide S/PDIF output though the used of ``lib_spdif``
Where something must be defined, it is recommended this is done in `xua_conf.h` but could also be done in the application Makefile.
.. toctree::
S/PDIF Transmit <feat_spdif_tx>
S/PDIF Receive <feat_spdif_rx>
Where something must be defined, it is recommened this is done in `xua_conf.h` but could also be done in the application Makefile.
For each feature steps are listed for if calling ``lib_xua`` functions manually - if using the "codeless" programming model then these steps informational only.
Each section also includes a sub-section on enabling the feature using the "codeless" model.
For full details of all options please see the API section
I2S/TDM
~~~~~~~
I2S/TDM is typically fundamental to most products and is built into the ``XUA_AudioHub()`` core.
In order to enable I2S on 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 */
.. note::
All of these ports must be buffered, width 32. Based on whether the xCORE is bus slave/master the ports must be declared as input/output respectively
These ports must then be passed to the ``XUA_AudioHub()`` task appropriately.
I2S functionality also requires two clock-blocks, one for bit and sample 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 core 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);
Codeless Programming Model
..........................
All ports and hardware resources are already fully declared, one must simply set the following:
* `I2S_CHANS_DAC` must be set to the desired number of output channels via I2S
* `I2S_CHANS_ADC` must be set to the desired number of input channels via I2S
* `AUDIO_IO_TILE` must be set to the tile where the physical I2S connections reside
For configuration options, master vs slave, TDM etc please see the API section.
|newpage|
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 in a single core and supports rates up to 192kHz.
The S/PDIF transmitter core 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 a normal::
chan c_spdif_tx
In order to use the S/PDIF transmmiter with ``lib_xua`` hardware resources 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_tx2, clk_audio_mclk, p_mclk_in, delay);
.. note:: If sharing the master-clock port and clockblock with ``XUA_AudioHub()`` (or any other task) then this setup
should be done before running the tasks in a ``par`` statement.
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_tx2, c_spdif_tx);
}
/* AudioHub/IO core 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``.
Codeless Programming Model
..........................
If using the codeless programming method one must simply ensure the following:
* `PORT_SPDIF_OUT` is correctly defined in the XN file
* `XUA_SPDIF_TX_EN` should be defined as non-zero
* `SPDIF_TX_TILE` is correctly defined (note, this defaults to `AUDIO_IO_TILE`)
For further configuration options please see the API section.

52
lib_xua/doc/rst/feat_spdif_rx.rst Normal file
View File

@@ -0,0 +1,52 @@
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 in a single core and supports rates up to 192kHz.
The S/PDIF receiver inputs data via a port and outputs samples via a channel. It requires a 1-bit port
which must be 4-bit buffered. For example::
buffered in port:4 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::
SpdifReceive(p_spdif_rx, c_spdif_rx, 1, clk_spd_rx);
.. note::
It is recomended to use the value 1 for the ``initial_divider`` parameter
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.
The ``ClockGen()`` task from ``lib_xua`` provides the reference signal to the CS2100 device and also handles
recording of clock validity etc. See :ref:`usb_audio_sec_clock_recovery` for full details regarding ``ClockGen()``.
It also provides a small FIFO for S/PDIF samples before they are forwarded to the ``AudioHub`` core.
As such it requires to be inserted in the communication path between the S/PDIF receiver and the
``AudioHub`` core. 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, ...);
}

47
lib_xua/doc/rst/feat_spdif_tx.rst Normal file
View File

@@ -0,0 +1,47 @@
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 in a single core and supports rates up to 192kHz.
The S/PDIF transmitter core 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);
.. note:: If sharing the master-clock port and clockblock with ``XUA_AudioHub()`` (or any other task) then this setup
should be done before running the tasks in a ``par`` statement.
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 core 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``.

101
lib_xua/doc/rst/hw.rst
View File

@@ -4,59 +4,118 @@ XMOS USB Audio Hardware Platforms
A range of hardware platforms for evaluating USB Audio on XMOS devices.
Specific, in depth, details for each platform/board are out of scope of this library documentation however, the features of the most popular platform are described below with the view of providing a worked example.
Specific details for each platform/board are out of scope of this library documentation however, the features of the most popular platform are described below with the view of providing a worked example.
Please also see application note AN00246.
xCORE-200 Multi-Channel Audio Board
xCORE.AI Multichannel Audio Board
...................................
`The XMOS xCORE-200 Multi-channel Audio board <https://www.xmos.com/support/boards?product=18334>`_
(XK-AUDIO-216-MC) is a complete hardware and reference software platform targeted at up to 32-channel USB and networked audio applications, such as DJ decks and mixers.
The XMOS xCORE.ai Multichannel Audio board (XK-AUDIO-316-MC) is a complete hardware and reference software platform targeted at up to 32-channel USB audio applications, such as DJ decks and mixers and other musical instrument interfaces. The board can also be used to prototype products with smaller feature sets or HiFi style products.
The Multichannel Audio Platform hardware is based around the XE216-512-TQ128 multicore microcontroller; an dual-tile xCORE-200 device with an integrated High Speed USB 2.0 PHY, RGMII (Gigabit Ethernet) interface and 16 logical cores delivering up to 2000MIPS of deterministic and responsive processing power.
The Multichannel Audio Platform hardware is based around the XU316-1024-TQ128-C24 multicore microcontroller; an dual-tile xCORE.ai device with an integrated High Speed USB 2.0 PHY and 16 logical cores delivering up to 3200MIPS of deterministic and responsive processing power.
Exploiting the flexible programmability of the xCORE-200 architecture, the Multi-channel Audio Platform supports either USB or network audio source, streaming 8 analogue input and 8 analogue output audio channels simultaneously - at up to 192kHz.
Exploiting the flexible programmability of the xCORE.ai architecture, the Multi-channel Audio Platform supports either USB or network audio source, streaming 8 analogue input and 8 analogue output audio channels simultaneously - at up to 192kHz.
For full details regarding the hardware please refer to `xCORE-200 Multichannel Audio Platform Hardware Manual <https://www.xmos.com/support/boards?product=18334&component=18687>`_.
The reference board has an associated firmware application that uses `lib_xua` to implemented a USB Audio Devicce. Full details of this application can be found in the USB Audio Design Guide.
The reference board has an associated firmware application that uses `lib_xua` to implemented a USB Audio Device. Full details of this application can be found later in this document.
Analogue Input & Output
+++++++++++++++++++++++
A total of eight single-ended analog input channels are provided via 3.5mm stereo jacks. Each is fed into a CirrusLogic CS5368 ADC.
Similarly a total of eight single-ended analog output channels are provided. Each is fed into a CirrusLogic CS4384 DAC.
A total of eight single-ended analog input channels are provided via 3.5mm stereo jacks. These inputs feed into a pair of quad-channel PCM1865 ADCs from Texas Instruments.
The four digital I2S/TDM input and output channels are mapped to the xCORE input/outputs through a header array. This jumper allows channel selection when the ADC/DAC is used in TDM mode
A total of eight single-ended analog output channels are provided. These a fed from a for PCM5122 stereo DAC's from Texas instruments.
ADC's and DAC's are configured via an I2C bus.
The four digital I2S/TDM input and output channels are mapped to the xCORE input/outputs through a header array. These jumpers allow channel selection when the ADC/DAC is used in TDM mode
Digital Input & Output
++++++++++++++++++++++
Optical and coaxial digital audio transmitters are used to provide digital audio input output in formats such as IEC60958 consumer mode (S/PDIF) and ADAT.
The output data streams from the xCORE-200 are re-clocked using the external master clock to synchronise the data into the audio clock domain. This is achieved using simple external D-type flip-flops.
The output data streams from the xCORE are re-clocked using the external master clock to synchronise the data into the audio clock domain. This is achieved using simple external D-type flip-flops.
MIDI
++++
MIDI I/O is provided on the board via standard 5-pin DIN connectors. The signals are buffered using 5V line drivers and are then connected to 1-bit ports on the xCORE-200, via a 5V to 3.3V buffer.
MIDI I/O is provided on the board via standard 5-pin DIN connectors. The signals are buffered using 5V line drivers and are then connected to 1-bit ports on the xCORE, via a 5V to 3.3V buffer.
Audio Clocking
++++++++++++++
A flexible clocking scheme is provided for both audio and other system services. In order to accommodate a multitude of clocking options, the low-jitter master clock is generated locally using a frequency multiplier PLL chip. The chip used is a Phaselink PL611-01, which is pre-programmed to provide a 24MHz clock from its CLK0 output, and either 24.576 MHz or 22.5792MHz from its CLK1 output.
In order to accommodate a multitude of clocking options a flexible clocking scheme is provided for the audio subsystem.
The 24MHz fixed output is provided to the xCORE-200 device as the main processor clock. It also provides the reference clock to a Cirrus Logic CS2100, which provides a very low jitter audio clock from a synchronisation signal provided from the xCORE-200.
Three methods of generating an audio master clock are provided on the board:
* A Cirrus Logic CS2100-CP PLL device. The CS2100 features both a clock generator and clock multiplier/jitter reduced clock frequency synthesizer (clean up) and can generate a low jitter audio clock based on a synchronisation signal provided by the xCORE
* A Skyworks Si5351B PLL device. The Si5351 is an I2C configurable clock generator that is ideally suited for replacing crystals, crystal oscillators, VCXOs, phase-locked loops (PLLs), and fanout buffers.
* xCORE.ai devices are equipped with a secondary (or 'application') PLL which can be used to generate audio clocks
Selection between these methods is done via writing to bits 6 and 7 of PORT 8D on tile[0].
Either the locally generated clock (from the PL611) or the recovered low jitter clock (from the CS2100) may be selected to clock the audio stages; the xCORE-200, the ADC/DAC and Digital output stages. Selection is controlled via an additional I/O, bit 5 of PORT 8C, see :ref:`hw_316_ctrlport`.
.. _hw_316_ctrlport:
Control I/O
+++++++++++
4 bits of PORT 8C are used to control external hardware on the board. This is described in :ref:`table_316_ctrlport`.
.. _table_316_ctrlport:
.. table:: PORT 8C functionality
:class: horizontal-borders vertical_borders
+--------+-----------------------------------------+------------+------------+
| Bit(s) | Functionality | 0 | 1 |
+========+=========================================+============+============+
| [0:3] | Unused | | |
+--------+-----------------------------------------+------------+------------+
| 4 | Enable 3v3 power for digital (inverted) | Enabled | Disabled |
+--------+-----------------------------------------+------------+------------+
| 5 | Enable 3v3 power for analogue | Disabled | Enabled |
+--------+-----------------------------------------+------------+------------+
| 6 | PLL Select | CS2100 | Si5351B |
+--------+-----------------------------------------+------------+------------+
| 7 | Master clock direction | Output | Input |
+--------+-----------------------------------------+------------+------------+
.. note::
To use the xCORE application PLL bit 7 should be set to 0. To use one of the external PLL's bit 7 should be set to 1.
Either the locally generated clock (from the PL611) or the recovered low jitter clock (from the CS2100) may be selected to clock the audio stages; the xCORE-200, the ADC/DAC and Digital output stages. Selection is conntrolled via an additional I/O, bit 5 of PORT 8C.
LEDs, Buttons and Other IO
++++++++++++++++++++++++++
An array of 4*4 green LEDs, 3 buttons and a switch are provided for general purpose user interfacing. The LED array is driven by eight signals each controlling one of 4 rows and 4 columns.
All programmable I/O on the board is configured for 3v3.
A standard XMOS xSYS interface is provided to allow host debug of the board via JTAG.
For green LED's and three push buttons are provided for general purpose user interfacing.
|newpage|
The LEDs are connected to PORT 4F and the buttons are connected to bits [0:2] of PORT 4E. Bit 3 of this port is connected to the (currently
unused) ADC interrupt line.
The board also includes support for an AES11 format Word Clock input via 75 ohm BNC. The software does not support this currently and it is
provided for future expansion.
All spare IO and Functional IO brought out on headers for easy connection of expansion boards (via 0.1” headers).
Power
+++++
The board is capable of acting as a USB2.0 self or bus powered device. If bus powered, board takes power from ``USB DEVICE`` connector (micro-B receptacle).
If self powered, board takes power from ``EXTERNAL POWER`` input (micro-B receptacle).
A Power Source Select (marked ``PWR SRC``) is used to select between bus and self-powered configuration.
Debug
+++++
For convenience the board includes an on-board xTAG4 for debugging via JTAG/xSCOPE. This is accessed via the USB (micro-B) receptacle marked ``DEBUG``.

26
lib_xua/doc/rst/issues.rst
View File

@@ -1,3 +1,4 @@
|appendix|
Known Issues
@@ -5,16 +6,29 @@ Known Issues
- Quad-SPI DFU will corrupt the factory image with tools version < 14.0.4 due to an issue with libquadflash
- (#14762) When in DSD mode with S/PDIF output enabled, DSD samples are transmitted over S/PDIF if the DSD and S/PDIF channels are shared, this may or may not be desired
- When in DSD mode with S/PDIF output enabled, DSD samples are transmitted over S/PDIF if the DSD and S/PDIF channels are shared, this may or may not be desired (#14762)
- (#14173) I2S input is completely disabled when DSD output is active - any input stream to the host will contain 0 samples
- I2S input is completely disabled when DSD output is active - any input stream to the host will contain 0 samples (#14173)
- (#14780) Operating the design at a sample rate of less than or equal to the SOF rate (i.e. 8kHz at HS, 1kHz at FS) may expose a corner case relating to 0 length packet handling in both the driver and device and should be considered un-supported at this time.
- Operating the design at a sample rate of less than or equal to the SOF rate (i.e. 8kHz at HS, 1kHz at FS) may expose a corner case relating to 0 length packet handling in both the driver and device and should be considered unsupported at this time (#14780)
- (#14883) Before DoP mode is detected a small number of DSD samples will be played out as PCM via I2S
- Before DoP mode is detected a small number of DSD samples will be played out as PCM via I2S (lib_xua #162)
- (#14887) Volume control settings currently affect samples in both DSD and PCM modes. This results in invalid DSD output if volume control not set to 0
- Volume control settings currently affect samples in both DSD and PCM modes. This results in invalid DSD output if volume control not set to 0 (#14887)
- Windows XP volume control very sensitive. The Audio 1.0 driver built into Windows XP (usbaudio.sys) does not properly support master volume AND channel volume controls, leading to a very sensitive control. Descriptors can be easily modified to disable master volume control if required (one byte - bmaControls(0) in Feature Unit descriptors)
- 88.2kHz and 176.4kHz sample frequencies are not exposed in Windows control panels. These are known OS restrictions.
- 88.2kHz and 176.4kHz sample frequencies are not exposed in Windows control panels. These are known OS restrictions.
- When DFU flash access fails the device NAKS the host indefinitely (sw_usb_audio #54)
- Host mixer app (xmos_mixer) is currently not provided (lib_xua #279)
- In synchronous mode there is no nice transition of the reference signal when moving between internal and SOF clocks (lib_xua #275)
- Binary images exceeding FLASH_MAX_UPGRADE_SIZE fail silently on DFU download (lib_xua #165)
- UAC 1.0 mode assumes device always has input. A run time exception occurs if this is not the case (lib_xua #58)
- No support for I2S_CHANS_DAC = 0 and I2S_CHANS_ADC = 0 (lib_xua #260)

32
lib_xua/doc/rst/lib_xua.rst
View File

@@ -1,37 +1,25 @@
.. include:: ../../../README.rst
About This Document
-------------------
~~~~~~~~~~~~~~~~~~~
This document describes the structure of the library, its use and resources required. It also covers some implementation detail.
This document describes the structure of ``lib_xua``, its use and resources required. It also covers some implementation detail.
This document assumes familiarity with the XMOS xCORE architecture, the Universal Serial Bus 2.0 Specification (and related specifications),
the XMOS tool chain and XC language.
Host System Requirements
------------------------
USB Audio devices built using `lib_xua` have the following host system requirements.
- Mac OSX version 10.6 or later
- Windows Vista, 7, 8 or 10 with Thesycon Audio Class 2.0 driver for Windows (Tested against version 3.20). Please contact XMOS for details.
- Windows Vista, 7, 8 or 10 with built-in USB Audio Class 1.0 driver.
Older versions of Windows are not guaranteed to operate as expected. Devices are also expected to operate with various Linux distributions including mobile variants.
.. toctree::
Overview <overview>
Hardware Platforms <hw>
Software Overview <sw>
Using lib_xua <using>
Features <feat>
Software Detail <sw_detail>
Software Architecture <arch>
Basic Usage <using>
Options <opt>
Advanced Usage <using_adv>
Additional Features <feat>
Software Detail <sw>
API <api>
Known Issues <issues>

37
lib_xua/doc/rst/opt.rst Normal file
View File

@@ -0,0 +1,37 @@
.. _sec_options:
Options
-------
This section describes key options of ``lib_xua``. These are typically controlled using build time defines.
Where something must be defined, it is recommended this is done in `xua_conf.h` but could also be done in the application Makefile.
For full details of all options please see ::ref:`sec_api`.
.. toctree::
Strings <opt_strings>
Code Location <opt_location>
Channel Counts and Sample Rates <opt_channels>
USB Audio Class Support <opt_audio_class>
Synchronisation <opt_sync>
I2S/TDM <opt_i2s>
S/PDIF Transmit <opt_spdif_tx>
S/PDIF Receive <opt_spdif_rx>
MIDI <opt_midi>
PDM Microphones <opt_pdm>
Mixer <opt_mixer>
Direct Stream Digital (DSD) <opt_dsd>
USB Audio Formats <opt_audio_formats>
Other Options <opt_other>

53
lib_xua/doc/rst/sw_usb_audio_class.rst → lib_xua/doc/rst/opt_audio_class.rst
View File

@@ -1,16 +1,21 @@
USB Audio Class Version Support
-------------------------------
|newpage|
The XMOS USB Audio framework supports both USB Audio Class 1.0 and Audio Class 2.0.
USB Audio Class Version
~~~~~~~~~~~~~~~~~~~~~~~
USB Audio Class 2.0 offers many improvements over USB Audio Class 1.0, most notable is the complete support for high-speed operation. This means that Audio Class devices are no longer limited to full-speed operation allowing greater channel counts, sample frequencies and sample bit-depths. Additional improvement, amoungst others, include:
The codebase supports USB Audio Class versions 1.0 and 2.0.
USB Audio Class 2.0 offers many improvements over USB Audio Class 1.0, most notable is the complete
support for high-speed operation. This means that Audio Class devices are no longer limited to
full-speed 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
Driver Support
~~~~~~~~~~~~~~
..............
Audio Class 1.0
+++++++++++++++
@@ -20,14 +25,16 @@ Audio Class 1.0 is fully supported in Apple OSX. Audio Class 1.0 is fully suppo
Audio Class 2.0
+++++++++++++++
Audio Class 2.0 is fully supported in Apple OSX since version 10.6.4. Audio Class 2.0 is not supported natively by Windows operating systems. It is therefore required that a driver is installed. Documentation of Windows drivers is beyond the scope of this document, please contact XMOS for further details.
Audio Class 2.0 is fully supported in Apple OSX since version 10.6.4. Starting with Windows 10, release 1703, a USB Audio 2.0 driver is shipped with Windows.
Third party Windows drivers are also available, however, documentation of these is beyond the scope of this document, please contact XMOS for further details.
Audio Class 1.0 Mode and Fall-back
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
..................................
The normal default for XMOS USB Audio applications is to run as a high-speed Audio Class 2.0
The default for XMOS USB Audio applications is to run as a high-speed Audio Class 2.0
device. However, some products may prefer to run in Audio Class 1.0 mode, this is normally to
allow "driver-less" operation with Windows operating systems.
allow "driver-less" operation with older versions of Windows operating systems.
.. note::
@@ -41,7 +48,7 @@ The device will operate in full-speed Audio Class 1.0 mode if one of the followi
to the host over a full speed link (and the Audio Class fall back is
enabled).
The options to control this behavior are detailed in :ref:`usb_audio_sec_custom_defines_api`.
The options to control this behavior are detailed in :ref:`sec_api_defines`.
When running in Audio Class 1.0 mode the following restrictions are applied:
@@ -55,3 +62,29 @@ Due to bandwidth limitations of full-speed USB the following sample-frequency re
- Sample rate is limited to a maximum of 96kHz if only input *or* output is enabled.
Related Defines
................
:ref:`opt_audio_class_defines` descibes the defines that effect audio class selection.
.. _opt_audio_class_defines:
.. list-table:: Audio Class defines
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``AUDIO_CLASS``
- Audio Class version (1 or 2)
- N/A (*must* be defined)
* - ``AUDIO_CLASS_FALLBACK``
- Enable audio class fallback functionalty
- ``0`` (disabled)
.. note::
Enabling USB Audio Class fallback functionality may have USB Compliance implications

136
lib_xua/doc/rst/opt_audio_formats.rst Normal file
View File

@@ -0,0 +1,136 @@
|newpage|
.. _sec_opt_audio_formats:
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 <http://www.usb.org/developers/devclass_docs/Audio2.0_final.zip>`_
Customisable parameters for the Alternate Settings provided by the design are as follows.:
* Audio sample resolution
* Audio sample subslot size
* Audio data format
.. note::
Currently only a single format is supported for the recording stream
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.
Audio Subslot
.............
An audio subslot holds a single audio sample. See `USB Device Class Definition for Audio Data Formats
<http://www.usb.org/developers/devclass_docs/Audio2.0_final.zip>`_ for full details.
This is represented by `bSubslotSize` in the devices descriptor set.
An audio subslot always contains an integer number of bytes. The specification limits the possible
audio subslot size to 1, 2, 3 or 4 bytes per audio subslot.
Since the xCORE is a 32-bit machine the value 4 is typically used for `bSubSlot` - this means that
packing/unpacking samples to/from packets is trivial. Other values can, however, be used and the design
supports values 4, 3 and 2.
Values other than 4 may be used for the following reasons:
* Bus-bandwidth needs to be efficiently utilised. For example maximising channel-count/sample-rates in
full-speed operation.
* To support restrictions with certain hosts. For example many Android based hosts support only 16bit
samples in a 2-byte subslot.
`bSubSlot` size is set using the following defines:
* When running in high-speed:
* `HS_STREAM_FORMAT_OUTPUT_1_SUBSLOT_BYTES`
* `HS_STREAM_FORMAT_OUTPUT_2_SUBSLOT_BYTES`
* `HS_STREAM_FORMAT_OUTPUT_3_SUBSLOT_BYTES`
* When running in full-speed:
* `FS_STREAM_FORMAT_OUTPUT_1_SUBSLOT_BYTES`
* `FS_STREAM_FORMAT_OUTPUT_2_SUBSLOT_BYTES`
* `FS_STREAM_FORMAT_OUTPUT_3_SUBSLOT_BYTES`
Audio Sample Resolution
.......................
An audio sample is represented using a number of bits (`bBitResolution`) less than or equal to the number
of total bits available in the audio subslot i.e. `bBitResolution` <= `bSubslotSize` * 8). The design
supports values 16, 24 and 32.
`bBitResolution` is set using the following defines:
* When operating at high-speed:
* `HS_STREAM_FORMAT_OUTPUT_1_RESOLUTION_BITS`
* `HS_STREAM_FORMAT_OUTPUT_2_RESOLUTION_BITS`
* `HS_STREAM_FORMAT_OUTPUT_3_RESOLUTION_BITS`
* When operating at full-speed:
* `FS_STREAM_FORMAT_OUTPUT_1_RESOLUTION_BITS`
* `FS_STREAM_FORMAT_OUTPUT_2_RESOLUTION_BITS`
* `FS_STREAM_FORMAT_OUTPUT_3_RESOLUTION_BITS`
Audio Format
............
The design supports two audio formats, PCM and, when "Native" DSD is enabled, Direct Stream Digital (DSD).
A DSD capable DAC is required for the latter.
The USB Audio `Raw Data` format is used to indicate DSD data (2.3.1.7.5 of `USB Device Class
Definition for Audio Data Formats <http://www.usb.org/developers/devclass_docs/Audio2.0_final.zip>`_).
This use of a RAW/DSD format in an alternative setting is termed by XMOS as *Native DSD*
The following defines affect both full-speed and high-speed operation:
* STREAM_FORMAT_OUTPUT_1_DATAFORMAT
* STREAM_FORMAT_OUTPUT_2_DATAFORMAT
* STREAM_FORMAT_OUTPUT_3_DATAFORMAT
The following options are supported:
* UAC_FORMAT_TYPEI_RAW_DATA
* UAC_FORMAT_TYPEI_PCM
.. note::
Currently DSD is only supported on the output/playback stream
.. note::
4 byte slot size with a 32 bit resolution is required for RAW/DSD format
Native DSD requires driver support and is available in the Thesycon Windows driver via ASIO.

73
lib_xua/doc/rst/opt_channels.rst Normal file
View File

@@ -0,0 +1,73 @@
|newpage|
Channel Counts and Sample Rates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The codebase 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 :ref:`opt_channel_defines` set the channel counts exposed to the USB host.
.. tabularcolumns:: lp{5cm}l
.. _opt_channel_defines:
.. list-table:: Channel count defines
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``NUM_USB_CHAN_OUT``
- Number of output channels the device advertises to the USB host
- N/A (must be defined)
* - ``NUM_USB_CHAN_IN``
- Number of input channels the device advertises to the USB host
- N/A (must be defined)
Sample rates ranges are set by the defines in :ref:`opt_channel_sr_defines`. The codebase will
automatically populate the device sample rate list with popular frequencies between the min and
max values. All values are in Hz:
.. tabularcolumns:: lp{5cm}l
.. _opt_channel_sr_defines:
.. list-table:: Sample rate defines
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``MAX_FREQ``
- Maximum supported sample rate (Hz)
- ``192000``
* - ``MIN_FREQ``
- Minimum supported sample rate (Hz)
- ``44100``
* - ``DEFAULT_FREQ``
- Starting frequency for the device after boot
- ``MIN_FREQ``
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 :ref:`opt_channel_mc_defines`. All values are in Hz.
.. tabularcolumns:: lp{5cm}l
.. _opt_channel_mc_defines:
.. list-table:: Master clock rate defines
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``CLK_441``
- Master clock defines for 44100 rates (Hz)
- ``(256 * 44100)``
* - ``MCLK_48``
- Master clock defines for 48000 rates (Hz)
- ``(256 * 48000)``

104
lib_xua/doc/rst/opt_dsd.rst Normal file
View File

@@ -0,0 +1,104 @@
|newpage|
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.
The codebase 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 define in :ref:`opt_dsd_defines` to a non-zero value.
.. _opt_dsd_defines:
.. list-table:: DSD defines
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``DSD_CHANS_DAC``
- Number of DSD channels
- ``0`` (Disabled)
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: ::ref:`sec_opt_audio_formats` for details.
If only DoP functionality is desired the Native implementation can be disabled with the define in
:ref:`opt_nativedsd_defines`.
.. _opt_nativedsd_defines:
.. list-table:: Native DSD defines
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``NATIVE_DSD``
- Enable/Disable "Native" DSD implementation
- ``1`` (Enabled)
DSD over PCM (DoP)
..................
DoP support follows the method described in the `DoP Open Standard 1.1
<http://dsd-guide.com/sites/default/files/white-papers/DoP_openStandard_1v1.pdf>`_.
While Native DSD support is available in Windows though a driver, OSX incorporates a USB driver
that only supports PCM, this is also true of the central audio engine, CoreAudio. It is
therefore not possible to use the "Native" scheme defined above using the built in driver of OSX.
Since the Apple OS only allows a PCM path a method of transporting DSD audio data over PCM frames
has been developed.
Standard DSD has a sample size of 1 bit and a sample rate of 2.8224MHz - this is 64x the speed of a
compact disc (CD). This equates to the same data-rate as a 16 bit PCM stream at 176.4kHz.
In order to clearly identify when this PCM stream contains DSD and when it contains PCM some header
bits are added to the sample. A 24-bit PCM stream is therefore used, with the most significant
byte being used for a DSD marker (alternating 0x05 and 0xFA values).
When enabled, if USB audio design detects a un-interrupted run of these samples (above a defined
threshold) it switches to DSD mode, using the lower 16-bits as DSD sample data. When this check for
DSD headers fails the design falls back to PCM mode. DoP detection and switching is done completely
in the Audio/I2S core (`audio.xc`). All other code handles the audio samples as PCM.
The design supports higher DSD/DoP rates (i.e. DSD128) by simply raising the underlying PCM sample
rate e.g. from 176.4kHz to 352.8kHz. The marker byte scheme remains exactly the same regardless
of rate.
.. note::
DoP requires bit-perfect transmission - therefore any audio/volume processing will break the stream.
"Native" vs DoP
~~~~~~~~~~~~~~~
Since the DoP specification requires header bytes this eats into the data bandwidth. The "Native" implementation
has no such overhead and can therefore transfer the same DSD rate and half the effective PCM rate of DoP.
Such a property may be desired when upporting DSD128 without exposing a 352.8kHz PCM rate, for example.
Ports
.....
The codebase expects 1-bit ports to be defined in the application XN file for the DSD data and
clock lines for example::
<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"/>
.. note::
The DSD ports may or may not overlap the I2S ports - the codebase will reconfigure the ports as appropriate
when switching between PCM and DSD modes.

49
lib_xua/doc/rst/opt_i2s.rst Normal file
View File

@@ -0,0 +1,49 @@
|newpage|
I2S/TDM
~~~~~~~
I2S/TDM is typically fundamental to most products and is built into the ``XUA_AudioHub()`` core.
The defines in :ref:`opt_i2s_defines` effect the I2S implementation.
.. tabularcolumns:: lp{5cm}l
.. _opt_i2s_defines:
.. list-table:: I2S defines
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``I2S_CHANS_DAC``
- The desired number of output channels via I2S (0 for disabled)
- N/A (Must be defined)
* - ``I2S_CHANS_ADC``
- The desired number of input channels via I2S (0 for disabled)
- N/A (Must be defined)
* - ``XUA_PCM_FORMAT``
- Enabled either TDM or I2S mode
- ``XUA_PCM_FORMAT_I2S``
* - ``CODEC_MASTER``
- Sets is xCORE is I2S master or slave
- ``0`` (xCORE is master)
The I2S code expects that the ports required for I2S (master clock, LR-clock, bit-clock and data lines) are be defined in the application XN file in 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 I2S related ports must be 1-bit ports.
.. note::
TDM mode allows 8 channels (rather than 2) to be supplied on each dataline.

44
lib_xua/doc/rst/opt_location.rst Normal file
View File

@@ -0,0 +1,44 @@
|newpage|
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``. :ref:`opt_location_defines` shows a
full listing of these ``TILE`` defines.
.. tabularcolumns:: lp{5cm}l
.. _opt_location_defines:
.. list-table:: Tile defines
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``AUDIO_IO_TILE``
- Tile on which I2S, ADAT Rx, S/PDIF Rx & mixer resides
- ``0``
* - ``XUD_TILE``
- Tile on which USB resides, including buffering for all USB interfaces/endppoints
- ``0``
* - ``MIDI_TILE``
- Tile on which MIDI resides
- Same as ``AUDIO_IO_TILE``
* - ``SPDIF_TX_TILE``
- Tile on which S/PDIF Tx resides
- Same as ``AUDIO_IO_TILE``
* - ``PDM_TILE``
- Tile on which PDM microphones resides
- Same as ``AUDIO_IO_TILE``
* - ``PLL_REF_TILE``
- Tile on which reference signal to CS2100 resides
- Same as ``AUDIO_IO_TILE``
.. note::
It should be ensured that the relevant port defines in the application XN file match the code location defines

54
lib_xua/doc/rst/opt_midi.rst Normal file
View File

@@ -0,0 +1,54 @@
|newpage|
MIDI
~~~~
The codebase supports MIDI input/output over USB as per `Universal Serial Bus Device Class Definition for MIDI Devices <https://www.usb.org/sites/default/files/midi10.pdf>`_.
MIDI functionality is enabled with the define in :ref:`opt_midi_defines`.
.. _opt_midi_defines:
.. list-table:: MIDI enable define
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``MIDI``
- Enable MIDI functionality
- ``0`` (Disabled)
The codebase supports MIDI receive on a 4-bit or 1-bit port, defaulting to using a 1-bit port.
MIDI transmit is supported port of any bit-width. By default the codebase assumes the transmit
and receive I/O is connected to bit[0] of the port. This is configurable for the transmit port.
:ref:`opt_midi_defines` provides information on the configuring these parameters.
.. _opt_midi_port_defines:
.. list-table:: MIDI port defines
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``MIDI_RX_PORT_WIDTH``
- Port width of the MIDI rx port (1 or 4bit)
- ``1`` (1-bit port)
* - ``MIDI_SHIFT_TX``
- MIDI tx bit
- ``0`` (bit[0])
The MIDI code expects that the ports for receive and transmit are defined in the application XN file in 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>

41
lib_xua/doc/rst/opt_mixer.rst Normal file
View File

@@ -0,0 +1,41 @@
|newpage|
Mixer
~~~~~
The codebase 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 :ref:`usb_audio_sec_mixer` for full details of the mixer including control.
Basic configuration of mixer functionality is achieved with the defines in :ref:`opt_mixer_defines`.
.. _opt_mixer_defines:
.. list-table:: Mixer defines
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``MIXER``
- Enable mixer
- ``0`` (Disabled)
* - ``MAX_MIX_COUNT``
- Number of separate mix outputs to perform
- ``8``
* - ``MIX_INPUTS``
- Number of channels input into the mixer
- ``18``
.. note::
The mixer cores always run on the tile defined by ``AUDIO_IO_TILE``

27
lib_xua/doc/rst/opt_other.rst Normal file
View File

@@ -0,0 +1,27 @@
|newpage|
Other Options
~~~~~~~~~~~~~
There are a few other, lesser used, options available.
.. _opt_other_defines:
.. list-table:: Other defines
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``XUA_USB_EN``
- Allows the use of the audio subsytem without USB
- ``1`` (enabled)
* - ``INPUT_VOLUME_CONTROL``
- Enables volume control on input channels, both descriptors and processing
- ``1`` (enabled)
* - ``OUTPUT_VOLUME_CONTROL``
- Enables volume control on output channels, both descriptors and processing
- ``1`` (enabled)

36
lib_xua/doc/rst/opt_pdm.rst Normal file
View File

@@ -0,0 +1,36 @@
|newpage|
PDM Microphones
~~~~~~~~~~~~~~~
The codebase supports input from up to 8 PDM microphones.
PDM microphone support is provided via ``lib_mic_array``. Settings for PDM microphones are controlled
via the defines in :ref:`opt_pdm_defines`.
.. _opt_pdm_defines:
.. list-table:: PDM defines
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``XUA_NUM_PDM_MICS``
- The number of mics to enable (0 for disabled)
- ``0`` (disabled)
* - ``PDM_MIC_INDEX``
- Defines which input channel the mics map to
- ``0``
The codebase expects 1-bit ports to be defined in the application XN file for ``PORT_PDM_CLK`` and ``PORT_PDM_MCLK``.
An 8-bit port is expected for ``PORT_PDM_DATA``. For example::
<Tile Number="0" Reference="tile[0]">
<!-- Mic related ports -->
<Port Location="XS1_PORT_1E" Name="PORT_PDM_CLK"/>
<Port Location="XS1_PORT_8B" Name="PORT_PDM_DATA"/>
<Port Location="XS1_PORT_1F" Name="PORT_PDM_MCLK"/>
</Tile>

60
lib_xua/doc/rst/opt_spdif_rx.rst Normal file
View File

@@ -0,0 +1,60 @@
|newpage|
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`` (https://www.github.com/xmos/lib_spdif).
Basic configuration of S/PDIF receive functionality is achieved with the defines in :ref:`opt_spdif_rx_defines`.
.. _opt_spdif_rx_defines:
.. list-table:: S/PDIF rx defines
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``XUA_SPDIF_RX_EN``
- Enable S/PDIF receive
- ``0`` (Disabled)
* - ``SPDIF_RX_INDEX``
- Defines which channels S/PDIF will be input on
- N/A (must defined)
.. note::
S/PDIF receive always runs on the tile defined by ``AUDIO_IO_TILE``
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 drive a synchronisation signal to an external
Cirrus Logic CS2100 device for master-clock generation.
The programmer should ensure the define in :ref:`opt_spdif_rx_ref_defines` is set appropriately.
.. _opt_spdif_rx_ref_defines:
.. list-table:: Reference Clock Location
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``PLL_REF_TILE``
- Tile location of reference to CS2100 device
- ``AUDIO_IO_TILE``
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.

46
lib_xua/doc/rst/opt_spdif_tx.rst Normal file
View File

@@ -0,0 +1,46 @@
|newpage|
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`` (https://www.github.com/xmos/lib_spdif).
Basic configuration of S/PDIF transmit functionality is achieved with the defines in :ref:`opt_spdif_tx_defines`
.. _opt_spdif_tx_defines:
.. list-table:: S/PDIF tx defines
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``XUA_SPDIF_TX_EN``
- Enable S/PDIF transmit
- ``0`` (Disabled)
* - ``SPDIF_TX_INDEX``
- Output channel offset to use for S/PDIF transmit
- ``0``
In addition, the developer may choose which tile the S/PDIF transmitter runs on, see :ref:`opt_spdif_tx_tile_defines`.
.. _opt_spdif_tx_tile_defines:
.. list-table:: S/PDIF tile define
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``SPDIF_TX_TILE``
- Tile that S/PDIF tx is connected to
- ``AUDIO_IO_TILE``
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"/>

41
lib_xua/doc/rst/opt_strings.rst Normal file
View File

@@ -0,0 +1,41 @@
Strings and ID's
~~~~~~~~~~~~~~~~
The codebase includes various strings and ID's that should be customised to match the product requirements.
These are listed in ::ref:`opt_strings_defines`.
The Vendor ID (VID) should be acquired from the USB Implementers Forum (www.usb.org). Under no circumstances
should the XMOS VID or any other VID be used without express permission.
The VID and Product ID (PID) pair must be unique to each product, otherwise driver incompatibilities may arise.
.. tabularcolumns:: lp{5cm}l
.. _opt_strings_defines:
.. list-table:: String & ID defines
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``VENDOR_STR``
- Name of vendor/manufacturer, note the is appended to various strings.
- ``"XMOS"``
* - ``PRODUCT_STR_A2``
- Name of the product when running in Audio Class 2.0 mode
- ``"XMOS xCORE (UAC2.0)"``
* - ``PRODUCT_STR_A1``
- Name of the product when running in Audio Class 1.0 mode
- ``"XMOS xCORE (UAC1.0)"``
* - ``PID_AUDIO_2``
- Product ID when running in Audio Class 2.0 mode
- ``0x0002``
* - ``PID_AUDIO_1``
- Product ID when running in Audio Class 1.0 mode
- ``0x0003``

66
lib_xua/doc/rst/opt_sync.rst Normal file
View File

@@ -0,0 +1,66 @@
|newpage|
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 it's 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 PC's 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.
.. note::
The selection of synchronisation mode is done at build time and cannot be changed dynamically.
Setting the synchronisation mode of the device is done using the define in :ref:`opt_sync_defines`
.. _opt_sync_defines:
.. list-table:: Sync Define
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``XUA_SYNCMODE``
- USB synchronisation mode
- ``XUA_SYNCMODE_ASYNC``
When operating in synchronous mode an external Cirrus Logic CS2100 device is required for master clock
generation. The codebase expects to drive a synchronisation signal to this external device
The programmer should ensure the define in :ref:`opt_sync_ref_defines` is set appropriately.
.. _opt_sync_ref_defines:
.. list-table:: Reference clock location
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``PLL_REF_TILE``
- Tile location of reference to CS2100 device
- ``AUDIO_IO_TILE``
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.

16
lib_xua/doc/rst/overview.rst
View File

@@ -1,5 +1,5 @@
USB Audio Solution Overview
---------------------------
Overview
--------
.. table::
@@ -48,19 +48,21 @@ USB Audio Solution Overview
| **Supported Devices** |
+-------------------------------------------------------------------------------------------------------------------------------+
+---------------------------------+---------------------------------------------------------------------------------------------+
| XMOS Devices | xCORE-200 Series |
| XMOS Devices | xCORE-200 Series |
| +---------------------------------------------------------------------------------------------+
| | xCORE.AI Series |
+---------------------------------+---------------------------------------------------------------------------------------------+
+-------------------------------------------------------------------------------------------------------------------------------+
| **Requirements** |
+-------------------------------------------------------------------------------------------------------------------------------+
+---------------------------------+---------------------------------------------------------------------------------------------+
| Development Tools | xTIMEcomposer Development Tools v14 or later |
| Development Tools | xTIMEcomposer Development Tools v15.1 or later |
+---------------------------------+---------------------------------------------------------------------------------------------+
| USB | xCORE-200 Series device with integrated USB Phy |
| USB | xCORE device with integrated USB phy (external phy not supported) |
+---------------------------------+---------------------------------------------------------------------------------------------+
| Audio | External audio DAC/ADC/CODECs (and required supporting componentry) supporting I2S/TDM |
| Audio | External audio DAC/ADC/CODECs (and required supporting componentry) supporting I2S/TDM |
+---------------------------------+---------------------------------------------------------------------------------------------+
| Boot/Storage | Compatible SPI Flash device (or xCORE-200 device with internal flash) |
| Boot/Storage | Compatible SPI/QSPI Flash device (or xCORE device with internal flash) |
+---------------------------------+---------------------------------------------------------------------------------------------+
+-------------------------------------------------------------------------------------------------------------------------------+
| **Licensing and Support** |

100
lib_xua/doc/rst/sw.rst
View File

@@ -1,89 +1,21 @@
.. _usb_audio_sec_architecture:
Implementation Detail
---------------------
USB Audio Software Overview
---------------------------
This section examines the implementation of the various components that make up ``lib_xua``. It also examines the integration of dependencies and supporting libraries.
This section describes the software architecture of a USB Audio device implemented using `lib_xua`, its dependencies and other supporting libraries.
`lib_xua` provides fundamental building blocks for producing USB Audio products on XMOS devices. Every system is required to have the components from `lib_xua` listed in :ref:`usb_audio_shared_components`.
.. _usb_audio_shared_components:
.. list-table:: Required XUA Components
:header-rows: 1
:widths: 40 60
* - Component
- Description
* - Endpoint 0
- Provides the logic for Endpoint 0 which handles
enumeration and control of the device including DFU related requests.
* - Endpoint buffer
- Buffers endpoint data packets to and from the host. Manages delivery of audio packets between the endpoint buffer
component and the audio components. It can also handle volume control processing.Note, this currently utlises two cores
* - AudioHub
- Handles audio I/O over I2S and manages audio data
to/from other digital audio I/O components.
In addition low-level USB I/0 is required and is provided by the external dependency `lib_xud`
.. list-table:: Additional Components Required
:header-rows: 1
:widths: 100 60
* - Component
- Description
* - XMOS USB Device Driver (XUD)
- Handles the low level USB I/O.
In addition :ref:`usb_audio_optional_components` shows optional components that can be added/enabled from within `lib_xua`
.. _usb_audio_optional_components:
.. list-table:: Optional Components
:header-rows: 1
:widths: 40 60
* - Component
- Description
* - Mixer
- Allows digital mixing of input and output channels. It can also
handle volume control instead of the decoupler.
* - Clockgen
- Drives an external frequency generator (PLL) and manages
changes between internal clocks and external clocks arising
from digital input.
* - MIDI
- Outputs and inputs MIDI over a serial UART interface.
`lib_xua` also provides optional support for integrating with the following eternal dependencies:
.. list-table:: Optional Components
:header-rows: 1
:widths: 40 60
* - Component
- Description
* - S/PDIF Transmitter (lib_spdif)
- Outputs samples of an S/PDIF digital audio interface.
* - S/PDIF Receiver (lib_spdif)
- Inputs samples of an S/PDIF digital audio interface (requires the
clockgen component).
* - ADAT Receiver (lib_adat)
- Inputs samples of an ADAT digital audio interface (requires the
clockgen component).
* - PDM Microphones (lib_mic_array)
- Receives PDM data from microphones and performs PDM to PCM conversion
.. _usb_audio_threads:
.. figure:: images/threads-crop.*
:width: 100%
USB Audio Core Diagram
:ref:`usb_audio_threads` shows how the components interact with each
other in a typical system. The green circles represent cores with arrows indicating inter-core communications.
.. toctree::
sw_audio
sw_ep0
sw_xud
sw_clocking
sw_spdif
sw_mixer
sw_spdif_rx
sw_adat_rx
sw_midi
sw_pdm
sw_hid
sw_resource

54
lib_xua/doc/rst/sw_adat.rst
View File

@@ -1,54 +0,0 @@
ADAT Receive
------------
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 :ref:`usb_audio_sec_component_api`.
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
Example of code show 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.
.. Timing Requirements
~~~~~~~~~~~~~~~~~~~
.. The data samples are outputted onto the channel every 2.4 us. The
.. control sample follows 1.7 us after the last data sample, and is
.. followed 2.4 us later by the first data sample. Given that a channel
.. can hold two words of data, when data appears on the channel, it
.. should be input within 4.1 us otherwise the ADAT receiver will block,
.. and data will be lost. Between data samples a window of 4.8 us is
.. available.
Integration
~~~~~~~~~~~
Since the ADAT is a digital stream the devices master clock must synchronised to it. This is
typically achieved with an external fractional-n clock multiplier.
The ADAT receive function communicates with the clockGen component which passes audio data onto the
audio driver and handles locking to the ADAT clock source if required.

54
lib_xua/doc/rst/sw_adat_rx.rst Normal file
View File

@@ -0,0 +1,54 @@
|newpage|
ADAT Receive
------------
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 :ref:`usb_audio_sec_component_api`.
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.
Usage and Integration
~~~~~~~~~~~~~~~~~~~~~
Since the ADAT is a digital stream the device's master clock must synchronised to it. The integration
of ADAT receive is much the same as S/PDIF receive in that the ADAT receive function communicates
with the Clock Gen core. This Clock Gen Core then passes audio data onto the Audio Hub core.
It also handles locking to the ADAT clock source.
There are some small differences with the S/PDIF integration accounting for the fact that ADAT
typically has 8 channels compared to S/DIF's two.
The Clock Gen core also handles SMUX II (e.g. 4 channels at 96kHz) and SMUX IV (e.g. 2 channels at
192kHz), populating the sample FIFO as appropriate. SMUX modes are communicated to the Clock Gen
core from Endpoint 0 via the ``c_clk_ctl`` channel. SMUX modes are exposed to the USB host using
Alternative Interfaces, with appropriate channel counts, for the streaming input Endpoint.

75
lib_xua/doc/rst/sw_audio.rst
View File

@@ -1,26 +1,32 @@
|newpage|
.. _usb_audio_sec_audio:
AudioHub/I2S
............
Audio Hub
.........
The AudioHub task performs many functions. It receives and transmits samples from/to the decoupler or mixer core over an XC channel.
The Audio Hub task performs many functions. It receives and transmits samples from/to the Decoupler
or Mixer core over a channel.
It also drives several in and out I2S/TDM channels to/from a CODEC, DAC, ADC etc - from now on termed "audio hardware".
It also drives several in and out I2S/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 I2S master the requred clock lines will also be driven out from this task also.
If the firmware is configured with the xCORE as I2S 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/cores such as S/PDIF tasks, ADAT etc.
It also has the task of formwarding on and reciving samples to/from other audio related tasks such as S/PDIF tasks, ADAT tasks etc.
In master mode, the xCORE generates the I2S "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 I2S and can be used.
The AudioHub task must be connected to external audio hardware that supports I2S (other modes such as "left justified" can be supported with firmware changes).
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 I2S standard but is commonly
included for synchronizing the internal operation of the analog/digital converters.
In master mode, the XMOS device acts as the master generating the I2S "Continous Serial Clock (SCK)" typically called the Bit-Clock (BCLK) and the "Word Select (WS)" line typically called left-right clock (LRCLK) signals. Any CODEC or DAC/ADC combination that supports I2S and can be used.
The Audio Hub task is implemented in the file ``xua_audiohub.xc``.
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 I2S standard but is commonly included for synchronizing the internal operation of the analog/digital converters.
The AudioHub task is implemented in the file ``xua_audiohub.xc``.
:ref:`usb_audio_codec_signals` shows the signals used to communicate audio between the XMOS device and the external audio hardware.
:ref:`usb_audio_codec_signals` shows the signals used to communicate audio between the XMOS device
and the external audio hardware.
.. _usb_audio_codec_signals:
@@ -83,9 +89,12 @@ with BCLK then being used to clock data in (SDIN) and data out (SDOUT) of the ex
- 12.288
- 2
The master clock must be supplied by an external source e.g. clock generator, fixed oscillators, PLL etc to generate the two frequencies to support
44.1kHz and 48kHz audio frequencies (e.g. 11.2896/22.5792MHz and 12.288/24.576MHzrespectively). This master clock input is then provided to the
external audio hardware and the xCORE device.
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 to support 44.1kHz and 48kHz 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.
Port Configuration (xCORE Master)
@@ -122,38 +131,16 @@ The preceding diagram shows the connectivity of ports and clock blocks.
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.
xCORE-200 series devices have the ability to divide an extenal clock in a clock-block.
Unlike previous xCORE architectures, xCORE-200 (XS2) and xCORE.ai (XS3) series devices have the ability to divide an external clock in a clock-block.
However, XS1 based devices do not have this functionality. In order achieve the reqired master-clock
to bit-clock/LR-clock divicd on XS1 devices, buffered ports with a transfer width of 32 are also
used for ``p_bclk`` and ``p_lrclk``. The bit clock is generated by performing outputs of a particular pattern to ``p_bclk`` to toggle
the output at the desired rate. The pattern depends on the divide between the master-clock and bit-clock.
The following table shows the required pattern for different values of this divide:
.. list-table:: Output patterns
:header-rows: 1
* - Divide
- Output pattern
- Outputs per sample
* - 2
- ``0xAAAAAAAA``
- 2
* - 4
- ``0xCCCCCCCC``
- 4
* - 8
- ``0xF0F0F0F0``
- 8
In any case, 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 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 I2S 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 I2S standard) and alternates between high and low for the
left and right channels of audio.
before the data (as required by the I2S standard) and alternates between high and low for the left
and right channels of audio.
Changing Audio Sample Frequency
+++++++++++++++++++++++++++++++
@@ -170,7 +157,7 @@ Upon receiving the change of sample frequency request, the audio
core stops the I2S/TDM interface and calls the CODEC/port configuration
functions.
Once this is complete, the I2S/TDM interface (i.e. the main look in AudioHub) is restarted at the new frequency.
Once this is complete, the I2S/TDM interface (i.e. the main loop in AudioHub) is restarted at the new frequency.

67
lib_xua/doc/rst/sw_clocking.rst
View File

@@ -1,35 +1,60 @@
|newpage|
.. _usb_audio_sec_clock_recovery:
External Clock Recovery (ClockGen)
----------------------------------
External Clock Recovery (Clock Gen)
-----------------------------------
An application can either provide fixed master clock sources via selectable oscillators, clock
generation IC, etc, to provide the audio master or use an external PLL/Clock Multiplier to
generate a master clock based on reference from the XMOS device.
To provide an audio master clock an application may use selectable oscillators, clock
generation IC or, in the case of xCORE.ai devices, integrated secondary PLL, to generate fixed
master clock frequencies.
Using an external PLL/Clock Multiplier allows the design to lock to an external clock source
from a digital stream (e.g. S/PDIF or ADAT input).
It may also use an external PLL/Clock Multiplier to generate a master clock based on a reference from
the xCORE.
The clock recovery core (clockGen) is responsible for generating the reference frequency
to the Fractional-N Clock Generator. This, in turn, generates the master clock used over the
whole design.
Using 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). The code-base supports the Cirrus
Logic CS2100 device for this purpose. Other devices may be supported via code modification.
.. note::
It is expected that in a future release the secondary PLL in xCORE.ai devices, coupled with
associated software changes, will be capable of replacing the CS2100 part for most designs.
The Clock Recovery core (Clock Gen) is responsible for generating the reference frequency
to the CS2100 device. This, in turn, generates the master clock used over the whole design.
This core also serves as a smaller buffer between ADAT and S/PDIF receiving cores and the Audio Hub
core.
When running in *Internal Clock* mode this core simply generates this clock using a local
timer, based on the XMOS reference clock.
When running in an external clock mode (i.e. S/PDIF Clock" or "ADAT Clock" mode) digital
samples are received from the S/PDIF and/or ADAT receive core.
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 core. The external frequency is calculated through
counting samples in a given period. The reference clock to the CS2100 is then generated based on
the reception of these samples.
The external frequency is calculated through counting samples in a given period. The
reference clock to the Fractional-N Clock Multiplier is then generated based on this
external stream. If this stream becomes invalid, the timer event will fire to ensure that
valid master clock generation continues regardless of cable unplugs etc.
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 the transition between these clocks are relatively seamless. Additionally efforts are also
made to try and keep the jitter on the reference clock as low as possibly, regardless of activity
level of the Clock Gen core. The is achieved though the use of port times to schedule pin toggling
rather than directly outputting to the port.
This core gets clock selection Get/Set commands from Endpoint 0 via the ``c_clk_ctl``
The Clock Gen core gets clock selection Get/Set commands from Endpoint 0 via the ``c_clk_ctl``
channel. This core also records the validity of external clocks, which is also queried
through the same channel from Endpoint 0.
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 core can also cause the Decouple core to
request an interrupt packet on change of clock validity. This functionality is based on the Audio
Class 2.0 status/interrupt endpoint feature.
This core also can cause the decouple core to request an interrupt packet on change of
clock validity. This functionality is based on the Audio Class 2.0 status/interrupt endpoint
feature.
.. note::
When running in Synchronous mode external digital input streams are currently not supported.
Such a feature would require sample-rate conversion to covert from the S/PDIF or ADAT clock
domain to the USB host clock domain. As such this core is not used in a Synchronous mode device.

27
lib_xua/doc/rst/sw_detail.rst
View File

@@ -1,27 +0,0 @@
Implementation Detail
---------------------
This section describes the software architecture of a USB Audio device implemented using `lib_xua`, it's dependancies and other supporting libraries.
This section will now examine the operation of these components in further detail.
.. toctree::
sw_audio
sw_spdif
..
sw_xud
sw_ep0
sw_audio
sw_mixer
sw_spdif_rx
sw_adat
sw_clocking
sw_midi
sw_pdm
sw_resource
..

185
lib_xua/doc/rst/sw_ep0.rst
View File

@@ -19,7 +19,7 @@ During the enumeration process the host will issue various commands to the devic
The endpoint 0 code runs in its own core and follows a similar format to that of the USB Device examples in `lib_xud` (i.e. Example HID Mouse Demo). That is, a call is made to ``USB_GetSetupPacket()`` to receive a command from the host. This populates a ``USB_SetupPacket_t`` structure, which is then parsed.
There are many mandatory requests that a USB Device must support as required by the USB Specification. Since these are required for all devices in order to function a
``USB_StandardRequests()`` function is provided (see ``module_usb_device``) which implements all of these requests. This includes the following items:
``USB_StandardRequests()`` function is provided (see ``xud_device.xc``) which implements all of these requests. This includes the following items:
- Requests for standard descriptors (Device descriptor, configuration descriptor etc) and string descriptors
- USB GET/SET INTERFACE requests
@@ -28,8 +28,8 @@ There are many mandatory requests that a USB Device must support as required by
For more information and full documentation, including full worked examples of simple devices, please refer to `lib_xud`.
The ``USB_StandardRequests()`` function takes the devices various descriptors as parameters, these are passed from data structures found in the ``descriptors.h`` file.
These data structures are fully customised based on the how the design is configured using various defines (see :ref:`sec_custom_defines_api`).
The ``USB_StandardRequests()`` function takes the devices various descriptors as parameters, these are passed from data structures found in the ``xud_ep0_descriptors.h`` file.
These data structures are fully customised based on the how the design is configured using various defines.
The ``USB_StandardRequests()`` functions returns a ``XUD_Result_t``. ``XUD_RESULT_OKAY`` indicates that the request was fully handled without error and no further action is required
- The device should move to receiving the next request from the host (via ``USB_GetSetupPacket()``).
@@ -38,16 +38,16 @@ The function returns ``XUD_RES_ERR`` if the request was not recognised by the ``
The function may also return ``XUD_RES_RST`` if a bus-reset has been issued onto the bus by the host and communicated from XUD to Endpoint 0.
Since the ``USB_StandardRequests()`` function STALLs an unknown request, the endpoint 0 code must parse the ``USB_SetupPacket_t`` structure to handle device specific requests and then calling ``USB_StandardRequests()`` as required. This is described next.
Since the ``USB_StandardRequests()`` function STALLs an unknown request, the endpoint 0 code must first parse the ``USB_SetupPacket_t`` structure to handle device specific requests and then call ``USB_StandardRequests()`` as required.
Over-riding Standard Requests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The USB Audio design "over-rides" some of the requests handled by ``USB_StandardRequests()``, for example it uses the SET_INTERFACE request to indicate it if the host is streaming audio to the device. In this case the setup packet is parsed, the relevant action taken, the ``USB_StandardRequests()`` is called to handle the response to the host etc.
The USB Audio design "over-rides" some of the requests handled by ``USB_StandardRequests()``, for example it uses the SET_INTERFACE request to indicate if the host is streaming audio to the device. In this case the setup packet is parsed, the relevant action taken, the ``USB_StandardRequests()`` is still called to handle the response to the host.
Class Requests
~~~~~~~~~~~~~~
Before making the call to ``USB_StandardRequests()`` the setup packet is parsed for Class requests. These are handled in functions such as ``AudioClasRequests_2()``, ``AudioClassRequests_2``, ``DFUDeviceRequests()`` etc depending on the type of request.
Before making the call to ``USB_StandardRequests()`` the setup packet is parsed for Class requests. These are handled in functions such as ``AudioClassRequests_1()``, ``AudioClassRequests_2``, ``DFUDeviceRequests()`` etc depending on the type of request.
Any device specific requests are handled - in this case Audio Class, MIDI class, DFU requests etc.
@@ -60,14 +60,14 @@ When the host issues an audio request (e.g. sample rate or volume change), it se
Note, Audio Class 1.0 Sample rate changes are send to the relevant endpoint, rather than the interface - this is handled as a special case in he endpoint 0 request parsing where ``AudioEndpointRequests_1()`` is called.
The ``AudioClassRequests_X()`` functions parses the request further in order to ascertain the correct audio operation to execute.
The ``AudioClassRequests_X()`` functions further parses the request in order to ascertain the correct audio operation to execute.
Audio Request: Set Sample Rate
++++++++++++++++++++++++++++++
The ``AudioClassRequests_2()`` function parses the passed ``USB_SetupPacket_t`` structure for a ``CUR`` request of type ``SAM_FREQ_CNTROL`` to a Clock Unit in the devices topology (as described in the devices descriptors).
The ``AudioClassRequests_2()`` function parses the passed ``USB_SetupPacket_t`` structure for a ``CUR`` request of type ``SAM_FREQ_CONTROL`` to a Clock Unit in the devices topology (as described in the devices descriptors).
The new sample frequency is extracted and passed via channel to the rest of the design - through the buffering code and eventually to the Audio IO/I2S core. The ``AudioClassRequests_2()`` function waits for a handshake to propagate back though the system before signalling to the host that the request has completed successfully. Note, during this time the USB library is NAKing the host essentially holding off further traffic/requests until the sample-rate change is fully complete.
The new sample frequency is extracted and passed via channel to the rest of the design - through the buffering code and eventually to the Audio Hub (I2S) core. The ``AudioClassRequests_2()`` function waits for a handshake to propagate back through the system before signalling to the host that the request has completed successfully. Note, during this time the USB library is NAKing the host essentially holding off further traffic/requests until the sample-rate change is fully complete.
.. _usb_audio_sec_audio-requ-volume:
@@ -83,7 +83,7 @@ When changing the volume, Endpoint 0 applies the master volume and
channel volume, producing a single volume value for each channel.
These are stored in the array.
The volume will either be handled by the ``decoupler`` core or the mixer
The volume will either be handled by the ``decouple`` core or the mixer
component (if the mixer component is used). Handling the volume in the
mixer gives the decoupler more performance to handle more channels.
@@ -97,7 +97,8 @@ the array (ordering between writes and reads is unimportant in this
case). Inline assembly is used by the decoupler core to access
the array, avoiding the parallel usage checks of XC.
If volume control is implemented in the mixer, Endpoint 0 sends a mixer command to the mixer to change the volume. Mixer commands
If volume control is implemented in the mixer, Endpoint 0 sends a mixer command
to the mixer to change the volume. Mixer commands
are described in :ref:`usb_audio_sec_mixer`.
Audio Endpoints (Endpoint Buffer and Decoupler)
@@ -107,18 +108,18 @@ Endpoint Buffer
~~~~~~~~~~~~~~~
All endpoints other that Endpoint 0 are handled in one core. This
core is implemented in the file ``usb_buffer.xc``. This core is communicates directly with the XUD library.
core is implemented in the file ``ep_buffer.xc``. This core communicates directly with the XUD library.
The USB buffer core is also responsible for feedback calculation based on USB Start Of Frame
(SOF) notification and reads from the port counter of a port connected to the master clock.
Decoupler
~~~~~~~~~
Decouple
~~~~~~~~
The decoupler supplies the USB buffering core with buffers to
transmit/receive audio data to/from the host. It marshals these buffers into
FIFOs. The data from the FIFOs are then sent over XC channels to
other parts of the system as they need it. This core also
other parts of the system as they need it. In asynchronous mode this core also
determines the size of each packet of audio sent to the host (thus
matching the audio rate to the USB packet rate). The decoupler is
implemented in the file ``decouple.xc``.
@@ -133,22 +134,22 @@ For data going from the device to the host the following scheme is
used:
#. The decouple core receives samples from the audio core and
#. The Decouple core receives samples from the Audio Hub core and
puts them into a FIFO. This FIFO is split into packets when data is
entered into it. Packets are stored in a format consisting of their
length in bytes followed by the data.
#. When the buffer cores needs a buffer to send to the XUD core
(after sending the previous buffer), the decouple core is
#. When the Endpoint Buffer core needs a buffer to send to the XUD core
(after sending the previous buffer), the Decouple core is
signalled (via a shared memory flag).
#. Upon this signal from the buffering core, the decouple core
passes the next packet from the FIFO to the buffer core. It also
signals to the XUD library that the buffer core is able to send a
#. Upon this signal from the Endpoint Buffer core, the Decouple core
passes the next packet from the FIFO to the Endpoint Buffer core. It also
signals to the XUD library that the Endpoint Buffer core is able to send a
packet.
#. When the buffer core has sent this buffer, it signals to the
decouple that the buffer has been sent and the decouple core
#. When the Endpoint Buffer core has sent this buffer, it signals to the
Decouple core that the buffer has been sent and the Decouple core
moves the read pointer of the FIFO.
@@ -156,47 +157,45 @@ For data going from the host to the device the following scheme is
used:
#. The decouple core passes a pointer to the buffering core
#. The Decouple core passes a pointer to the Endpoint Buffer core
pointing into a FIFO of data and signals to the XUD library that
the buffering core is ready to receive.
the Endpoint Buffer core is ready to receive.
#. The buffering core then reads a USB packet into the FIFO and
signals to the decoupler that the packet has been read.
#. The Endpoint Buffer core then reads a USB packet into the FIFO and
signals to the Decouple core that the packet has been read.
#. Upon receiving this signal the decoupler core updates the
#. Upon receiving this signal the Decouple core updates the
write pointer of the FIFO and provides a new pointer to the
buffering core to fill.
Endpoint Buffer core to fill.
#. Upon request from the audio core, the decoupler core sends
samples to the audio core by reading samples out of the FIFO.
#. Upon request from the Audio Hub core, the Decouple core sends
samples to the Audio Hub core by reading samples out of the FIFO.
Decoupler/Audio Core interaction
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To meet timing requirements of the audio system, the decoupler
To meet timing requirements of the audio system (i.e Audio Hub/Mixer), the Decoupler
core must respond to requests from the audio system to
send/receive samples immediately. An interrupt handler
is set up in the decoupler core to do this. The interrupt handler
is implemented in the function ``handle_audio_request``.
The audio system sends a word over a channel to the decouple core to
request sample transfer (using the build in outuint function).
request sample transfer (using the build in ``outuint()`` function).
The receipt of this word in the channel
causes the ``handle_audio_request`` interrupt to fire.
The first operation the interrupt handler does is to send back a word
acknowledging the request (if there was a change of sample frequency
The first operation the interrupt handler does (once it inputs the word that triggered the interrupt)
is to send back a word acknowledging the request (if there was a change of sample frequency
a control token would instead be sent---the audio system uses a testct()
to inspect for this case).
Sample transfer may now take place. First the audio subsystem transfers
samples destined for the host, then the decouple core sends
samples from the host to device. These transfers always take place
Sample transfer may now take place. First the Decouple core sends samples from host to device then the
audio subsystem transfers samples destined for the host. These transfers always take place
in channel count sized chunks (i.e. ``NUM_USB_CHAN_OUT`` and
``NUM_USB_CHAN_IN``). That is, if the device has 10 output channels and
8 input channels, 10 samples are sent from the decouple core and 8 received
every interrupt.
``NUM_USB_CHAN_IN``). That is, if the device has 10 output channels and 8 input channels,
10 samples are sent from the decouple core and 8 received every interrupt.
The complete communication scheme is shown in the table below (for non sample
frequency change case):
@@ -237,7 +236,7 @@ frequency change case):
+-----------------+-----------------+-----------------------------------------+
.. note::
The request and acknowledgement sent to/from Decouple to the Audio System is an "output underflow" sample
The request and acknowledgement sent to/from the Decouple core to the Audio System is an "output underflow" sample
value. If in PCM mode it will be 0, in DSD mode it will be DSD silence.
This allows the buffering system to output a suitable underflow value without knowing the format of the stream
(this is especially advantageous in the DSD over PCM (DoP) case)
@@ -245,47 +244,54 @@ frequency change case):
Asynchronous Feedback
+++++++++++++++++++++
The device uses a feedback endpoint to report the rate at which
When built to operate in Asynchronous mode the device uses a feedback endpoint to report the rate at which
audio is output/input to/from external audio interfaces/devices. This feedback is in accordance with
the *USB 2.0 Specification*.
the *USB 2.0 Specification*. This calculated feedback value is also used to size packets to the host.
This asynchronous clocking scheme means that the device is the clocking master than therefore
means a high-quality local master clock source can be used.
This asynchronous clocking scheme means that the device is the clock master and therefore
a high-quality local master clock or a digital input stream can be used as the clock source.
After each received USB SOF token, the buffering core takes a time-stamp from a port clocked off
After each received USB Start Of Frame (SOF) token, the buffering core takes a time-stamp from a port clocked off
the master clock. By subtracting the time-stamp taken at the previous SOF, the number of master
clock ticks since the last SOF is calculated. From this the number of samples (as a fixed
point number) between SOFs can be calculated.
This count is aggregated over 128 SOFs and used as a basis for the feedback value.
point number) between SOFs can be calculated. This count is aggregated over 128 SOFs and used as a
basis for the feedback value.
The sending of feedback to the host is also handled in the USB buffering core via an explicit feedback
IN endpoint. If both input and output is enabled then the feedback is implicit based on the audio stream
sent to the host.
The sending of feedback to the host is also handled in the Endpoint Buffer core via an explicit
feedback IN endpoint.
If both input and output is enabled then the feedback can be implicit based on the audio stream
sent to the host. In practice this an explicit feedback endpoint is normally used due to restrictions
in Microsoft Windows operating systems (see ``UAC_FORCE_FEEDBACK_EP``).
USB Rate Control
++++++++++++++++
.. _usb_audio_sec_usb-rate-control:
The Audio core must consume data from USB
and provide data to USB at the correct rate for the selected sample
frequency. The *USB 2.0 Specification* states that the maximum
variation on USB packets can be +/- 1 sample per USB frame. USB
frames are sent at 8kHz, so on average for 48kHz each packet
contains six samples per channel. The device uses Asynchronous mode,
so the audio clock may drift and run faster or slower than the
host. Hence, if the audio clock is slightly fast, the device may
occasionally input/output seven samples rather than six. Alternatively,
it may be slightly slow and input/output five samples rather than six.
:ref:`usb_audio_samples_per_packet` shows the allowed number of samples
per packet for each example audio frequency.
The device must consume data from USB host and provide data to USB host at the correct rate for the
selected sample frequency. When running in asynchronous mode the *USB 2.0 Specification* states
that the maximum variation on USB packets can be +/- 1 sample per USB frame (Synchronous mode
mandates no variation other than that required to match a sample rate that doesn't cleanly divide
the USB SOF period e.g. 44.1kHz)
See USB Device Class Definition for Audio Data Formats v2.0 section 2.3.1.1
for full details.
High-speed USB frames are sent at 8kHz, so on average for 48kHz each packet contains six samples
per channel.
When running in Asynchronous mode, so the audio clock may drift and run faster or slower than the
host. Hence, if the audio clock is slightly fast, the device may occasionally input/output seven
samples rather than six. Alternatively, it may be slightly slow and input/output five samples rather
than six. :ref:`usb_audio_samples_per_packet` shows the allowed number of samples per packet for
each example audio frequency in Asynchronous mode.
When running in Synchronous mode the audio clock is synchronised to the USB host SOF clock. Hence,
at 48kHz the device always expects six samples from, and always sends size samples to, the host.
See USB Device Class Definition for Audio Data Formats v2.0 section 2.3.1.1 for full details.
.. _usb_audio_samples_per_packet:
.. table:: Allowed samples per packet
.. table:: Allowed samples per packet in Async mode
+-----------------+-------------+-------------+
| Frequency (kHz) | Min Packet | Max Packet |
@@ -304,46 +310,11 @@ for full details.
+-----------------+-------------+-------------+
To implement this control, the decoupler core uses the feedback
value calculated in the buffering core. This value is used to
work out the size of the next packet it will insert into the audio
FIFO.
To implement this control, the Decoupler core uses the feedback value calculated in the EP Buffering
core. This value is used to work out the size of the next packet it will insert into the audio FIFO.
.. note::
In Synchronous mode the same system is used, but the feedback value simply uses a fixed value
rather than one derived from the master clock port.
.. .. _fig_usb_devices:
.. .. table:: USB interfaces presented to host
.. :class: center
..
.. +-----------------------+----------------------------------+
.. | **Mode** | **Interfaces** |
.. +=======================+==================================+
.. | Application mode | | Audio Class 2/Audio Class 1 |
.. | | | DFU Class 1.1 |
.. | | | MIDI Device Class 1.0 |
.. +-----------------------+----------------------------------+
.. | DFU mode | DFU Class 1.1 |
.. +-----------------------+----------------------------------+
.. The device initially starts in Application mode.
.. :ref:`usb_audio_sec_dfu` describes how DFU mode is used. The
.. audio device class (1 or 2) is set at compile time---see :ref:`usb_audio_sec_custom_defines_api`.
.. Reset
.. ~~~~~
.. On receiving a reset request, three steps occur:
.. #. Depending on the DFU state, the device may be set into DFU
mode.
.. #. A XUD function is called to reset the endpoint structure and receive the new bus speed.
.. _usb_audio_sec_audio-requ-sett:

1
lib_xua/doc/rst/sw_hid.rst
View File

@@ -45,4 +45,3 @@ On each HID report request from the host the function ``Vendor_ReadHidButtons(un
Since the ``Vendor_ReadHidButtons()`` function is called from the ``buffer`` logical core, care should be taken not to add to much execution time to this function since this could cause issues with servicing other endpoints.
For a full example please see the HID section in :ref:`usb_audio_sec_l1_audio_sw`.

9
lib_xua/doc/rst/sw_iap.rst
View File

@@ -1,9 +0,0 @@
Apple MFi compatibility
-----------------------
XMOS devices are capable of operating with Apple iPod, iPhone, and iPad devices
that feature USB host support. Information regarding this functionality is
protected by the Made For iPod (MFi) program and associated licensing.
Please contact XMOS for details and further documentation.

14
lib_xua/doc/rst/sw_midi.rst
View File

@@ -1,7 +1,13 @@
|newpage|
MIDI
----
The MIDI driver implements a 31250 baud UART input and output. On receiving 32-bit USB MIDI events
from the ``buffer`` core, it parses these and translates them to 8-bit MIDI messages which are sent
over UART. Similarly, incoming 8-bit MIDI messages are aggregated into 32-bit USB-MIDI events an
passed on to the ``buffer`` core. The MIDI core is implemented in the file ``usb_midi.xc``.
The MIDI core implements a 31250 baud UART for both input and output. On receiving 32-bit USB MIDI events
from the Endpoint Buffer core, it parses these and translates them to 8-bit MIDI messages which are sent
over UART. Similarly, incoming 8-bit MIDI messages are aggregated into 32-bit USB-MIDI events and
passed on to the Endpoint Buffer core. The MIDI core is implemented in the file ``usb_midi.xc``.
The Endpoint Buffer core implements the two Bulk endpoints (one In and one Out) as well as interacting
with small, shared-memory, FIFOs for each endpoint.

138
lib_xua/doc/rst/sw_mixer.rst
View File

@@ -3,50 +3,53 @@
Digital Mixer
-------------
The mixer core(s) take outgoing audio from the decoupler core and incoming
audio from the audio driver core. It then applies the volume to each
channel and passes incoming audio on to the decoupler and outgoing
audio to the audio driver. 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 core(s) take outgoing audio from the Decouple core and incoming audio from the Audio Hub
core. 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 two cores 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 moves
down to two mixes when switching to a higher rate.
The mixer takes (up to) two cores 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 decoupler core.
* The inputs from the audio interface on the device---these
samples come from the audio driver.
* The USB outputs from the host---these samples come from the Decouple core.
* The inputs from the audio interfaces on the device---these samples come from the Audio Hub core
and includes samples from digital input streams.
Since the sum of these inputs may be more then the 18 possible mix
inputs to each mixer, there is a mapping from all the
possible inputs to the mixer inputs.
Since the sum of these inputs may be more then 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
output destinations:
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 decoupler core.
* The USB inputs to the host---these samples are sent to the Decouple core.
* The outputs to the audio interface on the device---these samples
are sent to the audio driver.
* The outputs to the audio interface on the device---these samples are sent to the Audio Hub
core
For each possible output, a mapping exists to tell the mixer what its
source is. The possible sources are the USB outputs from the host, the
inputs for the audio interface or the outputs from the mixer units.
For each possible output from the device, a mapping exists to inform the mixer what it's source is.
The possible sources are the output from the USB host, the inputs from the Audio Hub core or the
outputs from the mixes.
As mentioned in :ref:`usb_audio_sec_audio-requ-volume`, the mixer can also
handle volume setting. If the mixer is configured to handle volume but
the number of mixes is set to zero (so the component is solely doing
volume setting) then the component will use only one core.
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 :ref:`usb_audio_sec_audio-requ-volume`, the mixer can also handle processing or
volume controls. If the mixer is configured to handle volume but the number of mixes is set to zero
(such that the core is solely doing volume setting) then the component will use only one core. This
is sometimes a useful configuration for large channel count devices.
Control
~~~~~~~
The mixers can receive the following control commands from the Endpoint 0 core via a channel:
The mixers can receive the control commands from the host via USB Control Requests to Endpoint 0.
The Endpoint 0 core relays these to the Mixer cores(s) via a channel (``c_mix_ctl``). These commands
are described in :ref:`table_mixer_commands`.
.. _table_mixer_commands:
.. list-table:: Mixer Component Commands
:header-rows: 1
@@ -79,46 +82,49 @@ Host Control
~~~~~~~~~~~~
The mixer can be controlled from a host PC by sending requests to Endpoint 0. XMOS provides a simple
command line based sample application demonstrating how the mixer can be controlled.
command line based sample application demonstrating how the mixer can be controlled. This is
intended as an example of how you might add mixer control to your own control application. It is not
intended to be exposed to end users.
For details, consult the README file in the host_usb_mixer_control directory.
The main requirements of this control are to
The main requirements of this control utility are to
* Set the mapping of input channels into the mixer
* Set the coefficients for each mixer output of each input
* Set the coefficients for each mixer output for each input
* Set the mapping for physical outputs which can either come
directly from the inputs or via the mixer.
There is enough flexibility within this configuration that there will often
be multiple ways of creating the required solution.
.. note::
Whilst using the XMOS Host control example application, consider setting the
mixer to perform a loop-back from analogue inputs 1 and 2 to analogue
outputs 1 and 2.
The flexibility within this configuration space us such that there is often multiple ways
of producing the desired result. Product developers may only want to expose a subset of this
functionality to their end users.
First consider the inputs to the mixer::
Whilst using the XMOS Host control example application, consider the example of setting the
mixer to perform a loop-back from analogue inputs 1 and 2 to analogue outputs 1 and 2.
Firstly consider the inputs to the mixer. The following will displays which channels are mapped
to which mixer inputs::
./xmos_mixer --display-aud-channel-map 0
displays which channels are mapped to which mixer inputs::
The following command will displays which channels could possibly be mapped to mixer inputs. Notice
that analogue inputs 1 and 2 are on mixer inputs 10 and 11::
./xmos_mixer --display-aud-channel-map-sources 0
./xmos_mixer --display-aud-channel-map-sources 0
displays which channels could possibly be mapped to mixer inputs. Notice
that analogue inputs 1 and 2 are on mixer inputs 10 and 11.
Now examine the audio output mapping::
Now examine the audio output mapping using the following command::
./xmos_mixer --display-aud-channel-map 0
displays which channels are mapped to which outputs. By default all
This displays which channels are mapped to which outputs. By default all
of these bypass the mixer. We can also see what all the possible
mappings are::
mappings are with the following command::
./xmos_mixer --display-aud-channel-map-sources 0
So now map the first two mixer outputs to physical outputs 1 and 2::
We will now map the first two mixer outputs to physical outputs 1 and 2::
./xmos_mixer --set-aud-channel-map 0 26
./xmos_mixer --set-aud-channel-map 1 27
@@ -127,13 +133,12 @@ You can confirm the effect of this by re-checking the map::
./xmos_mixer --display-aud-channel-map 0
This now makes analogue outputs 1 and 2 come from the mixer, rather
than directly from USB. However the mixer is still mapped to pass
the USB channels through to the outputs, so there will still be no
functional change yet.
This now derives analogue outputs 1 and 2 from the mixer, rather than directly from USB. However,
since the mixer is still mapped to pass the USB channels through to the outputs there will be no
functional change.
The mixer nodes need to be individually set. They can be displayed
with::
with the following command::
./xmos_mixer --display-mixer-nodes 0
@@ -150,32 +155,25 @@ At the same time, the original mixer outputs can be muted::
Now audio inputs on analogue 1/2 should be heard on outputs 1/2.
As mentioned above, the flexibility of the mixer is such that there
will be multiple ways to create a particular mix. Another option to
create the same routing would be to change the mixer sources such that
mixer 1/2 outputs come from the analogue inputs.
As mentioned above, the flexibility of the mixer is such that there will be multiple ways to create
a particular mix. Another option to create the same routing would be to change the mixer sources
such that mixer 1/2 outputs come from the analogue inputs.
To demonstrate this, firstly undo the changes above::
To demonstrate this, firstly undo the changes above (or simply reset the device)::
./xmos_mixer --set-value 0 80 -inf
./xmos_mixer --set-value 0 89 -inf
./xmos_mixer --set-value 0 0 0
./xmos_mixer --set-value 0 9 0
The mixer should now have the default values. The sources for mixer
1/2 can now be changed::
The mixer should now have the default values. The sources for mixer 1/2 can now be changed::
./xmos_mixer --set-mixer-source 0 0 10
./xmos_mixer --set-mixer-source 0 1 11
If you rerun::
./xmos_mixer --display-mixer-nodes 0
the first column now has AUD - Analogue 1 and 2 rather than DAW (Digital Audio Workstation i.e. the
host) - Analogue 1 and 2 confirming the new mapping. Again, by playing audio into analogue inputs
1/2 this can be heard looped through to analogue outputs 1/2.
If you re-run the following command then the first column now has "AUD - Analogue 1 and 2" rather
than "DAW (Digital Audio Workstation i.e. the host) - Analogue 1 and 2" confirming the new mapping.
Again, by playing audio into analogue inputs 1/2 this can be heard looped through to analogue outputs 1/2::
./xmos_mixer --display-mixer-nodes 0

49
lib_xua/doc/rst/sw_pdm.rst
View File

@@ -1,11 +1,10 @@
|newpage|
PDM Microphones
---------------
Overview of PDM implemention
----------------------------
The design is capable of integrating PDM microphones. The PDM stream from the microphones is converted
to PCM and output to the host via USB.
The XMOS USB Audio Reference Design firmware 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 with efficient decimation
@@ -19,9 +18,6 @@ The following components of the library are used:
* PDM interface
* Four channel decimators
|newpage|
Up to sixteen PDM microphones can be attached to each high channel count PDM interface (``mic_array_pdm_rx()``).
One to four processing tasks, ``mic_array_decimate_to_pcm_4ch()``, each process up to four channels. For 1-4
channels the library requires two logical cores:
@@ -40,35 +36,40 @@ for 5-8 channels three logical cores are required, as shown below:
Five to eight count PDM interface
The left most task, ``mic_array_pdm_rx()``, samples up to 8 microphones and filters the data to provide up to
eight 384 KHz data streams, split in two streams of four channels. The processing thread
decimates the signal to a user chosen sample rate (one of 48, 24, 16, 12 or 8 KHz).
eight 384kHz data streams, split into two streams of four channels. The processing thread
decimates the signal to a user chosen sample rate (one of 48, 24, 16, 12 or 8kHz).
More channels can be supported by increasing the number of cores dedicated to the PDM tasks. However, the current
PDM mic integration into USB Audio limits itself to 8.
PDM mic integration into ``lib_xua`` is limited to 8.
After the decimation to the output sample-rate various other steps take place e.g. DC offset elimination, gain correction
and compensation etc. Please refer to ``lib_mic_array`` documention for further implementation detail and complete feature set.
and compensation etc. Please refer to the documentation provided with ``lib_mic_array`` for further
implementation detail and complete feature set.
PDM Microphone Hardware Characteristics
+++++++++++++++++++++++++++++++++++++++
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The PDM microphones need a *clock input* and provide the PDM signal on a *data output*. All PDM microphones share the same
clock signal (buffered on the PCB as appropriate), and output onto eight data wires that are connected to a single 8-bit port:
The PDM microphones require a *clock input* and provide the PDM signal on a *data output*. All of
the PDM microphones must share the same clock signal (buffered on the PCB as appropriate), and
output onto eight data wires that are connected to a single 8-bit port:
.. _pdm_wire_table:
.. list-table:: PDM microphone data and signal wires
:class: vertical-borders horizontal-borders
* - *CLOCK*
:header-rows: 1
* - Signal
- Description
* - CLOCK
- Clock line, the PDM clock the used by the microphones to
drive the data out.
* - *DQ_PDM*
* - DQ_PDM
- The data from the PDM microphones on an 8 bit port.
The only port that is passed into ``lib_mic_array`` is the 8-bit data port. The library
assumes that the input port is clocked using the PDM clock and requires no knowlege of the
assumes that the input port is clocked using the PDM clock and requires no knowledge of the
PDM clock source.
The input clock for the microphones can be generated in a multitude of
@@ -76,14 +77,14 @@ ways. For example, a 3.072MHz clock can be generated on the board, or the xCORE
divide down 12.288 MHz master clock. Or, if clock accuracy is not important, the internal 100 MHz
reference can be divided down to provide an approximate clock.
Integration of PDM Microphones into USB Audio
+++++++++++++++++++++++++++++++++++++++++++++
Usage & Integration
~~~~~~~~~~~~~~~~~~~
A PDM microphone wrapper is called from ``main()`` and takes one channel argument connecting it to the rest of the system:
``pcm_pdm_mic(c_pdm_pcm);``
The implemetation of this function can be found in the file ``pcm_pdm_mics.xc``.
The implementation of this function can be found in the file ``pcm_pdm_mics.xc``.
The first job of this function is to configure the ports/clocking for the microphones, this divides the external
audio master clock input (on port ``p_mclk``) and outputs the divided clock to the microphones via the ``p_pdm_clk`` port::
@@ -93,7 +94,7 @@ audio master clock input (on port ``p_mclk``) and outputs the divided clock to t
configure_in_port(p_pdm_mics, pdmclk);
start_clock(pdmclk);
It then runs the various cores required for the PDM interface and PDM to PCM conversion as discussed previously::
It then runs the various cores required for the PDM interface and PDM to PCM conversion as previously discussed::
par
{
@@ -107,7 +108,7 @@ The ``pdm_process()`` task includes the main integration code, it takes audio fr
it, performs optional local processing and outputs it to the audio driver (TDM/I2S core).
This function simply makes a call to ``mic_array_get_next_time_domain_frame()`` in order to get a frame of PCM audio
from the microphones. It then waits for an request for audio samples from the audio/I2S/TDM core via a channel and
from the microphones. It then waits for an request for audio samples from the Audio Hub core via a channel and
sends the frame of audio back over this channel.
Note, it is assumed that the system shares a global master-clock, therefore no additional buffering or rate-matching/conversion

27
lib_xua/doc/rst/sw_resource.rst
View File

@@ -1,24 +1,26 @@
|newpage|
.. _usb_audio_sec_resource_usage:
Resource Usage
--------------
The following table details the resource usage of each
component of the reference design software.
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.
.. table:: Resource Usage
+---------------+---------------+---------------------+-------------------------------------+
| Component | Cores | Memory (KB) | Ports |
+===============+===============+=====================+=====================================+
| XUD library | 1 | 9 (6 code) | ULPI ports |
| XUD library | 1 | 9 (6 code) | USB ports |
| | | | |
+---------------+---------------+---------------------+-------------------------------------+
| Endpoint 0 | 1 | 17.5 (10.5 code) | none |
+---------------+---------------+---------------------+-------------------------------------+
| USB Buffering | 1 | 22.5 (1 code) | none |
| USB Buffering | 2 | 22.5 (1 code) | 1 x n bit port |
+---------------+---------------+---------------------+-------------------------------------+
| Audio driver | 1 | 8.5 (6 code) | See :ref:`usb_audio_sec_audio` |
| Audio Hub | 1 | 8.5 (6 code) | See :ref:`usb_audio_sec_audio` |
+---------------+---------------+---------------------+-------------------------------------+
| S/PDIF Tx | 1 | 3.5 (2 code) | 1 x 1 bit port |
+---------------+---------------+---------------------+-------------------------------------+
@@ -26,18 +28,18 @@ component of the reference design software.
+---------------+---------------+---------------------+-------------------------------------+
| ADAT Rx | 1 | 3.2 (3.2 code) | 1 x 1 bit port |
+---------------+---------------+---------------------+-------------------------------------+
| Midi | 1 | 6.5 (1.5 code) | 2 x 1 bit ports |
| MIDI | 1 | 6.5 (1.5 code) | 2 x 1 bit ports |
+---------------+---------------+---------------------+-------------------------------------+
| Mixer | 2 | 8.7 (6.5 code) | |
| Mixer | (up to) 2 | 8.7 (6.5 code) | |
+---------------+---------------+---------------------+-------------------------------------+
| ClockGen | 1 | 2.5 (2.4 code) | |
+---------------+---------------+---------------------+-------------------------------------+
.. note::
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.
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.
.. note::
@@ -46,6 +48,5 @@ component of the reference design software.
.. note::
The ULPI ports are a fixed set of ports on the L-Series
device. When using these ports, other ports are
unavailable when ULPI is active. See the `XS1-L Hardware Design Checklist <http://www.xmos.com/published/xs1lcheck>`_ for further details.
Unlike other interfaces, since the USB PHY is internal the USB ports are a fixed set of ports
and cannot be modified. See ``lib_xud`` documentation for full details.

16
lib_xua/doc/rst/sw_spdif.rst
View File

@@ -1,3 +1,6 @@
|newpage|
S/PDIF Transmit
...............
@@ -79,6 +82,7 @@ The following protocol is used on the channel:
* - ``...``
-
This communication is wrapped up in the API functions provided by ``lib_spdif``.
Output stream structure
@@ -126,15 +130,15 @@ indicates sampling frequency as shown in :ref:`usb_audio_spdif_sample_bits`.
* - Frequency (kHz)
- n
* - 44.1
- 0
- 0x0
* - 48
- 2
- 0x2
* - 88.2
- 8
- 0x8
* - 96
- A
- 0xA
* - 176.4
- C
- 0xC
* - 192
- E
- 0xE

33
lib_xua/doc/rst/sw_spdif_rx.rst
View File

@@ -1,17 +1,18 @@
|newpage|
S/PDIF Receive
---------------
XMOS devices can support S/PDIF receive up to 192kHz.
XMOS devices can support S/PDIF receive up to 192kHz - see ``lib_spdif`` for full specifications.
The S/PDIF receiver module uses a clockblock and a buffered one-bit port.
The S/PDIF receiver module uses a clock-block and a buffered one-bit port.
The clock-block is divided of a 100 MHz reference clock. The one bit port is buffered to 4-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.
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:
The S/PDIF receive function never returns. The 32-bit value from the channel input comprises:
.. list-table:: S/PDIF RX Word Structure
:header-rows: 1
@@ -41,16 +42,22 @@ The tag has one of three values:
* - FRAME\_Z
- Sample on channel 0 (Left), and the first sample of a frame; can be used if the user bits need to be reconstructed.
See S/PDIF specification for further details on format, user bits etc.
See S/PDIF, IEC 60958-3:2006, specification for further details on format, user bits etc.
Usage and Integration
+++++++++++++++++++++
Since S/PDIF is a digital steam the devices master clock must be syncronised to it. This is typically
done with an external fractional-n multipier. See `Clock Recovery` (:ref:`usb_audio_sec_clock_recovery`)
Since S/PDIF is a digital steam the devices master clock must be synchronised to it. This is typically
done with an external device. See `Clock Recovery` (:ref:`usb_audio_sec_clock_recovery`).
The S/PDIF receive function communicates with the ``clockGen`` component with passes audio data to the
audio driver and handles locking to the S/PDIF clock source if required (see External Clock Recovery).
.. note::
Due to the requirement for this clock recovery S/PDIF receive can only be used in Asynchronous
mode.
The S/PDIF receive function communicates with the Clock Gen core, which in turn passes audio data to the
Audio Hub core. The Clock Gen core also handles locking to the S/PDIF clock source
(see :ref:`usb_audio_sec_clock_recovery`).
Ideally the parity of each word/sample received should be checked. This is done using the built in
``crc32`` function (see ``xs1.h``):
@@ -62,8 +69,7 @@ Ideally the parity of each word/sample received should be checked. This is done
If bad parity is detected the word/sample is ignored, otherwise the tag is inspected for channel
(i.e. left or right) and the sample stored.
The following code snippet illustrates how the output of the S/PDIF receive component could be used::
The following code snippet illustrates how the output of the S/PDIF receive component could is used::
while(1)
{
@@ -90,6 +96,5 @@ The following code snippet illustrates how the output of the S/PDIF receive comp
}
}
The Clock Gen core stores samples in a small FIFO before they are communicated to the Audio Hub core.

2
lib_xua/doc/rst/sw_xud.rst
View File

@@ -1,4 +1,6 @@
|newpage|
XMOS USB Device (XUD) Library
.............................

167
lib_xua/doc/rst/using.rst
View File

@@ -1,11 +1,11 @@
Using lib_xud
-------------
This sections describes the basic usage of `lib_xud`. It provides a guide on how to program the USB Audio Devices using `lib_xud`.
Basic Usage
-----------
Reviewing application note AN00246 is highly recommended at this point.
This sections describes the basic usage of `lib_xua` and provides a guide on how to program USB Audio Devices.
Library structure
Library Structure
~~~~~~~~~~~~~~~~~
The code is split into several directories.
@@ -18,15 +18,17 @@ The code is split into several directories.
- MIDI I/O code
* - dfu
- Device Firmware Upgrade code
* - hid
- Human Interface Device code
Note, the midi and dfu directories are potential candidates for separate libs in their own right.
Including in a project
~~~~~~~~~~~~~~~~~~~~~~
Using in a Project
~~~~~~~~~~~~~~~~~~
All `lib_xua` functions can be accessed via the ``xua.h`` header filer::
All `lib_xua` functions can be accessed via the ``xua.h`` header file::
#include <xua.h>
@@ -34,109 +36,51 @@ It is also required to add ``lib_xua`` to the ``USED_MODULES`` field of your app
USED_MODULES = .. lib_xua ...
.. _sec_basic_usage_codeless:
Core hardware resources
~~~~~~~~~~~~~~~~~~~~~~~
"Codeless" Programming Model
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The user must declare and initialise relevant hardware resources (globally) and pass them to the relevant function of `lib_xua`.
Whilst it is possible to code a USB Audio device using the building blocks provided by `lib_xua`
it is realised that this might not be desirable for many classes of customers or products.
As an absolute minimum the following resources are required:
For instance, some users may not have a large software development experience and simply want to
customise some basic settings such as strings, sample-rates, channel-counts etc.
Others may want to fully customise the implementation - adding additional functionality such as
adding DSP or possibly only using a subset of the functions provided - just ``XUA_AudioHub``,
for example.
- A 1-bit port for audio master clock input
- A n-bit port for internal feedback calculation (typically a free, unused port is used e.g. `16B`)
- A clock-block, which will be clocked from the master clock input port
In addition, the large number of supported features can lead to a large number of tasks, hardware
resources, communication channels etc, requiring quite a lot of code to be authored for each product.
Example declaration of these resources might look as follows::
In order to cater for the former class of users, a "codeless" option is provided. Put simply, a file
``main.xc`` is provided which includes a pre-authored ``main()`` function along with all of the
required hardware resource declarations. Code is generated based on the options provided by the
developer in ``xua_conf.h``
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 */
Using this development model the user simply must include a ``xua_conf.h`` with their settings and
optional implementations of any 'user functions' as desired. This, along with an XN file for their
hardware platform, is all that is required to build a fully featured and functioning product. This
XN file should contain definitions of the ports used for the various ``lib_xua`` functionality,
see ::ref:`sec_options`.
.. note::
This development model also provides the benefit of a full and verified codebase as a basis for a product.
The `PORT_MCLK_IN` and `PORT_MCLK_COUNT` defintions are derived from the projects XN file
This behaviour described in this section is the default behaviour of `lib_xua`, to disable this please
set ``EXCLUDE_USB_AUDIO_MAIN`` to 1 in the application makefile or ``xua_conf.h`` and see
::ref:`sec_advanced_usage`.
Configuring lib_xua
~~~~~~~~~~~~~~~~~~~
The ``XUA_AudioHub()`` function requires an audio master clock input to clock the physical audio I/O. Less obvious is the reasoning for the ``XUA_Buffer()``
task having the same requirement - it is used for the USB feedback system and packet sizing.
Configuration of the various build time options of ``lib_xua`` is done via the optional header `xua_conf.h`.
To allow the build scripts to locate this file it should reside somewhere in the application `src` directory.
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::
Such build time options include audio class version, sample rates, channel counts etc. Please see
::ref:`sec_api` for full listings.
/* 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 needs some additional audio I/O,
I2S or SPDIF for example.
These should be passed into the various cores as required - see API and Features sections.
Running the core components
~~~~~~~~~~~~~~~~~~~~~~~~~~~
In their most basic form the core components can be run as follows::
par
{
/* Endpoint 0 core from lib_xua */
XUA_Endpoint0(c_ep_out[0], c_ep_in[0], c_aud_ctl, null, null, null, null);
/* Buffering cores - handles audio data to/from EP's and gives/gets data to/from the audio I/O core */
/* Note, this spawns two cores */
XUA_Buffer(c_ep_out[1], c_ep_in[1], c_sof, c_aud_ctl, p_for_mclk_count, c_aud);
/* AudioHub/IO core does most of the audio IO i.e. I2S (also serves as a hub for all audio) */
XUA_AudioHub(c_aud, ...) ;
}
``XUA_Buffer()`` expects its ``p_for_mclk_count`` argument to be clocked from the audio master clock before being passed it.
The following code satisfies this requirement::
{
/* Connect master-clock clock-block to clock-block pin */
set_clock_src(clk_audio_mclk_usb, p_mclk_in_usb); /* Clock clock-block from mclk pin */
set_port_clock(p_for_mclk_count, clk_audio_mclk_usb); /* Clock the "count" port from the clock block */
start_clock(clk_audio_mclk_usb); /* Set the clock off running */
XUA_Buffer(c_ep_out[1], c_ep_in[1], c_sof, c_aud_ctl, p_for_mclk_count, c_aud);
}
.. note:: Keeping this configuration outside of ``XUA_Buffer()`` does not preclude the possibllty of sharing ``p_mclk_in_usb`` port with additional components
To produce a fully operating device a call to ``XUD_Main()`` (from ``lib_xud``) must also be made for USB connectivity::
/* Low level USB device layer core */
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 cores */
chan c_sof;
/* Channel for audio data between buffering cores and AudioHub/IO core */
chan c_aud;
/* Channel for communicating control messages from EP0 to the rest of the device (via the buffering cores) */
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.
Configuring XUA
~~~~~~~~~~~~~~~
Configuration of the various build time options of ``lib_xua`` is done via the optional header `xua_conf.h`. Such build time options include audio class version, sample rates, channel counts etc.
Please see the API section for full listings.
The build system will automatically include the `xua_conf.h` header file as appropriate - the user should continue to include `xua.h` as previously directed. A simple example is shown below::
The build system will automatically include the `xua_conf.h` header file as appropriate - the developer
should continue to include `xua.h` as previously directed. A simple example is shown below::
#ifndef _XUA_CONF_H_
#define _XUA_CONF_H_
@@ -150,27 +94,10 @@ The build system will automatically include the `xua_conf.h` header file as appr
#endif
User functions
User Functions
~~~~~~~~~~~~~~
To enable custom functionality, such as configuring external audio hardware, custom functionality on stream start/stop etc various user overridable functions are provided (see API section for full listings). The default implementations are empty.
Codeless programming model
~~~~~~~~~~~~~~~~~~~~~~~~~~
Whilst it is possible to code a USB Audio device using the building blocks provided by `lib_xua` it is realised that this might not be desirable for some classes of customers or product.
For instance, some users may not have a large software development experience and simply want to customise some basic settings such as strings, sample-rates, channel-counts etc. Others may want to fully customise the implementation - adding additional functionality such as adding DSD or possibly only using a subset of the functions provided - just ``XUA_AudioHub``, for example.
In addition, the large number of supported features can lead to a large number of tasks, hardware resources, communication channels etc, requiring quite a lot of code to be authored for each product.
In order to cater for the former class of users, a "codeless" option is provided. Put simply, a file ``main.xc`` is provided which includes a pre-authored ``main()`` function along with all of the required hardware resource declarations. Code is generated based on the options provided in ``xua_conf.h``
Using this development model the user simply must include a ``xua_conf.h`` with their settings and optional implementations of any 'user functions' as desired. This, along with an XN file for their hardware platform, is all that is required to build a fully featured and functioning product.
This model also provides the benefit of a known-good, full codebase as a basis for a product.
This behaviour described in this section is the default behaviour of `lib_xua`, to disable this please set ``EXCLUDE_USB_AUDIO_MAIN`` to 1 in the application makefile or ``xua_conf.h``.
To enable custom functionality, such as configuring external audio hardware, bespoke behaviour on
stream start/stop etc, various functions can be overridden by the user. (see ::ref:`sec_api` for
full listings). The default implementations of these functions are empty.

25
lib_xua/doc/rst/using_adv.rst Normal file
View File

@@ -0,0 +1,25 @@
.. _sec_advanced_usage:
Advanced Usage
--------------
Whilst it is possible to program USB Audio devices using ``lib_xua`` by only setting defines
(see :ref:`sec_basic_usage_codeless`) some developers may want to code a USB Audio device from
scratch using the building blocks provided by `lib_xua`.
This could be for a number of reasons, adding complex DSP, merging with some other functionality
etc. This section describes these building blocks and their use.
Reviewing application note AN00246 is highly recommended at this point.
.. toctree::
Core Hardware Resources <using_adv_core_hw>
Running the Core Components <using_adv_core_comp>
I2S/TDM <using_adv_i2s>
Mixer <using_adv_mixer>

64
lib_xua/doc/rst/using_adv_core_comp.rst Normal file
View File

@@ -0,0 +1,64 @@
Running the Core Components
~~~~~~~~~~~~~~~~~~~~~~~~~~~
In their most basic form the core components can be run as follows::
par
{
/* Endpoint 0 core from lib_xua */
XUA_Endpoint0(c_ep_out[0], c_ep_in[0], c_aud_ctl, ...);
/* Buffering cores - handles audio data to/from EP's and gives/gets data to/from the audio I/O core */
/* Note, this spawns two cores */
XUA_Buffer(c_ep_out[1], c_ep_in[1], c_sof, c_aud_ctl, p_for_mclk_count, c_aud);
/* AudioHub/IO core does most of the audio IO i.e. I2S (also serves as a hub for all audio) */
XUA_AudioHub(c_aud, ...) ;
}
``XUA_Buffer()`` expects its ``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);
}
.. note:: Keeping this configuration outside of ``XUA_Buffer()`` means the possibility of sharing the
``p_mclk_in_usb`` port with additional components is not precluded
For USB connectivity a call to ``XUD_Main()`` (from ``lib_xud``) must also be made::
/* Low level USB device layer core */
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 cores */
chan c_sof;
/* Channel for audio data between buffering cores and AudioHub/IO core */
chan c_aud;
/* Channel for communicating control messages from EP0 to the rest of the device (via the buffering cores) */
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 no physical audio interfaces have yet to be instantiated.

43
lib_xua/doc/rst/using_adv_core_hw.rst Normal file
View File

@@ -0,0 +1,43 @@
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 */
.. note::
The ``PORT_MCLK_IN`` and ``PORT_MCLK_COUNT`` definitions are derived from the projects XN file
The ``XUA_AudioHub()`` function requires an audio master clock input to clock the physical audio I/O.
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, I2S or S/PDIF for example.
These should be passed into the various cores as required - see :ref:`sec_api`.

38
lib_xua/doc/rst/using_adv_i2s.rst Normal file
View File

@@ -0,0 +1,38 @@
|newpage|
I2S/TDM
~~~~~~~
I2S/TDM is typically fundamental to most products and is built into the ``XUA_AudioHub()`` core.
In order to enable I2S on 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 */
.. note::
All of these ports must be 1-bit ports, 32-bit buffed. Based on whether the xCORE is bus slave/master the ports must be declared as input/output respectively
These ports must then be passed to the ``XUA_AudioHub()`` task appropriately.
I2S functionality also requires two clock-blocks, one for bit and sample 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 core 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);

28
lib_xua/doc/rst/using_adv_mixer.rst Normal file
View File

@@ -0,0 +1,28 @@
|newpage|
Mixer
~~~~~
Since the mixer has no I/O the instantiation is straight forward. Communication wises, the mixer cores are inserted
between the `AudioHub` and Buffering core(s)
It takes three channel ends as parameters, one for audio to/from the buffering core(s), one for audio to/from the
`AudioHub` core and another one for control requests from the `Endpoint0` core.
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, ...);
}

9
lib_xua/src/core/buffer/ep/ep_buffer.xc
View File

@@ -5,15 +5,6 @@
#include <xs1.h>
#include <stdint.h>
#ifdef MIDI
#include "usb_midi.h"
#endif
#ifdef IAP
#include "iap.h"
#ifdef IAP_EA_NATIVE_TRANS
#include "iap2_ea_nativetransport.h"
#endif
#endif
#include "xc_ptr.h"
#include "xua_commands.h"
#include "xud.h"

2
lib_xua/src/core/clocking/clockgen.xc
View File

@@ -7,7 +7,7 @@
#include "xua.h"
#include "xua_commands.h"
#include "clocking.h"
#include "xua_clocking.h"
#if (XUA_SPDIF_RX_EN)
#include "spdif.h"

7
lib_xua/src/core/endpoint0/xua_ep0_uacreqs.xc
View File

@@ -15,9 +15,6 @@
#include "dbcalc.h"
#include "xua_commands.h"
#include "xc_ptr.h"
#ifdef MIXER
#include "mixer.h"
#endif
#define CS_XU_MIXSEL (0x06)
@@ -321,7 +318,7 @@ int AudioClassRequests_2(XUD_ep ep0_out, XUD_ep ep0_in, USB_SetupPacket_t &sp, c
int newSampleRate = buffer[0];
/* Instruct audio thread to change sample freq (if change required) */
if(newSampleRate != g_curSamFreq)
//if(newSampleRate != g_curSamFreq)
{
int newMasterClock;
@@ -374,7 +371,7 @@ int AudioClassRequests_2(XUD_ep ep0_out, XUD_ep ep0_in, USB_SetupPacket_t &sp, c
}
#endif /* MAX_FREQ != MIN_FREQ */
/* Send 0 Length as status stage */
XUD_DoSetRequestStatus(ep0_in);
int x = XUD_DoSetRequestStatus(ep0_in);
}
/* Direction: Device-to-host: Send Current Sample Freq */
else

11
lib_xua/src/core/main.xc
View File

@@ -24,19 +24,12 @@
#endif
#include "uac_hwresources.h"
#ifdef MIDI
#include "usb_midi.h"
#endif
#ifdef IAP
#include "i2c_shared.h"
#include "iap.h"
#endif
#ifdef MIXER
#include "mixer.h"
#endif
#if (XUA_SPDIF_RX_EN)
#include "SpdifReceive.h"
#endif
@@ -45,8 +38,6 @@
#include "adat_rx.h"
#endif
#include "clocking.h"
#if (XUA_NUM_PDM_MICS > 0)
#include "xua_pdm_mic.h"
#endif
@@ -674,7 +665,7 @@ int main()
on tile[MIDI_TILE]:
{
thread_speed();
usb_midi(p_midi_rx, p_midi_tx, clk_midi, c_midi, 0, null, null, null, null);
usb_midi(p_midi_rx, p_midi_tx, clk_midi, c_midi, 0);
}
#endif
#if defined(IAP)

1
lib_xua/src/core/mixer/mixer.xc
View File

@@ -3,7 +3,6 @@
#include <xs1.h>
#include <print.h>
#include "xua.h"
#include "mixer.h"
#include "xc_ptr.h"
#include "xua_commands.h"
#include "dbcalc.h"

32
lib_xua/src/midi/usb_midi.xc
View File

@@ -1,10 +1,10 @@
// Copyright 2011-2021 XMOS LIMITED.
// Copyright 2011-2022 XMOS LIMITED.
// This Software is subject to the terms of the XMOS Public Licence: Version 1.
#include <xs1.h>
#include <xclib.h>
#include <print.h>
#include <stdint.h>
#include "usb_midi.h"
#include "xua_midi.h"
#include "midiinparse.h"
#include "midioutparse.h"
#include "queue.h"
@@ -24,12 +24,8 @@ static unsigned makeSymbol(unsigned data)
#define RATE 31250
#ifndef MIDI_SHIFT_TX
#define MIDI_SHIFT_TX 0
#endif
static unsigned bit_time = XS1_TIMER_MHZ * 1000000 / (unsigned) RATE;
static unsigned bit_time_2 = (XS1_TIMER_MHZ * 1000000 / (unsigned) RATE) / 2;
static const unsigned bit_time = XS1_TIMER_MHZ * 1000000 / (unsigned) RATE;
static const unsigned bit_time_2 = (XS1_TIMER_MHZ * 1000000 / (unsigned) RATE) / 2;
// For debugging
int mr_count = 0; // MIDI received (from HOST)
@@ -58,16 +54,18 @@ timer iAPTimer;
void usb_midi(
#if (MIDI_RX_PORT_WIDTH == 4)
buffered in port:4 ?p_midi_in,
buffered in port:4 ?p_midi_in,
#else
buffered in port:1 ?p_midi_in,
buffered in port:1 ?p_midi_in,
#endif
port ?p_midi_out,
clock ?clk_midi,
chanend ?c_midi,
unsigned cable_number,
chanend ?c_iap, chanend ?c_i2c, // iOS stuff
port ?p_scl, port ?p_sda
clock ?clk_midi,
chanend ?c_midi,
unsigned cable_number
#ifdef IAP
, chanend ?c_iap, chanend ?c_i2c,
port ?p_scl, port ?p_sda
#endif
)
{
unsigned symbol = 0x0; // Symbol in progress of being sent out
@@ -241,7 +239,6 @@ buffered in port:1 ?p_midi_in,
}
p_midi_out <: (1<<MIDI_SHIFT_TX) @ txPT;
// printstr("mout1\n");
t :> txT;
txT += bit_time;
txPT += bit_time;
@@ -253,7 +250,6 @@ buffered in port:1 ?p_midi_in,
txT += bit_time; // Should this be after the output otherwise be double the length of the high before the start bit
txPT += bit_time;
p_midi_out @ txPT <: ((symbol & 1)<<MIDI_SHIFT_TX);
// printstr("mout2\n");
symbol >>= 1;
if (symbol == 0)
{
@@ -274,10 +270,8 @@ buffered in port:1 ?p_midi_in,
if (is_ack)
{
// have we got more data to send
//printstr("ack\n");
if (!queue_is_empty(midi_to_host_fifo))
{
//printstr("uart->decouple\n");
outuint(c_midi, queue_pop_word(midi_to_host_fifo, midi_to_host_fifo_arr));
th_count++;
}

4
lib_xua/src/midi/usb_midi_support.xc
View File

@@ -1,5 +1,5 @@
// Copyright 2011-2021 XMOS LIMITED.
// Copyright 2011-2022 XMOS LIMITED.
// This Software is subject to the terms of the XMOS Public Licence: Version 1.
#include <xs1.h>
#define __MIDI_IMPL
#include "usb_midi.h"
#include "xua_midi.h"