Merge pull request #142 from xmos/release/v1.1.0

Release v1.1.0

.gitignore

@@ -1,5 +1,4 @@
 *.log
-module_dfu/host/xmosdfu/xmosdfu
 *.dSYM
 */.build_*/*
 */bin/*
@@ -11,14 +10,21 @@ module_dfu/host/xmosdfu/xmosdfu
 *.xi
 *.i
 *.bin
-.*
 *~
 *.a
 *.swp
 *.*~
+*.pyc
+.build*
+.DS_Store
+test_results.csv
+_build*
+**/.venv/**
 
 # waf build files
 .lock-waf_*
 .waf-*/
 build/
-host/xmosdfu/xmosdfu
+.build*
+*.pyc
+xscope.xmt

Brewfile

@@ -0,0 +1,7 @@
+tap 'homebrew/core'
+
+brew 'perl'
+brew 'cpanm'
+
+brew 'python@2'
+brew 'pipenv'

CHANGELOG.rst

@@ -1,12 +1,82 @@
 lib_xua Change Log
 ==================
 
+1.1.0
+-----
+
+  * ADDED:     Ability to read or modify serial number string
+
+1.0.1
+-----
+
+  * FIXED:     Wrong size of vendor and product strings
+
+1.0.0
+-----
+
+  * ADDED:     UAC1 HID support with simulated Voice Command detection reported
+    every 10 seconds
+  * ADDED:     Support for USB HID Set Idle request
+  * ADDED:     Pre-processor symbols to enable single-threaded, dual-PDM
+    microphone operation
+  * FIXED:     Descriptors for XUA_ADAPTIVE incorrectly defined for IN endpoint
+  * ADDED:     Guards to user_hid.h and xua_hid.h
+  * ADDED:     UAC1 HID support for AC Stop (End Call), Volume Increment and
+    Volume Decrement
+  * CHANGE:    UAC1 HID to report function keys f21 through f24 as specified by
+    customer
+  * CHANGE:    HID interface for user to set and clear events from global
+    variable to function
+  * CHANGE     HID report descriptor to use generic events instead of GPI
+    events, to report Key-phrase detection as AC Search, and to report end-call
+    detection as AC Stop
+  * ADDED:     Ability to read or modify vendor and product IDs and strings
+  * ADDED:     Ability to read or modify bcdDevice
+  * ADDED:     Override USB descriptor with sampling frequency and
+    bit-resolution set at boot time.
+  * ADDED:     Global pointer to allow external access to masterClockFreq
+
+0.2.1
+-----
+
+  * HOTFIX: Fix descriptors for XUA_ADAPTIVE
+
+0.2.0
+-----
+
+  * ADDED:     Initial library documentation
+  * ADDED:     Application note AN00247: Using lib_xua with lib_spdif (transmit)
+  * ADDED:     Separate callbacks for input/output audio stream start/stop
+  * CHANGE:    I2S hardware resources no longer used globally and must be passed
+    to XUA_AudioHub()
+  * CHANGE:    XUA_AudioHub() no longer pars S/PDIF transmitter task
+  * CHANGE:    Moved to lib_spdif (from module_spdif_tx & module_spdif_rx)
+  * CHANGE:    Define NUM_PDM_MICS renamed to XUA_NUM_PDM_MICS
+  * CHANGE:    Define NO_USB renamed to XUA_USB_EN
+  * CHANGE:    Build files updated to support new "xcommon" behaviour in xwaf.
+  * RESOLVED:  wChannelConfig in UAC1 descriptor set according to output channel
+    count
+  * RESOLVED:  Indexing of ADAT channel strings (#18059)
+  * RESOLVED:  Rebooting device fails when PLL config "not reset" bit is set
+
+  * Changes to dependencies:
+
+    - lib_dsp: Added dependency 5.0.0
+
+    - lib_mic_array: Added dependency 4.0.0
+
+    - lib_spdif: Added dependency 3.1.0
+
+    - lib_xassert: Added dependency 3.0.1
+
 0.1.2
 -----
 
-  * ADDED:     Application note AN00246
+  * ADDED:     Application note AN00246: Simple USB Audio Device using lib_xua
+  * CHANGE:    xmosdfu emits warning if empty image read via upload
+  * CHANGE:    Simplified mclk port sharing - no longer uses unsafe pointer
   * RESOLVED:  Runtime exception issues when incorrect feedback calculated
-    (introduced in sc_xud 6.13)
+    (introduced in sc_usb_audio 6.13)
   * RESOLVED:  Output sample counter reset on stream start. Caused playback
     issues on some Linux based hosts
 
@@ -71,7 +141,7 @@ Legacy release history
 
 7.3.0
 -----
-    - CHANGE:     Example OSX DFU host app updated to now take PID as runtime 
+    - CHANGE:     Example OSX DFU host app updated to now take PID as runtime
       argument. This enabled multiple XMOS devices to be attached to the host
       during DFU process
 

Jenkinsfile

@@ -0,0 +1,103 @@
+@Library('xmos_jenkins_shared_library@v0.14.1') _
+
+getApproval()
+
+pipeline {
+  agent none
+  environment {
+    REPO = 'lib_xua'
+    VIEW = getViewName(REPO)
+  }
+  options {
+    skipDefaultCheckout()
+  }
+  stages {
+    stage('Basic tests') {
+      agent {
+        label 'x86_64&&brew'
+      }
+      stages {
+        stage('Get view') {
+          steps {
+            xcorePrepareSandbox("${VIEW}", "${REPO}")
+          }
+        }
+        stage('Library checks') {
+          steps {
+            xcoreLibraryChecks("${REPO}")
+          }
+        }
+        stage('Tests') {
+          steps {
+            runXmostest("${REPO}", 'tests')
+          }
+        }
+        stage('xCORE builds') {
+          steps {
+            dir("${REPO}") {
+              xcoreAllAppNotesBuild('examples')
+              dir("${REPO}") {
+                runXdoc('doc')
+              }
+            }
+          }
+        }
+      }
+      post {
+        cleanup {
+          xcoreCleanSandbox()
+        }
+      }
+    }
+    stage('Build host apps') {
+      failFast true
+      parallel {
+        stage('Build Linux host app') {
+          agent {
+            label 'x86_64&&brew&&linux'
+          }
+          steps {
+            xcorePrepareSandbox("${VIEW}", "${REPO}")
+            dir("${REPO}/${REPO}/host/xmosdfu") {
+              sh 'make -f Makefile.Linux64'
+            }
+          }
+          post {
+            cleanup {
+              xcoreCleanSandbox()
+            }
+          }
+        }
+        stage('Build Mac host app') {
+          agent {
+            label 'x86_64&&brew&&macOS'
+          }
+          steps {
+            xcorePrepareSandbox("${VIEW}", "${REPO}")
+            dir("${REPO}/${REPO}/host/xmosdfu") {
+              sh 'make -f Makefile.OSX64'
+            }
+          }
+          post {
+            cleanup {
+              xcoreCleanSandbox()
+            }
+          }
+        }
+      }
+    }
+    stage('Update') {
+      agent {
+        label 'x86_64&&brew'
+      }
+      steps {
+        updateViewfiles()
+      }
+      post {
+        cleanup {
+          xcoreCleanSandbox()
+        }
+      }
+    }
+  }
+}

LICENSE.txt

@@ -1,6 +1,6 @@
 Software Release License Agreement
 
-Copyright (c) 2011-2018, XMOS, All rights reserved.
+Copyright (c) 2011-2020, XMOS, All rights reserved.
 
 BY ACCESSING, USING, INSTALLING OR DOWNLOADING THE XMOS SOFTWARE, YOU AGREE TO BE BOUND BY THE FOLLOWING TERMS. IF YOU DO NOT AGREE TO THESE, DO NOT ATTEMPT TO DOWNLOAD, ACCESS OR USE THE XMOS Software.
 

Pipfile

@@ -0,0 +1,7 @@
+[[source]]
+name = "pypi"
+url = "https://pypi.org/simple"
+verify_ssl = true
+
+[dev-packages]
+flake8 = "*"

README.rst

@@ -1,18 +1,61 @@
 lib_xua
 =======
 
-USB Audio Shared Components. For use in the XMOS USB Audio Refererence Designs.
+Summary
+-------
 
+USB Audio Shared Components for use in the XMOS USB Audio Refererence Designs.
 
-Required software (dependencies)
-................................
+This library enables the development of USB Audio devices on the XMOS xCORE architecture.
 
-  * lib_logging
-  * lib_xud
+Features
+........
+
+Key features of the various applications in this repository are as follows
+
+- USB Audio Class 1.0/2.0 Compliant
+
+- Fully Asynchronous operation
+
+- 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
+
+- Support for dynamically selectable output audio formats (e.g. resolution)
+
+- Field firmware upgrade compliant to the USB Device Firmware Upgrade (DFU) Class Specification
+
+- S/PDIF output
+
+- S/PDIF input
+
+- ADAT output
+
+- ADAT input
+
+- MIDI input/output (Compliant to USB Class Specification for MIDI devices)
+
+- DSD output (Native and DoP mode) at DSD64 and DSD128 rates
+
+- Mixer with flexible routing
+
+- Simple playback controls via Human Interface Device (HID)
+
+- 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 also require specific host driver support.
 
-Checking dependent libs
 
 Software version and dependencies
 .................................
 
 .. libdeps::
+
+Related Application Notes
+.........................
+
+The following application notes use this library:
+
+    * AN000246 - Simple USB Audio Device using lib_xua
+    * AN000247 - Using lib_xua with lib_spdif (transmit)
+    * AN000248 - Using lib_xua with lib_mic_array

cpanfile

@@ -0,0 +1,2 @@
+requires 'File::Copy::Recursive';
+requires 'LWP::Simple'

doc_dfu/.gitignore

@@ -0,0 +1 @@
+_build

doc_dfu/building_xmos_dfu.rst

@@ -1,7 +1,7 @@
 .. _usb_audiosec_building_xmos_dfu:
 
-Building the XMOS DFU loader - macOS
-====================================
+Building the XMOS DFU loader
+============================
 
 The XMOS DFU loader is provided as source as part of the USB Audio
 framework, located in lib_xua/host/xmosdfu.
@@ -9,10 +9,33 @@ framework, located in lib_xua/host/xmosdfu.
 The loader is compiled using libusb, the code for the loader is contained in the
 file ``xmosdfu.cpp``
 
+macOS
+-----
+
 To build the loader a Makefile is provided, which can be run as follows:
 
-  ``make -f Makefile.OSX all``
+  ``make -f Makefile.OSX64 all``
 
 This Makefile contains the following:
 
-.. literalinclude:: Makefile.OSX
+.. literalinclude:: Makefile.OSX64
+
+There is also a 32bit OS X makefile, ``Makefile.OSX32``.
+
+Linux
+-----
+
+Similarly to macOS, there are two Linux makefiles provided, ``Makefile.Linux32`` and ``Makefile.Linux64``:
+
+.. literalinclude:: Makefile.Linux64
+
+System-wide libusb is used. On Debian-derived systems this can be installed with:
+
+  ``apt-get install libusb-1.0.0-dev``
+
+Raspberry Pi
+------------
+
+A makefile is provided for Raspbian. libusb is required and can be installed using the ``apt-get`` command from previous Linux section.
+
+.. literalinclude:: Makefile.Pi

doc_dfu/index.rst

@@ -7,4 +7,4 @@ DFU loader for XMOS USB AUDIO devices
     Creating factory and upgrade images with XFLASH <factory_image>
     Using the DFU loader - Windows (via the Thesycon driver) <thesycon_dfu>
     Using the DFU loader - macOS (via the XMOS DFU loader) <xmos_dfu>
-    Building the XMOS DFU loader - macOS <building_xmos_dfu>
+    Building the XMOS DFU loader <building_xmos_dfu>

examples/AN00246_xua_example/LICENSE.txt

@@ -1,6 +1,6 @@
 Software Release License Agreement
 
-Copyright (c) 2018, XMOS, All rights reserved.
+Copyright (c) 2018-2019, XMOS, All rights reserved.
 
 BY ACCESSING, USING, INSTALLING OR DOWNLOADING THE XMOS SOFTWARE, YOU AGREE TO BE BOUND BY THE FOLLOWING TERMS. IF YOU DO NOT AGREE TO THESE, DO NOT ATTEMPT TO DOWNLOAD, ACCESS OR USE THE XMOS Software.
 
@@ -132,4 +132,4 @@ This License shall be governed by and construed in accordance with English law a
 This License has been entered into on the date stated at the beginning of it.
 
 Schedule
-XMOS lib_xua software
+XMOS application note AN00246 software

examples/AN00246_xua_example/Makefile

@@ -4,13 +4,14 @@ TARGET = xk-audio-216-mc.xn
 
 # The flags passed to xcc when building the application
 XCC_FLAGS	= -fcomment-asm -Xmapper --map -Xmapper MAPFILE -O3 -report -fsubword-select -save-temps \
-			  -g -Wno-unused-function -Wno-timing -DXUD_SERIES_SUPPORT=XUD_X200_SERIES -DUSB_TILE=tile[1] \
-			  -DSDA_HIGH=2 -DSCL_HIGH=1 -fxscope
+			  -g -Wno-unused-function -Wno-timing -DXUD_SERIES_SUPPORT=XUD_X200_SERIES -DUSB_TILE=tile[1] -fxscope
+			  
+#-DSDA_HIGH=2 -DSCL_HIGH=1 -fxscope
 
 # The USED_MODULES variable lists other module used by the application. These
 # modules will extend the SOURCE_DIRS, INCLUDE_DIRS and LIB_DIRS variables.
 # Modules are expected to be in the directory above the BASE_DIR directory.
-USED_MODULES = lib_xua lib_device_control lib_xud module_i2c_shared module_i2c_single_port module_locks
+USED_MODULES = lib_xua lib_device_control lib_xud lib_i2c
 
 #=============================================================================
 # The following part of the Makefile includes the common build infrastructure

examples/AN00246_xua_example/README.rst

@@ -1,6 +1,6 @@
 
-How to use the lib_xua_library
-===============================
+Simple USB Audio Device using lib_xua
+=====================================
 
 .. version:: 0.1.0
 

examples/AN00246_xua_example/doc/rst/AN00246.rst

@@ -8,29 +8,16 @@ Overview
 Introduction
 ............
 
-The XMOS USB Audio (XUA) library provides an implemention of USB Audio Class 2.0 
+The XMOS USB Audio (XUA) library provides an implemention of USB Audio Class versions 1.0 and 2.0.
 
 This application note demonstrates the implementation of a basic USB Audio Device on 
 the xCORE-200 MC Audio board.
 
-Block diagram
-.............
-
-.. figure:: images/block_diagram.*
-   :width: 80%
-
-   Application block diagram
-
-The application uses a single logical core which runs the application and makes
-calls to the |I2C| master library functions as required.
-
-How to use lib_xua
-------------------
 
 The Makefile
-............
+------------
 
-To start using the lib_xua, you need to add ``lib_xua`` to your Makefile::
+To start using ``lib_xua``, you need to add ``lib_xua`` to your Makefile::
 
   USED_MODULES = .. lib_xua ...
 
@@ -68,7 +55,7 @@ be included in your code to use the library.
 Allocating hardware resources
 .............................
 
-A most basic implementation of a USB Audio device (i.e. simple stereo input and output via I2S)
+A basic implementation of a USB Audio device (i.e. simple stereo input and output via I2S)
 using ``lib_xua`` requires the follow pins:
 
     - I2S Bit Clock (from xCORE to DAC)
@@ -79,20 +66,34 @@ using ``lib_xua`` requires the follow pins:
 
 .. note::
 
-    ANOO246 assumes xCORE is I2S bus master
+    This application note assumes xCORE is I2S bus master
 
 On an xCORE the pins are controlled by ``ports``. The application therefore declares various ``ports``
 for this purpose:
 
 .. literalinclude:: app_xua_simple.xc
    :start-on: /* Port declaration
-   :end-on: /* Clock-block
+   :end-on: in port p_mclk_in
+
+``lib_xua`` also requires two ports for internally calculating USB feedback. Please refer to 
+the ``lib_xua`` library documentation for further details.  The additonal input port for the master
+clock is required since USB and S/PDIF do not reside of the same tiles on the example hardware.
+
+These ports are declared as follows:
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: /* Resources for USB feedback
+   :end-on: in port p_mclk_in_usb
 
 In addition to ``port`` resources two clock-block resources are also required:
 
 .. literalinclude:: app_xua_simple.xc
    :start-on: /* Clock-block
-   :end-on: /* clock clk_audio_mclk
+   :end-on: clock clk_audio_mclk_usb
+
+Again, for the same reasoning as the master-clock ports, two master-clock clock-blocks are required
+- one on each tile.
+
 
 Other declarations
 ..................
@@ -109,21 +110,21 @@ These are declared as follows:
 
 .. literalinclude:: app_xua_simple.xc
    :start-on: /* Endpoint type tables
-   :end-on: /* XUD_EpType epTypeTableIn
+   :end-on: XUD_EpType epTypeTableIn
 
 The application main() function
-...............................
+-------------------------------
 
 The ``main()`` function sets up the tasks in the application.
 
 Various channels are required in order to allow the required tasks to communcate. 
-These must be declared":
+These must first be declared:
 
 .. literalinclude:: app_xua_simple.xc
    :start-on: /* Channels for lib_xud
-   :end-on: /* chan c_aud_ctl
+   :end-on: chan c_aud_ctl
 
-The rest of the ``main()`` function starts all the tasks in parallel
+The rest of the ``main()`` function starts all of the tasks in parallel
 using the xC ``par`` construct:
 
 .. literalinclude:: app_xua_simple.xc
@@ -136,6 +137,25 @@ the audio I/O (i.e. I2S signalling).
 Configuration 
 .............
 
+``lib_xua`` has many parameters than can be configured at build time, some examples include:
+
+    - Sample-rates
+    - Channel counts
+    - Audio Class version
+    - Product/Vendor ID's
+    - Various product strings
+    - Master clock frequency
+
+These parameters are set via defines in an optional ``xua_conf.h`` header file. For this simple application the contents 
+of this file might look something like the following:
+
+.. literalinclude:: xua_conf.h
+   :start-on: // Copyright
+   :end-on: #endif
+
+Some items have sensible default values, items like strings and sample rates for example. However, some items are specific to a hardware 
+implentation e.g. master clock frequencies and must be defined.  Please see the ``lib_xua`` library documentation for full details.
+
 |appendix|
 |newpage|
 

examples/AN00246_xua_example/src/app_xua_simple.xc

@@ -22,23 +22,17 @@ buffered in port:32 p_i2s_adc[]    	= {PORT_I2S_ADC0};   /* I2S Data-line(s) */
 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, declared unsafe as sometimes we want to share this port
-e.g. PDM mics and I2S use same master clock IO */
-port p_mclk_in_                     = PORT_MCLK_IN;
-
-unsafe
-{
-    /* TODO simplify this */
-    unsafe port p_mclk_in;                               /* Audio master clock input */
-}
+/* Master clock for the audio IO tile */
+in port p_mclk_in                   = PORT_MCLK_IN;
 
+/* Resources for USB feedback */
 in port p_for_mclk_count            = PORT_MCLK_COUNT;   /* Extra port for counting master clock ticks */
-in port p_mclk_in2                  = PORT_MCLK_IN2;
+in port p_mclk_in_usb               = PORT_MCLK_IN_USB;  /* Extra master clock input for the USB tile */
 
 /* 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 */
-clock clk_audio_mclk2               = on tile[1]: XS1_CLKBLK_1;   /* Master clock */
+clock clk_audio_mclk_usb            = on tile[1]: XS1_CLKBLK_1;   /* Master clock for USB tile */
 
 /* Endpoint type tables - informs XUD what the transfer types for each Endpoint in use and also
  * if the endpoint wishes to be informed of USB bus resets */
@@ -54,10 +48,10 @@ int main()
     /* Channel for communicating SOF notifications from XUD to the Buffering cores */
     chan c_sof;
 
-    /* Channel for audio data between buffering cores and audio IO core */
+    /* 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 */
+    /* Channel for communicating control messages from EP0 to the rest of the device (via the buffering cores) */
     chan c_aud_ctl;
 
     par
@@ -66,7 +60,7 @@ int main()
         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_BUS);
+                      XUD_SPEED_HS, XUD_PWR_SELF);
         
         /* Endpoint 0 core from lib_xua */
         /* Note, since we are not using many features we pass in null for quite a few params.. */
@@ -75,22 +69,18 @@ int main()
         /* 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 */
         on tile[1]: {
-                        set_clock_src(clk_audio_mclk2, p_mclk_in2);
-                        set_port_clock(p_for_mclk_count, clk_audio_mclk2);
-                        start_clock(clk_audio_mclk2);
+                        
+                        /* 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);
 
                     }
 
-        /* IOHub core does most of the audio IO i.e. I2S (also serves as a hub for all audio) */
-        on tile[0]: {
-                        unsafe
-                        {
-                            p_mclk_in = p_mclk_in_; 
-                        }
-                        XUA_AudioHub(c_aud);
-                    }
+        /* 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);
     }
     
     return 0;

examples/AN00246_xua_example/src/hwsupport.xc

@@ -2,15 +2,15 @@
 
 #include <platform.h>
 #include <timer.h>
+#include <stdint.h>
 
 #include "xua.h"
-#include "i2c_shared.h"
+#include "i2c.h"     /* From lib_i2c */
 
 #include "cs5368.h"
 #include "cs4384.h"
 
-on tile [0] : struct r_i2c r_i2c = {XS1_PORT_4A};
-
+port p_i2c = on tile[0]:XS1_PORT_4A;
 
 /* General output port bit definitions */
 #define P_GPIO_DSD_MODE         (1 << 0) /* DSD mode select 0 = 8i/8o I2S, 1 = 8o DSD*/
@@ -22,17 +22,16 @@ on tile [0] : struct r_i2c r_i2c = {XS1_PORT_4A};
 #define P_GPIO_ADC_RST_N        (1 << 6)
 #define P_GPIO_MCLK_FSEL        (1 << 7) /* Select frequency on Phaselink clock. 0 = 24.576MHz for 48k, 1 = 22.5792MHz for 44.1k.*/
 
-#define DAC_REGWRITE(reg, val) {data[0] = val; i2c_shared_master_write_reg(r_i2c, CS4384_I2C_ADDR, reg, data, 1);}
-#define DAC_REGREAD(reg, val)  {i2c_shared_master_read_reg(r_i2c, CS4384_I2C_ADDR, reg, val, 1);}
-#define ADC_REGWRITE(reg, val) {data[0] = val; i2c_shared_master_write_reg(r_i2c, CS5368_I2C_ADDR, reg, data, 1);}
+#define DAC_REGWRITE(reg, val) result = i2c.write_reg(CS4384_I2C_ADDR, reg, val);
+#define DAC_REGREAD(reg)  data = i2c.read_reg(CS4384_I2C_ADDR, reg, result);
+#define ADC_REGWRITE(reg, val) result = i2c.write_reg(CS5368_I2C_ADDR, reg, val);
 
 out port p_gpio = on tile[0]:XS1_PORT_8C;
 
-void AudioHwConfig(unsigned samFreq, unsigned mClk, unsigned dsdMode,
-    unsigned sampRes_DAC, unsigned sampRes_ADC)
+void AudioHwConfig2(unsigned samFreq, unsigned mClk, unsigned dsdMode, unsigned sampRes_DAC, unsigned sampRes_ADC, client interface i2c_master_if i2c)
 {
-    unsigned char data[1] = {0};
 	unsigned char gpioVal = 0;
+    i2c_regop_res_t result;
 
     /* Set master clock select appropriately and put ADC and DAC into reset */
     if (mClk == MCLK_441)
@@ -67,6 +66,7 @@ void AudioHwConfig(unsigned samFreq, unsigned mClk, unsigned dsdMode,
 	*/
 	ADC_REGWRITE(CS5368_GCTL_MDE, 0b10010000 | (dif << 2) | mode);
 
+
 	/* Reg 0x06: (PDN) Power Down Register */
 	/* Bit[7:6]: Reserved
 	 * Bit[5]: PDN-BG: When set, this bit powers-own the bandgap reference
@@ -90,8 +90,8 @@ void AudioHwConfig(unsigned samFreq, unsigned mClk, unsigned dsdMode,
 	 * bit[0] : Power Down (PDN)               : Powered down
 	 */
 	DAC_REGWRITE(CS4384_MODE_CTRL, 0b11000001);
-
-	/* PCM Control (Address: 0x03) */
+	
+    /* PCM Control (Address: 0x03) */
 	/* bit[7:4] : Digital Interface Format (DIF) : 0b0001 for I2S up to 24bit
 	 * bit[3:2] : Reserved
 	 * bit[1:0] : Functional Mode (FM) : 0x00 - single-speed mode (4-50kHz)
@@ -120,6 +120,8 @@ void AudioHwConfig(unsigned samFreq, unsigned mClk, unsigned dsdMode,
 	 */
 	DAC_REGWRITE(CS4384_MODE_CTRL, 0b10000000);
 
+    /* Kill the i2c task */
+    i2c.shutdown();
     return;
 }
 
@@ -128,8 +130,16 @@ void AudioHwInit()
     /* Set USB Mux to micro-b */
     /* ADC and DAC in reset */
     p_gpio <: P_GPIO_USB_SEL0 | P_GPIO_USB_SEL1;
-
-    /* Init the i2c module */
-    i2c_shared_master_init(r_i2c);
+}
+
+void AudioHwConfig(unsigned samFreq, unsigned mClk, unsigned dsdMode,
+    unsigned sampRes_DAC, unsigned sampRes_ADC)
+{
+    i2c_master_if i2c[1];
+    par
+    {
+        i2c_master_single_port(i2c, 1, p_i2c, 10, 0, 1, 0);
+        AudioHwConfig2(samFreq, mClk, dsdMode, sampRes_DAC, sampRes_ADC, i2c[0]);
+    }
 }
 

examples/AN00246_xua_example/src/xk-audio-216-mc.xn

@@ -40,9 +40,10 @@
           </Tile>
           <Tile Number="1" Reference="tile[1]">
             <!-- USB intended to run on this tile -->
-            <!-- Audio Ports -->
+            <!-- Ports for USB feedback calculation -->
             <Port Location="XS1_PORT_16B" Name="PORT_MCLK_COUNT"/>              
-            <Port Location="XS1_PORT_1L"  Name="PORT_MCLK_IN2"/>
+            <Port Location="XS1_PORT_1L"  Name="PORT_MCLK_IN_USB"/>
+            <!-- Audio Ports -->
             <Port Location="XS1_PORT_1M"  Name="PORT_MIDI_IN"/>
             <Port Location="XS1_PORT_1N"  Name="PORT_MIDI_OUT"/>
             <Port Location="XS1_PORT_1O"  Name="PORT_ADAT_IN"/>-->  <!-- P: COAX O: OPT --> 

examples/AN00246_xua_example/src/xua_conf.h

@@ -1,24 +1,26 @@
-// Copyright (c) 2017-2018, XMOS Ltd, All rights reserved
+// Copyright (c) 2017-2019, XMOS Ltd, All rights reserved
 
-#define NUM_USB_CHAN_OUT 2
-#define NUM_USB_CHAN_IN 2
-#define I2S_CHANS_DAC 2
-#define I2S_CHANS_ADC 2
-#define MCLK_441 (512 * 44100)
-#define MCLK_48 (512 * 48000)
-#define MIN_FREQ 48000
-#define MAX_FREQ 48000
+#ifndef _XUA_CONF_H_ 
+#define _XUA_CONF_H_
+
+#define NUM_USB_CHAN_OUT      2     /* Number of channels from host to device */
+#define NUM_USB_CHAN_IN       2     /* Number of channels from device to host */
+#define I2S_CHANS_DAC         2     /* Number of I2S channels out of xCORE */
+#define I2S_CHANS_ADC         2     /* Number of I2S channels in to xCORE */
+#define MCLK_441  (512 * 44100)     /* 44.1kHz family master clock frequency */
+#define MCLK_48   (512 * 48000)     /* 48kHz family master clock frequency */
+#define MIN_FREQ  48000             /* Minimum sample rate */
+#define MAX_FREQ  48000             /* Maximum sample rate */
 
 #define EXCLUDE_USB_AUDIO_MAIN
 
-#define SPDIF_TX_INDEX 0
-#define VENDOR_STR "XMOS"
-#define VENDOR_ID 0x20B1
-#define PRODUCT_STR_A2 "XUA Example"
-#define PRODUCT_STR_A1 "XUA Example"
-#define PID_AUDIO_1 1
-#define PID_AUDIO_2 2
-#define AUDIO_CLASS 2
-#define AUDIO_CLASS_FALLBACK 0
-#define BCD_DEVICE 0x1234
-#define XUA_DFU_EN 0
+#define VENDOR_STR      "XMOS"
+#define VENDOR_ID       0x20B1
+#define PRODUCT_STR_A2  "XUA Example"
+#define PRODUCT_STR_A1  "XUA Example"
+#define PID_AUDIO_1     1   
+#define PID_AUDIO_2     2
+#define XUA_DFU_EN      0           /* Disable DFU (for simplicity of example */
+#define MIC_DUAL_ENABLED 0          // Use multi-threaded design
+
+#endif

examples/AN00247_xua_example_spdif_tx/LICENSE.txt

@@ -0,0 +1,135 @@
+Software Release License Agreement
+
+Copyright (c) 2018-2019, XMOS, All rights reserved.
+
+BY ACCESSING, USING, INSTALLING OR DOWNLOADING THE XMOS SOFTWARE, YOU AGREE TO BE BOUND BY THE FOLLOWING TERMS. IF YOU DO NOT AGREE TO THESE, DO NOT ATTEMPT TO DOWNLOAD, ACCESS OR USE THE XMOS Software.
+
+Parties:
+
+(1) XMOS Limited, incorporated and registered in England and Wales with company number 5494985 whose registered office is 107 Cheapside, London, EC2V 6DN (XMOS).
+
+(2)  An individual or legal entity exercising permissions granted by this License (Customer).
+
+If you are entering into this Agreement on behalf of another legal entity such as a company, partnership, university, college etc. (for example, as an employee, student or consultant), you warrant that you have authority to bind that entity.
+
+1. Definitions
+
+"License" means this Software License and any schedules or annexes to it.
+
+"License Fee" means the fee for the XMOS Software as detailed in any schedules or annexes to this Software License
+
+"Licensee Modifications" means all developments and modifications of the XMOS Software developed independently by the Customer.
+
+"XMOS Modifications" means all developments and modifications of the XMOS Software developed or co-developed by XMOS.
+
+"XMOS Hardware" means any XMOS hardware devices supplied by XMOS from time to time and/or the particular XMOS devices detailed in any schedules or annexes to this Software License.
+
+"XMOS Software" comprises the XMOS owned circuit designs, schematics, source code, object code, reference designs, (including related programmer comments and documentation, if any), error corrections, improvements, modifications (including XMOS Modifications) and updates.
+
+The headings in this License do not affect its interpretation. Save where the context otherwise requires, references to clauses and schedules are to clauses and schedules of this License.
+
+Unless the context otherwise requires:
+
+- references to XMOS and the Customer include their permitted successors and assigns; 
+- references to statutory provisions include those statutory provisions as amended or re-enacted; and
+- references to any gender include all genders.
+
+Words in the singular include the plural and in the plural include the singular.
+
+2. License
+
+XMOS grants the Customer a non-exclusive license to use, develop, modify and distribute the XMOS Software with, or for the purpose of being used with, XMOS Hardware.
+
+Open Source Software (OSS) must be used and dealt with in accordance with any license terms under which OSS is distributed.
+
+3. Consideration
+
+In consideration of the mutual obligations contained in this License, the parties agree to its terms.
+
+4. Term
+
+Subject to clause 12 below, this License shall be perpetual.
+
+5. Restrictions on Use
+
+The Customer will adhere to all applicable import and export laws and regulations of the country in which it resides and of the United States and United Kingdom, without limitation. The Customer agrees that it is its responsibility to obtain copies of and to familiarise itself fully with these laws and regulations to avoid violation.
+
+6. Modifications
+
+The Customer will own all intellectual property rights in the Licensee Modifications but will undertake to provide XMOS with any fixes made to correct any bugs found in the XMOS Software on a non-exclusive, perpetual and royalty free license basis.
+
+XMOS will own all intellectual property rights in the XMOS Modifications. 
+The Customer may only use the Licensee Modifications and XMOS Modifications on, or in relation to, XMOS Hardware.
+
+7. Support
+
+Support of the XMOS Software may be provided by XMOS pursuant to a separate support agreement. 
+
+8. Warranty and Disclaimer
+
+The XMOS Software is provided "AS IS" without a warranty of any kind. XMOS and its licensors' entire liability and Customer's exclusive remedy under this warranty to be determined in XMOS's sole and absolute discretion, will be either (a) the corrections of defects in media or replacement of the media, or (b) the refund of the license fee paid (if any).
+
+Whilst XMOS gives the Customer the ability to load their own software and applications onto XMOS devices, the security of such software and applications when on the XMOS devices is the Customer's own responsibility and any breach of security shall not be deemed a defect or failure of the hardware. XMOS shall have no liability whatsoever in relation to any costs, damages or other losses Customer may incur as a result of any breaches of security in relation to your software or applications.
+
+XMOS AND ITS LICENSORS DISCLAIM ALL OTHER WARRANTIES, EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY/ SATISFACTORY QUALITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT EXCEPT TO THE EXTENT THAT THESE DISCLAIMERS ARE HELD TO BE LEGALLY INVALID UNDER APPLICABLE LAW.
+
+9. High Risk Activities
+
+The XMOS Software is not designed or intended for use in conjunction with on-line control equipment in hazardous environments requiring fail-safe performance, including without limitation the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, life support machines, or weapons systems (collectively "High Risk Activities") in which the failure of the XMOS Software could lead directly to death, personal injury, or severe physical or environmental damage. XMOS and its licensors specifically disclaim any express or implied warranties relating to use of the XMOS Software in connection with High Risk Activities.
+
+10. Liability
+
+TO THE EXTENT NOT PROHIBITED BY APPLICABLE LAW, NEITHER XMOS NOR ITS LICENSORS SHALL BE LIABLE FOR ANY LOST REVENUE, BUSINESS, PROFIT, CONTRACTS OR DATA, ADMINISTRATIVE OR OVERHEAD EXPENSES, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES HOWEVER CAUSED AND REGARDLESS OF THEORY OF LIABILITY ARISING OUT OF THIS LICENSE, EVEN IF XMOS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. In no event shall XMOS's liability to the Customer whether in contract, tort (including negligence), or otherwise exceed the License Fee.
+
+Customer agrees to indemnify, hold harmless, and defend XMOS and its licensors from and against any claims or lawsuits, including attorneys' fees and any other liabilities, demands, proceedings, damages, losses, costs, expenses fines and charges which are made or brought against or incurred by XMOS as a result of your use or distribution of the Licensee Modifications or your use or distribution of XMOS Software, or any development of it, other than in accordance with the terms of this License.
+
+11. Ownership
+
+The copyrights and all other intellectual and industrial property rights for the protection of information with respect to the XMOS Software (including the methods and techniques on which they are based) are retained by XMOS and/or its licensors. Nothing in this Agreement serves to transfer such rights. Customer may not sell, mortgage, underlet, sublease, sublicense, lend or transfer possession of the XMOS Software in any way whatsoever to any third party who is not bound by this Agreement.
+
+12. Termination
+
+Either party may terminate this License at any time on written notice to the other if the other:
+
+- is in material or persistent breach of any of the terms of this License and either that breach is incapable of remedy, or the other party fails to remedy that breach within 30 days after receiving written notice requiring it to remedy that breach; or
+
+- is unable to pay its debts (within the meaning of section 123 of the Insolvency Act 1986), or becomes insolvent, or is subject to an order or a resolution for its liquidation, administration, winding-up or dissolution (otherwise than for the purposes of a solvent amalgamation or reconstruction), or has an administrative or other receiver, manager, trustee, liquidator, administrator or similar officer appointed over all or any substantial part of its assets, or enters into or proposes any composition or arrangement with its creditors generally, or is subject to any analogous event or proceeding in any applicable jurisdiction.
+
+Termination by either party in accordance with the rights contained in clause 12 shall be without prejudice to any other rights or remedies of that party accrued prior to termination.
+
+On termination for any reason:
+
+- all rights granted to the Customer under this License shall cease;
+- the Customer shall cease all activities authorised by this License;
+- the Customer shall immediately pay any sums due to XMOS under this License; and
+- the Customer shall immediately destroy or return to the XMOS (at the XMOS's option) all copies of the XMOS Software then in its possession, custody or control and, in the case of destruction, certify to XMOS that it has done so.
+
+Clauses 5, 8, 9, 10 and 11 shall survive any effective termination of this Agreement.
+
+13. Third party rights
+
+No term of this License is intended to confer a benefit on, or to be enforceable by, any person who is not a party to this license.
+
+14. Confidentiality and publicity
+
+Each party shall, during the term of this License and thereafter, keep confidential all, and shall not use for its own purposes nor without the prior written consent of the other disclose to any third party any, information of a confidential nature (including, without limitation, trade secrets and information of commercial value) which may become known to such party from the other party and which relates to the other party, unless such information is public knowledge or already known to such party at the time of disclosure, or subsequently becomes public knowledge other than by breach of this license, or subsequently comes lawfully into the possession of such party from a third party.
+
+The terms of this license are confidential and may not be disclosed by the Customer without the prior written consent of XMOS.
+The provisions of clause 14 shall remain in full force and effect notwithstanding termination of this license for any reason.
+
+15. Entire agreement
+
+This License and the documents annexed as appendices to this License or otherwise referred to herein contain the whole agreement between the parties relating to the subject matter hereof and supersede all prior agreements, arrangements and understandings between the parties relating to that subject matter.
+
+16. Assignment
+
+The Customer shall not assign this License or any of the rights granted under it without XMOS's prior written consent.
+
+17. Governing law and jurisdiction
+
+This License shall be governed by and construed in accordance with English law and each party hereby submits to the non-exclusive jurisdiction of the English courts.
+
+This License has been entered into on the date stated at the beginning of it.
+
+Schedule
+XMOS application note AN00247 software

examples/AN00247_xua_example_spdif_tx/Makefile

@@ -0,0 +1,21 @@
+APP_NAME = app_xua_simple
+
+TARGET = xk-audio-216-mc.xn
+
+# The flags passed to xcc when building the application
+XCC_FLAGS	= -fcomment-asm -Xmapper --map -Xmapper MAPFILE -O3 -report -fsubword-select -save-temps \
+			  -g -Wno-unused-function -Wno-timing -DXUD_SERIES_SUPPORT=XUD_X200_SERIES -DUSB_TILE=tile[1] \
+			  -DSDA_HIGH=2 -DSCL_HIGH=1 -fxscope
+
+# The USED_MODULES variable lists other module used by the application. These
+# modules will extend the SOURCE_DIRS, INCLUDE_DIRS and LIB_DIRS variables.
+# Modules are expected to be in the directory above the BASE_DIR directory.
+USED_MODULES = lib_xua lib_xud lib_spdif
+
+#=============================================================================
+# The following part of the Makefile includes the common build infrastructure
+# for compiling XMOS applications. You should not need to edit below here.
+
+XMOS_MAKE_PATH ?= ../..
+include $(XMOS_MAKE_PATH)/xcommon/module_xcommon/build/Makefile.common
+

examples/AN00247_xua_example_spdif_tx/README.rst

@@ -0,0 +1,34 @@
+
+Using lib_xua with lib_spdif (transmit) 
+=======================================
+
+.. version:: 0.1.0
+
+Summary
+-------
+
+Required tools and libraries
+............................
+
+.. appdeps::
+
+Required hardware
+.................
+
+The example code provided with the application has been implemented
+and tested on the xCORE-200 Multi-channel Audio Board
+
+Prerequisites
+.............
+
+ * This document assumes familiarity with the XMOS xCORE architecture,
+   the XMOS tool chain and the xC language. Documentation related to these
+   aspects which are not specific to this application note are linked to in
+   the references appendix.
+
+ * For a description of XMOS related terms found in this document
+   please see the XMOS Glossary [#]_.
+
+.. [#] http://www.xmos.com/published/glossary
+
+

examples/AN00247_xua_example_spdif_tx/doc/rst/AN00247.rst

@@ -8,31 +8,22 @@ Overview
 Introduction
 ............
 
-The XMOS USB Audio (XUA) library provides an implemention of USB Audio Class 2.0 
+The XMOS USB Audio (XUA) library provides an implemention of USB Audio Class versions 1.0 and 2.0.
 
-This application note demonstrates the implementation of a basic USB Audio Device on 
-the xCORE-200 MC Audio board.
+This application note demonstrates the implementation of a basic USB Audio Device with 
+S/PDIF transmit functionality the xCORE-200 MC Audio board.
 
-Block diagram
-.............
+To reduce complexity this application note does not enable any other audio interfaces other that S/PDIF transmit 
+(i.e. no I2S). Readers are encouraged to read applicaition note AN00246 in conjunction with this application
+note.
 
-.. figure:: images/block_diagram.*
-   :width: 80%
-
-   Application block diagram
-
-The application uses a single logical core which runs the application and makes
-calls to the |I2C| master library functions as required.
-
-How to use lib_xua
-------------------
 
 The Makefile
-............
+------------
 
-To start using the lib_xua, you need to add ``lib_xua`` to your Makefile::
+To start using ``lib_xua``, you need to add ``lib_xua`` and ``lib_spdif`` to your Makefile::
 
-  USED_MODULES = .. lib_xua ...
+  USED_MODULES = .. lib_xua lib_spdif ...
 
 This demo also uses the XMOS USB Device library (``lib_xud``) for low-level USB connectivity.
 The Makefile also includes::
@@ -49,7 +40,7 @@ Secondly, the architecture of the target device, for example::
   XCC_FLAGS = .. -DXUD_SERIES_SUPPORT=XUD_X200_SERIES ..
 
 Includes
-........
+--------
 
 This application requires the system header that defines XMOS xCORE specific
 defines for declaring and initialising hardware:
@@ -65,40 +56,73 @@ be included in your code to use the library.
    :start-on: include "xua.h"
    :end-on: include "xud_device.h"
 
-Allocating hardware resources
-.............................
-
-A most basic implementation of a USB Audio device (i.e. simple stereo input and output via I2S)
-using ``lib_xua`` requires the follow pins:
-
-    - I2S Bit Clock (from xCORE to DAC)
-    - I2S L/R clock (from xCORE to DAC)
-    - I2S Data line (from xCORE to DAC)
-    - I2S Data line (from ADC to xCORE)
-    - Audio Master clock (from clock source to xCORE)
-
-.. note::
-
-    ANOO246 assumes xCORE is I2S bus master
-
-On an xCORE the pins are controlled by ``ports``. The application therefore declares various ``ports``
-for this purpose:
+The application uses the S/PDIF transmitter from ``lib_spdif``. This header
+must be included in your code.
 
 .. literalinclude:: app_xua_simple.xc
-   :start-on: /* Port declaration
-   :end-on: /* Clock-block
+   :start-on: /* From lib_spdif 
+   :end-on: include "spdif.h"
+
+Declarations
+------------
+
+Allocating hardware resources for lib_xua
+.........................................
+
+A minimal implementation of a USB Audio device, without I2S functionalilty,
+using ``lib_xua`` requires the follow pins:
+
+    - Audio Master clock (from clock source to xCORE)
+
+On an xCORE the pins are controlled by ``ports``. The application therefore declares a 
+port for the master clock input signal.
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: /* Lib_xua port declaration
+   :end-on: in port p_mclk_in
+
+``lib_xua`` also requires two ports for internally calculating USB feedback. Please refer to 
+the ``lib_xua`` library documentation for further details.  The additonal input port for the master
+clock is required since USB and S/PDIF do not reside of the same tiles on the example hardware.
+
+These ports are declared as follows:
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: /* Resources for USB feedback
+   :end-on: in port p_mclk_in_usb
 
 In addition to ``port`` resources two clock-block resources are also required:
 
 .. literalinclude:: app_xua_simple.xc
    :start-on: /* Clock-block
-   :end-on: /* clock clk_audio_mclk
+   :end-on: clock clk_audio_mclk_usb
+
+Again, for the same reasoning as the master-clock ports, two master-clock clock-blocks are required
+- one on each tile.
+
+
+Allocating hardware resources for lib_spdif
+...........................................
+
+The S/PDIF transmitter requires a single (buffered) 1-bit port:
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: /* Lib_spdif port 
+   :end-on: buffered out port 
+
+This port must be clocked from the audio master clock. This application note chooses to declare
+an extra clock-block as follows:
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: clock clk_spdif_tx
+   :end-before: /* Lib_xua
+
 
 Other declarations
 ..................
 
 ``lib_xua`` currently requires the manual declaration of tables for the endpoint types for
-``lib_xud`` and the calling the main XUD funtion in a par (``XUD_Main()``).
+``lib_xud`` and the calling the main XUD function in a par (``XUD_Main()``).
 
 For a simple application the following endpoints are required:
 
@@ -109,32 +133,12 @@ These are declared as follows:
 
 .. literalinclude:: app_xua_simple.xc
    :start-on: /* Endpoint type tables
-   :end-on: /* XUD_EpType epTypeTableIn
+   :end-on: XUD_EpType epTypeTableIn
 
-The application main() function
-...............................
+Configuring lib_xua
+-------------------
 
-The ``main()`` function sets up the tasks in the application.
-
-Various channels are required in order to allow the required tasks to communcate. 
-These must be declared":
-
-.. literalinclude:: app_xua_simple.xc
-   :start-on: /* Channels for lib_xud
-   :end-on: /* chan c_aud_ctl
-
-The rest of the ``main()`` function starts all the tasks in parallel
-using the xC ``par`` construct:
-
-.. literalinclude:: app_xua_simple.xc
-   :start-on: par
-   :end-before: return 0
-
-This code starts the low-level USB task, an Endpoint 0 task, an Audio buffering task and a task to handle 
-the audio I/O (i.e. I2S signalling).
-
-Configuration 
-.............
+``lib_xua`` must be configued to enable S/PDIF Tx functionality. 
 
 ``lib_xua`` has many parameters than can be configured at build time, some examples include:
 
@@ -145,7 +149,41 @@ Configuration
     - Various product strings
     - Master clock frequency
 
-These parameters are set via defines in an optional ``xua_conf.h`` header file.
+To enable S/PDIF functionality ``XUA_SPDIF_TX_EN`` must be set to a non-zero value. Setting this will cause the ``XUA_AudioHub``
+tasks to forward samples and sample rate information to the S/PDIF transmitter task. 
+
+These parameters are set via defines in an optional ``xua_conf.h`` header file. For this simple application the 
+complete contents of this file are as follows:
+
+.. literalinclude:: xua_conf.h
+   :start-on: // Copyright
+   :end-on: #endif
+
+The application main() function
+-------------------------------
+
+The ``main()`` function sets up the tasks in the application.
+
+Various channels are required in order to allow the required tasks to communcate. 
+These must first be declared:
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: /* Channels for lib_xud
+   :end-on: chan c_spdif_tx
+
+The rest of the ``main()`` function starts all of the tasks in parallel
+using the xC ``par`` construct:
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: par
+   :end-before: return 0
+
+This code starts the low-level USB task, an Endpoint 0 task, an Audio buffering task and a task to handle 
+the audio I/O. Note, since there is no I2S funcitonality in this example this task simply forwards samples to the 
+SPDIF transmitter task. In addition the ``spdif_tx()`` task is also run.
+
+Note that the ``spdif_tx_port_config()`` function is called before a nested ``par`` of ``spdif_tx()`` and ``XUA_AudioHub()``.
+This is because of the "shared" nature of ``p_mclk_in`` and avoids a parrallel usage check failure by the XMOS toolchain.
 
 |appendix|
 |newpage|

examples/AN00247_xua_example_spdif_tx/doc/rst/xdoc.conf

@@ -0,0 +1,2 @@
+XMOSNEWSTYLE=1
+SOURCE_INCLUDE_DIRS=../../src

examples/AN00247_xua_example_spdif_tx/src/app_xua_simple.xc

@@ -0,0 +1,105 @@
+// Copyright (c) 2017-2018, XMOS Ltd, All rights reserved
+
+/* A very simple *example* of a USB audio application (and as such is un-verified for production)
+ *
+ * It uses the main blocks from the lib_xua 
+ *
+ * - S/PDIF output only
+ * - No DFU
+ *
+ */
+
+#include <xs1.h>
+#include <platform.h>
+
+#include "xua.h"
+#include "xud_device.h"
+
+/* From lib_spdif */
+#include "spdif.h"
+
+/* Lib_spdif port declarations. Note, the defines come from the xn file */
+buffered out port:32 p_spdif_tx     = PORT_SPDIF_OUT;             /* SPDIF transmit port */
+
+clock clk_spdif_tx                  = on tile[0]: XS1_CLKBLK_4;   /* Clock block for S/PDIF transmit */
+
+/* Lib_xua port declarations. Note, the defines come from the xn file */
+in port p_mclk_in                   = PORT_MCLK_IN;      /* Master clock for the audio IO tile */
+
+/* Resources for USB feedback */
+in port p_for_mclk_count            = PORT_MCLK_COUNT;   /* Extra port for counting master clock ticks */
+in port p_mclk_in_usb               = PORT_MCLK_IN_USB;  /* Extra master clock input for the USB tile */
+
+/* Clock-block declarations */
+clock clk_audio_mclk                = on tile[0]: XS1_CLKBLK_5;   /* Master clock */
+clock clk_audio_mclk_usb            = on tile[1]: XS1_CLKBLK_1;   /* Master clock for USB tile */
+
+/* Endpoint type tables - informs XUD what the transfer types for each Endpoint in use and also
+ * if the endpoint wishes to be informed of USB bus resets */
+XUD_EpType epTypeTableOut[]   = {XUD_EPTYPE_CTL | XUD_STATUS_ENABLE, XUD_EPTYPE_ISO};
+XUD_EpType epTypeTableIn[]    = {XUD_EPTYPE_CTL | XUD_STATUS_ENABLE, XUD_EPTYPE_ISO};
+
+int main()
+{
+    /* Channels 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;
+
+    /* Channel for communication between AudioHub and S/PDIF transmitter */
+    chan c_spdif_tx;
+
+    par
+    {
+        /* 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);
+        
+        /* Endpoint 0 core from lib_xua */
+        /* Note, since we are not using many features we pass in null for quite a few params.. */
+        on tile[1]: 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 */
+        on tile[1]: {
+                        
+                        /* 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);
+                    }
+        
+        /* AudioHub() (I2S) and S/SPDIF Tx are on the same tile */
+        on tile[0]: {
+
+                        /* Setup S/PDIF tx port from clock etc - note we do this before par to avoid parallel usage */
+                        spdif_tx_port_config(p_spdif_tx, clk_spdif_tx, p_mclk_in, 7);
+        
+                        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);
+                        }
+                    }
+    }
+    
+    return 0;
+}
+
+

examples/AN00247_xua_example_spdif_tx/src/hwsupport.xc

@@ -0,0 +1,52 @@
+// Copyright (c) 2016-2018, XMOS Ltd, All rights reserved
+
+#include <platform.h>
+#include <timer.h>
+
+#include "xua.h"
+
+/* General output port bit definitions */
+#define P_GPIO_DSD_MODE         (1 << 0) /* DSD mode select 0 = 8i/8o I2S, 1 = 8o DSD*/
+#define P_GPIO_DAC_RST_N        (1 << 1)
+#define P_GPIO_USB_SEL0         (1 << 2)
+#define P_GPIO_USB_SEL1         (1 << 3)
+#define P_GPIO_VBUS_EN          (1 << 4)
+#define P_GPIO_PLL_SEL          (1 << 5) /* 1 = CS2100, 0 = Phaselink clock source */
+#define P_GPIO_ADC_RST_N        (1 << 6)
+#define P_GPIO_MCLK_FSEL        (1 << 7) /* Select frequency on Phaselink clock. 0 = 24.576MHz for 48k, 1 = 22.5792MHz for 44.1k.*/
+
+
+out port p_gpio = on tile[0]:XS1_PORT_8C;
+
+void AudioHwConfig(unsigned samFreq, unsigned mClk, unsigned dsdMode,
+    unsigned sampRes_DAC, unsigned sampRes_ADC)
+{
+    unsigned char data[1] = {0};
+	unsigned char gpioVal = 0;
+
+    /* Set master clock select appropriately and put ADC and DAC into reset */
+    if (mClk == MCLK_441)
+    {
+		gpioVal =  P_GPIO_USB_SEL0 | P_GPIO_USB_SEL1;
+    }
+    else
+    {
+		gpioVal = P_GPIO_USB_SEL0 | P_GPIO_USB_SEL1 | P_GPIO_MCLK_FSEL;
+    }
+
+    /* Note, DAC and ADC held in reset */
+	p_gpio <: gpioVal;
+
+    /* Allow MCLK to settle */
+    delay_microseconds(20000);
+
+    return;
+}
+
+void AudioHwInit()
+{
+    /* Set USB Mux to micro-b */
+    /* ADC and DAC in reset */
+    p_gpio <: P_GPIO_USB_SEL0 | P_GPIO_USB_SEL1;
+}
+

examples/AN00247_xua_example_spdif_tx/src/xk-audio-216-mc.xn

@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Network xmlns="http://www.xmos.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.xmos.com http://www.xmos.com" ManuallySpecifiedRouting="true">
+  <Type>Board</Type>
+  <Name>XS2 MC Audio</Name>
+  <Declarations>
+    <Declaration>tileref tile[2]</Declaration>
+    <Declaration>tileref usb_tile</Declaration>
+  </Declarations>
+  <Packages>
+    <Package id="0" Type="XS2-UnA-512-FB236">
+      <Nodes>
+        <Node Id="0" InPackageId="0" Type="XS2-L16A-512" Oscillator="24MHz" SystemFrequency="500MHz" referencefrequency="100MHz">
+          <Boot>
+            <Source Location="SPI:bootFlash"/>
+          </Boot>
+          <Tile Number="0" Reference="tile[0]">
+            <Port Location="XS1_PORT_1B" Name="PORT_SQI_CS"/>
+            <Port Location="XS1_PORT_1C" Name="PORT_SQI_SCLK"/>
+            <Port Location="XS1_PORT_4B" Name="PORT_SQI_SIO"/>
+        
+            <!-- Audio Ports -->         
+            <Port Location="XS1_PORT_1A"  Name="PORT_PLL_REF"/>
+            <Port Location="XS1_PORT_1F"  Name="PORT_MCLK_IN"/>
+            <Port Location="XS1_PORT_1G"  Name="PORT_I2S_LRCLK"/>
+            <Port Location="XS1_PORT_1H"  Name="PORT_I2S_BCLK"/>
+            <Port Location="XS1_PORT_1M"  Name="PORT_I2S_DAC0"/>
+            <port Location="XS1_PORT_1N"  Name="PORT_I2S_DAC1"/>
+            <port Location="XS1_PORT_1O"  Name="PORT_I2S_DAC2"/>
+            <port Location="XS1_PORT_1P"  Name="PORT_I2S_DAC3"/>
+            <Port Location="XS1_PORT_1I"  Name="PORT_I2S_ADC0"/>
+            <Port Location="XS1_PORT_1J"  Name="PORT_I2S_ADC1"/>
+            <Port Location="XS1_PORT_1K"  Name="PORT_I2S_ADC2"/>
+            <Port Location="XS1_PORT_1L"  Name="PORT_I2S_ADC3"/>
+            <Port Location="XS1_PORT_4A"  Name="PORT_I2C"/>
+            <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"/>
+            <Port Location="XS1_PORT_1E"  Name="PORT_ADAT_OUT"/>-->  <!-- D: COAX E: OPT --> 
+            <Port Location="XS1_PORT_1D"  Name="PORT_SPDIF_OUT"/>--> <!-- D: COAX E: OPT --> 
+          </Tile>
+          <Tile Number="1" Reference="tile[1]">
+            <!-- USB intended to run on this tile -->
+            <!-- Ports for USB feedback calculation -->
+            <Port Location="XS1_PORT_16B" Name="PORT_MCLK_COUNT"/>              
+            <Port Location="XS1_PORT_1L"  Name="PORT_MCLK_IN_USB"/>
+            <!-- Audio Ports -->
+            <Port Location="XS1_PORT_1M"  Name="PORT_MIDI_IN"/>
+            <Port Location="XS1_PORT_1N"  Name="PORT_MIDI_OUT"/>
+            <Port Location="XS1_PORT_1O"  Name="PORT_ADAT_IN"/>-->  <!-- P: COAX O: OPT --> 
+            <Port Location="XS1_PORT_1P"  Name="PORT_SPDIF_IN"/>--> <!-- P: COAX O: OPT --> 
+          </Tile>
+        </Node>
+        <Node Id="1" InPackageId="1" Type="periph:XS1-SU" Reference="usb_tile" Oscillator="24MHz">
+        </Node>
+      </Nodes>
+      <Links>
+        <Link Encoding="5wire">
+          <LinkEndpoint NodeId="0" Link="8" Delays="52clk,52clk"/>
+          <LinkEndpoint NodeId="1" Link="XL0" Delays="1clk,1clk"/>
+        </Link>
+      </Links>
+    </Package>
+  </Packages>
+  <Nodes>
+    <Node Id="2" Type="device:" RoutingId="0x8000">
+      <Service Id="0" Proto="xscope_host_data(chanend c);">
+        <Chanend Identifier="c" end="3"/>
+      </Service>
+    </Node>
+  </Nodes>
+  <Links>
+    <Link Encoding="2wire" Delays="4,4" Flags="XSCOPE">
+      <LinkEndpoint NodeId="0" Link="XL0"/>
+      <LinkEndpoint NodeId="2" Chanend="1"/>
+    </Link>
+  </Links>
+  <ExternalDevices>
+    <Device NodeId="0" Tile="0" Class="SQIFlash" Name="bootFlash" Type="S25FL116K">
+      <Attribute Name="PORT_SQI_CS" Value="PORT_SQI_CS"/>
+      <Attribute Name="PORT_SQI_SCLK"   Value="PORT_SQI_SCLK"/>
+      <Attribute Name="PORT_SQI_SIO"  Value="PORT_SQI_SIO"/>
+    </Device>
+  </ExternalDevices>
+  <JTAGChain>
+    <JTAGDevice NodeId="0"/>
+    <JTAGDevice NodeId="1"/>
+  </JTAGChain>
+</Network>

examples/AN00247_xua_example_spdif_tx/src/xua_conf.h

@@ -0,0 +1,31 @@
+// Copyright (c) 2017-2019, XMOS Ltd, All rights reserved
+
+#ifndef _XUA_CONF_H_ 
+#define _XUA_CONF_H_
+
+#define NUM_USB_CHAN_OUT 2
+#define NUM_USB_CHAN_IN 0
+#define I2S_CHANS_DAC 0
+#define I2S_CHANS_ADC 0
+#define MCLK_441 (512 * 44100)
+#define MCLK_48 (512 * 48000)
+#define MIN_FREQ 48000
+#define MAX_FREQ 48000
+
+#define EXCLUDE_USB_AUDIO_MAIN
+
+#define XUA_SPDIF_TX_EN 1
+#define SPDIF_TX_INDEX 0
+#define VENDOR_STR "XMOS"
+#define VENDOR_ID 0x20B1
+#define PRODUCT_STR_A2 "XUA SPDIF Example"
+#define PRODUCT_STR_A1 "XUA SPDIF Example"
+#define PID_AUDIO_1 1
+#define PID_AUDIO_2 2
+#define AUDIO_CLASS 2
+#define AUDIO_CLASS_FALLBACK 0
+#define BCD_DEVICE 0x1234
+#define XUA_DFU_EN 0
+#define MIC_DUAL_ENABLED 0          // Use multi-threaded design
+
+#endif

examples/AN00247_xua_example_spdif_tx/src/xud_conf.h

@@ -0,0 +1,7 @@
+// Copyright (c) 2017-2018, XMOS Ltd, All rights reserved
+
+#include "xua_conf.h"
+
+/* TODO */
+#define XUD_UAC_NUM_USB_CHAN_OUT    NUM_USB_CHAN_OUT
+#define XUD_UAC_NUM_USB_CHAN_IN     NUM_USB_CHAN_IN

examples/AN00248_xua_example_pdm_mics/LICENSE.txt

@@ -0,0 +1,135 @@
+Software Release License Agreement
+
+Copyright (c) 2018-2019, XMOS, All rights reserved.
+
+BY ACCESSING, USING, INSTALLING OR DOWNLOADING THE XMOS SOFTWARE, YOU AGREE TO BE BOUND BY THE FOLLOWING TERMS. IF YOU DO NOT AGREE TO THESE, DO NOT ATTEMPT TO DOWNLOAD, ACCESS OR USE THE XMOS Software.
+
+Parties:
+
+(1) XMOS Limited, incorporated and registered in England and Wales with company number 5494985 whose registered office is 107 Cheapside, London, EC2V 6DN (XMOS).
+
+(2)  An individual or legal entity exercising permissions granted by this License (Customer).
+
+If you are entering into this Agreement on behalf of another legal entity such as a company, partnership, university, college etc. (for example, as an employee, student or consultant), you warrant that you have authority to bind that entity.
+
+1. Definitions
+
+"License" means this Software License and any schedules or annexes to it.
+
+"License Fee" means the fee for the XMOS Software as detailed in any schedules or annexes to this Software License
+
+"Licensee Modifications" means all developments and modifications of the XMOS Software developed independently by the Customer.
+
+"XMOS Modifications" means all developments and modifications of the XMOS Software developed or co-developed by XMOS.
+
+"XMOS Hardware" means any XMOS hardware devices supplied by XMOS from time to time and/or the particular XMOS devices detailed in any schedules or annexes to this Software License.
+
+"XMOS Software" comprises the XMOS owned circuit designs, schematics, source code, object code, reference designs, (including related programmer comments and documentation, if any), error corrections, improvements, modifications (including XMOS Modifications) and updates.
+
+The headings in this License do not affect its interpretation. Save where the context otherwise requires, references to clauses and schedules are to clauses and schedules of this License.
+
+Unless the context otherwise requires:
+
+- references to XMOS and the Customer include their permitted successors and assigns; 
+- references to statutory provisions include those statutory provisions as amended or re-enacted; and
+- references to any gender include all genders.
+
+Words in the singular include the plural and in the plural include the singular.
+
+2. License
+
+XMOS grants the Customer a non-exclusive license to use, develop, modify and distribute the XMOS Software with, or for the purpose of being used with, XMOS Hardware.
+
+Open Source Software (OSS) must be used and dealt with in accordance with any license terms under which OSS is distributed.
+
+3. Consideration
+
+In consideration of the mutual obligations contained in this License, the parties agree to its terms.
+
+4. Term
+
+Subject to clause 12 below, this License shall be perpetual.
+
+5. Restrictions on Use
+
+The Customer will adhere to all applicable import and export laws and regulations of the country in which it resides and of the United States and United Kingdom, without limitation. The Customer agrees that it is its responsibility to obtain copies of and to familiarise itself fully with these laws and regulations to avoid violation.
+
+6. Modifications
+
+The Customer will own all intellectual property rights in the Licensee Modifications but will undertake to provide XMOS with any fixes made to correct any bugs found in the XMOS Software on a non-exclusive, perpetual and royalty free license basis.
+
+XMOS will own all intellectual property rights in the XMOS Modifications. 
+The Customer may only use the Licensee Modifications and XMOS Modifications on, or in relation to, XMOS Hardware.
+
+7. Support
+
+Support of the XMOS Software may be provided by XMOS pursuant to a separate support agreement. 
+
+8. Warranty and Disclaimer
+
+The XMOS Software is provided "AS IS" without a warranty of any kind. XMOS and its licensors' entire liability and Customer's exclusive remedy under this warranty to be determined in XMOS's sole and absolute discretion, will be either (a) the corrections of defects in media or replacement of the media, or (b) the refund of the license fee paid (if any).
+
+Whilst XMOS gives the Customer the ability to load their own software and applications onto XMOS devices, the security of such software and applications when on the XMOS devices is the Customer's own responsibility and any breach of security shall not be deemed a defect or failure of the hardware. XMOS shall have no liability whatsoever in relation to any costs, damages or other losses Customer may incur as a result of any breaches of security in relation to your software or applications.
+
+XMOS AND ITS LICENSORS DISCLAIM ALL OTHER WARRANTIES, EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY/ SATISFACTORY QUALITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT EXCEPT TO THE EXTENT THAT THESE DISCLAIMERS ARE HELD TO BE LEGALLY INVALID UNDER APPLICABLE LAW.
+
+9. High Risk Activities
+
+The XMOS Software is not designed or intended for use in conjunction with on-line control equipment in hazardous environments requiring fail-safe performance, including without limitation the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, life support machines, or weapons systems (collectively "High Risk Activities") in which the failure of the XMOS Software could lead directly to death, personal injury, or severe physical or environmental damage. XMOS and its licensors specifically disclaim any express or implied warranties relating to use of the XMOS Software in connection with High Risk Activities.
+
+10. Liability
+
+TO THE EXTENT NOT PROHIBITED BY APPLICABLE LAW, NEITHER XMOS NOR ITS LICENSORS SHALL BE LIABLE FOR ANY LOST REVENUE, BUSINESS, PROFIT, CONTRACTS OR DATA, ADMINISTRATIVE OR OVERHEAD EXPENSES, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES HOWEVER CAUSED AND REGARDLESS OF THEORY OF LIABILITY ARISING OUT OF THIS LICENSE, EVEN IF XMOS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. In no event shall XMOS's liability to the Customer whether in contract, tort (including negligence), or otherwise exceed the License Fee.
+
+Customer agrees to indemnify, hold harmless, and defend XMOS and its licensors from and against any claims or lawsuits, including attorneys' fees and any other liabilities, demands, proceedings, damages, losses, costs, expenses fines and charges which are made or brought against or incurred by XMOS as a result of your use or distribution of the Licensee Modifications or your use or distribution of XMOS Software, or any development of it, other than in accordance with the terms of this License.
+
+11. Ownership
+
+The copyrights and all other intellectual and industrial property rights for the protection of information with respect to the XMOS Software (including the methods and techniques on which they are based) are retained by XMOS and/or its licensors. Nothing in this Agreement serves to transfer such rights. Customer may not sell, mortgage, underlet, sublease, sublicense, lend or transfer possession of the XMOS Software in any way whatsoever to any third party who is not bound by this Agreement.
+
+12. Termination
+
+Either party may terminate this License at any time on written notice to the other if the other:
+
+- is in material or persistent breach of any of the terms of this License and either that breach is incapable of remedy, or the other party fails to remedy that breach within 30 days after receiving written notice requiring it to remedy that breach; or
+
+- is unable to pay its debts (within the meaning of section 123 of the Insolvency Act 1986), or becomes insolvent, or is subject to an order or a resolution for its liquidation, administration, winding-up or dissolution (otherwise than for the purposes of a solvent amalgamation or reconstruction), or has an administrative or other receiver, manager, trustee, liquidator, administrator or similar officer appointed over all or any substantial part of its assets, or enters into or proposes any composition or arrangement with its creditors generally, or is subject to any analogous event or proceeding in any applicable jurisdiction.
+
+Termination by either party in accordance with the rights contained in clause 12 shall be without prejudice to any other rights or remedies of that party accrued prior to termination.
+
+On termination for any reason:
+
+- all rights granted to the Customer under this License shall cease;
+- the Customer shall cease all activities authorised by this License;
+- the Customer shall immediately pay any sums due to XMOS under this License; and
+- the Customer shall immediately destroy or return to the XMOS (at the XMOS's option) all copies of the XMOS Software then in its possession, custody or control and, in the case of destruction, certify to XMOS that it has done so.
+
+Clauses 5, 8, 9, 10 and 11 shall survive any effective termination of this Agreement.
+
+13. Third party rights
+
+No term of this License is intended to confer a benefit on, or to be enforceable by, any person who is not a party to this license.
+
+14. Confidentiality and publicity
+
+Each party shall, during the term of this License and thereafter, keep confidential all, and shall not use for its own purposes nor without the prior written consent of the other disclose to any third party any, information of a confidential nature (including, without limitation, trade secrets and information of commercial value) which may become known to such party from the other party and which relates to the other party, unless such information is public knowledge or already known to such party at the time of disclosure, or subsequently becomes public knowledge other than by breach of this license, or subsequently comes lawfully into the possession of such party from a third party.
+
+The terms of this license are confidential and may not be disclosed by the Customer without the prior written consent of XMOS.
+The provisions of clause 14 shall remain in full force and effect notwithstanding termination of this license for any reason.
+
+15. Entire agreement
+
+This License and the documents annexed as appendices to this License or otherwise referred to herein contain the whole agreement between the parties relating to the subject matter hereof and supersede all prior agreements, arrangements and understandings between the parties relating to that subject matter.
+
+16. Assignment
+
+The Customer shall not assign this License or any of the rights granted under it without XMOS's prior written consent.
+
+17. Governing law and jurisdiction
+
+This License shall be governed by and construed in accordance with English law and each party hereby submits to the non-exclusive jurisdiction of the English courts.
+
+This License has been entered into on the date stated at the beginning of it.
+
+Schedule
+XMOS application note AN00248 software

examples/AN00248_xua_example_pdm_mics/Makefile

@@ -0,0 +1,21 @@
+APP_NAME = app_xua_simple
+
+TARGET = mic_array_ref.xn
+
+# The flags passed to xcc when building the application
+XCC_FLAGS	= -fcomment-asm -Xmapper --map -Xmapper MAPFILE -O3 -report -fsubword-select -save-temps \
+			  -g -Wno-unused-function -Wno-timing -DXUD_SERIES_SUPPORT=XUD_X200_SERIES -DUSB_TILE=tile[1] \
+			  -DSDA_HIGH=2 -DSCL_HIGH=1 -fxscope
+
+# The USED_MODULES variable lists other module used by the application. These
+# modules will extend the SOURCE_DIRS, INCLUDE_DIRS and LIB_DIRS variables.
+# Modules are expected to be in the directory above the BASE_DIR directory.
+USED_MODULES = lib_xua lib_xud lib_mic_array
+
+#=============================================================================
+# The following part of the Makefile includes the common build infrastructure
+# for compiling XMOS applications. You should not need to edit below here.
+
+XMOS_MAKE_PATH ?= ../..
+include $(XMOS_MAKE_PATH)/xcommon/module_xcommon/build/Makefile.common
+

examples/AN00248_xua_example_pdm_mics/README.rst

@@ -0,0 +1,37 @@
+
+Using lib_xua with lib_mic_array
+================================
+
+.. version:: 0.1.0
+
+Summary
+-------
+
+This applicaition note describes how to use ``lib_mic_array`` in conjunction with ``lib_xua``
+to implement a USB Audio device with the ability to record from multiple PDM microphones.
+
+Required tools and libraries
+............................
+
+.. appdeps::
+
+Required hardware
+.................
+
+The example code provided with the application has been implemented
+and tested on the xCORE-200 Array Microphone board.
+
+Prerequisites
+.............
+
+ * This document assumes familiarity with the XMOS xCORE architecture,
+   the XMOS tool chain and the xC language. Documentation related to these
+   aspects which are not specific to this application note are linked to in
+   the references appendix.
+
+ * For a description of XMOS related terms found in this document
+   please see the XMOS Glossary [#]_.
+
+.. [#] http://www.xmos.com/published/glossary
+
+

examples/AN00248_xua_example_pdm_mics/doc/rst/AN00248.rst

@@ -0,0 +1,315 @@
+.. include:: ../../README.rst
+
+|newpage|
+
+Overview
+--------
+
+Introduction
+............
+
+The XMOS USB Audio (XUA) library provides an implementation of USB Audio Class versions 1.0 and 2.0.
+
+This application note demonstrates the implementation of a basic USB Audio Device with 
+record functionality from PDM microphones on the xCORE-200 Array Microphone board.
+
+Core PDM microphone functionality is contained in` ``lib_mic_array``. This library includes both the physical
+interfacing to the PDM microphones as well as efficient decimation to user selectable output
+sample rates - essentially providing PDM to PCM conversion.
+
+To reduce complexity this application note does not enable any other audio interfaces other than recording 
+from PDM microphones (i.e. no I2S and the on board DAC is not configured. 
+
+Readers are encouraged to read application note AN00246 in conjunction with this application note.
+
+
+The Makefile
+------------
+
+To start using ``lib_xua``, you need to add ``lib_xua`` to the Makefile. ``lib_mic_array`` should also be 
+added for this application example::
+
+  USED_MODULES = .. lib_xua lib_mic_array ...
+
+This demo also uses the XMOS USB Device library (``lib_xud``) for low-level USB connectivity.
+The Makefile therefore also includes this lib::
+
+  USED_MODULES = .. lib_xud ..
+
+``lib_xud`` library requires some flags for correct operation. Firstly the 
+tile on which ``lib_xud`` will be executed, for example::
+
+    XCC_FLAGS = .. -DUSB_TILE=tile[1] ..
+
+Secondly, the architecture of the target device, for example::
+
+  XCC_FLAGS = .. -DXUD_SERIES_SUPPORT=XUD_X200_SERIES ..
+
+Includes
+--------
+
+This application requires the system header files that contains XMOS xCORE specific
+defines for declaring and initialising hardware:
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: include <xs1.h>
+   :end-before: include "xua.h"
+
+The XUA and XUD library functions are defined in header files ``xua.h`` and ``xud_device.h`` respectively. These headers must
+be included in the code in order to use these libraries. 
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: include "xua.h"
+   :end-on: include "xud_device.h"
+
+The application uses PDM interfacing and decimation code from ``lib_mic_array``. This header
+must be included in the code.
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: /* From lib_mic
+   :end-on: include "mic_array.h"
+
+Declarations
+------------
+
+Allocating hardware resources for lib_xua
+.........................................
+
+A minimal implementation of a USB Audio device using ``lib_xua``,  without I2S functionality,
+requires the follow I/O pins:
+
+    - Audio Master clock (from clock source to xCORE)
+
+On an xCORE the pins are controlled by ``ports``. The application therefore declares a 
+port for the master clock input signal.
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: /* Lib_xua port declaration
+   :end-on: in port p_mclk_in
+
+``lib_xua`` also requires two ports for internally calculating USB feedback. Please refer to 
+the ``lib_xua`` library documentation for further details.  In this example ``XUA_Buffer()`` and ``XUA_AudioHub()``
+reside on the same tile and can therefore make use of the same master-clock port.
+
+These ports are declared as follows:
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: /* Resources for USB feedback
+   :end-on: in port p_for
+
+In addition to ``port`` resources a single clock-block resource is also required:
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: /* Clock-block declarations
+   :end-on: clock clk_audio_mclk
+
+Again, for the same reasoning as the master-clock ports, only one master-clock clock-blocks is required.
+
+
+Allocating hardware resources for lib_mic_array
+...............................................
+
+``lib_mic_array`` requires a single 8-bit port for PDM data from up to 8 microphones. This port must be declared
+as 32-bit buffered:
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: in buffered port:32 p_pdm_mics
+   :end-before: clock clk_pdm
+
+The microphones must be clocked by an audio related clock - typically 3.072MHz.
+
+The xCORE-200 Array Microphone Board expects the xCORE to divide down the audio master clock input (24.576MHz)
+and output the result to the microphones.
+
+Two ports for this purpose are declared as follows:
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: /* Lib_mic_array declarations
+   :end-before: in buffered
+
+
+Please see the ``lib_mic_array`` library documentation for full details.
+
+
+Other declarations
+..................
+
+``lib_xua`` currently requires the manual declaration of tables for the endpoint types for
+``lib_xud`` and the calling the main XUD function in a par (``XUD_Main()``).
+
+For a simple application the following endpoints are required:
+
+    - ``Control`` endpoint zero 
+    - ``Isochonous`` endpoint for each direction for audio data to/from the USB host
+
+These are declared as follows:
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: /* Endpoint type tables
+   :end-on: XUD_EpType epTypeTableIn
+
+Configuring lib_xua
+-------------------
+
+``lib_xua`` must be configured to enable support for PDM microphones.
+
+``lib_xua`` has many parameters than can be configured at build time, some examples include:
+
+    - Supported sample-rates
+    - Channel counts
+    - Audio Class version
+    - Product/Vendor ID's
+    - Various product strings
+    - Master clock frequency
+
+To enable PDM microphone support  ``XUA_NUM_PDM_MICS`` must be set to a non-zero value.  Setting this will cause the ``XUA_AudioHub``
+task to forward sample rate information and receive samples from the relevant microphone related tasks. 
+
+These parameters are set via defines in an optional ``xua_conf.h`` header file. For this simple application the 
+complete contents of this file are as follows:
+
+.. literalinclude:: xua_conf.h
+   :start-on: // Copyright
+   :end-on: #endif
+
+The application main() function
+-------------------------------
+
+The ``main()`` function sets up and runs the tasks in the application.
+
+Channel declarations
+....................
+
+Various channels are required in order to allow the required tasks to communicate. 
+These must first be declared:
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: /* Channels for lib_xud
+   :end-on: chan c_mic_pcm
+
+Standard ``lib_xua`` tasks
+..........................
+
+The rest of the ``main()`` function starts all of the tasks in parallel
+using the xC ``par`` construct.
+
+Firstly the standard ``lib_xua`` tasks are run on tile 1:  
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: par
+   :end-before: on tile[0]
+
+This code starts the low-level USB task, an Endpoint 0 task, an Audio buffering task and a task to handle 
+the audio I/O (``XUA_AudioHub``).
+
+Note, since there is no I2S functionality in this example the ``XUA_AudioHub`` task essentially just receives 
+samples from the PDM buffer task and forwards samples to the ``XUA_Buffer`` task for forwarding to the USB host. 
+
+Microphone related tasks
+........................
+
+Microphone related tasks are executed on tile 0 as follows:
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: Microphone related tasks
+   :end-before: return 0
+
+Two functions from ``lib_mic_array`` are used - a PDM receiver task (``mic_array_pdm_rx()``) and a decimation task (``mic_array_decimate_to_pcm_4ch()``).
+
+Each call to ``mic_array_decimate_to_pcm_4ch()`` can handle the decimation of up to 4 microphone signals. Since the xCORE-200 Array microphone
+board is equipped with seven microphones two instances of this task are run.
+
+The ``mic_array_pdm_rx()`` task expects the PDM microphone port to be clocked from the PDM clock.
+
+
+|appendix|
+|newpage|
+
+Demo Hardware Setup
+-------------------
+
+To run the demo, connect a USB cable to power the xCORE-200 MC Audio board 
+and plug the xTAG to the board and connect the xTAG USB cable to your
+development machine.
+
+.. figure:: images/hw_setup.*
+   :width: 80%
+
+   Hardware setup
+
+|newpage|
+
+Launching the demo application
+------------------------------
+
+Once the demo example has been built either from the command line using xmake or
+via the build mechanism of xTIMEcomposer studio it can be executed on the xCORE-200
+MC Audio board.
+
+Once built there will be a ``bin/`` directory within the project which contains
+the binary for the xCORE device. The xCORE binary has a XMOS standard .xe extension.
+
+Launching from the command line
+...............................
+
+From the command line you use the ``xrun`` tool to download and run the code
+on the xCORE device::
+
+  xrun --xscope bin/app_xua_simple.xe
+
+Once this command has executed the application will be running on the
+xCORE-200 MC Audio Board
+
+Launching from xTIMEcomposer Studio
+...................................
+
+From xTIMEcomposer Studio use the run mechanism to download code to xCORE device.
+Select the xCORE binary from the ``bin/`` directory, right click and go to Run
+Configurations. Double click on xCORE application to create a new run configuration,
+enable the xSCOPE I/O mode in the dialog box and then
+select Run.
+
+Once this command has executed the application will be running on the
+xCORE-200 MC Audio board.
+
+Running the application
+.......................
+
+Once running the device will be detected as a USB Audio device - note, Windows operating 
+systems may require a third party driver for correct operation 
+
+|newpage|
+
+References
+----------
+
+.. nopoints::
+
+  * XMOS Tools User Guide
+
+    http://www.xmos.com/published/xtimecomposer-user-guide
+
+  * XMOS xCORE Programming Guide
+
+    http://www.xmos.com/published/xmos-programming-guide
+
+  * XMOS lib_xua Library
+
+    http://www.xmos.com/support/libraries/lib_xua
+    
+  * XMOS lib_xud Library
+
+    http://www.xmos.com/support/libraries/lib_xud
+
+|newpage|
+
+Full source code listing
+------------------------
+
+Source code for main.xc
+.......................
+
+.. literalinclude:: app_xua_simple.xc
+  :largelisting:
+
+|newpage|

examples/AN00248_xua_example_pdm_mics/doc/rst/xdoc.conf

@@ -0,0 +1,2 @@
+XMOSNEWSTYLE=1
+SOURCE_INCLUDE_DIRS=../../src

examples/AN00248_xua_example_pdm_mics/src/app_xua_simple.xc

@@ -0,0 +1,120 @@
+// Copyright (c) 2017-2018, XMOS Ltd, All rights reserved
+
+/* A very simple *example* of a USB audio application (and as such is un-verified for production)
+ *
+ * It uses the main blocks from the lib_xua with the addition of PDM mic support using lib_mic_array 
+ *
+ * - No DFU
+ *
+ */
+
+#include <xs1.h>
+#include <platform.h>
+
+#include "xua.h"
+#include "xud_device.h"
+
+/* From lib_mic_array */
+#include "mic_array.h"
+
+/* Lib_mic_array declarations. Note, the defines derived from the xn file */
+in port p_pdm_clk                = PORT_PDM_CLK;               /* Port for PDM mic clock */
+in port p_pdm_mclk               = PORT_PDM_MCLK;              /* Master clock for PDM mics */
+
+in buffered port:32 p_pdm_mics   = PORT_PDM_DATA;              /* Port for PDM mic data */
+
+clock clk_pdm                    = on tile[0]: XS1_CLKBLK_1;   /* Clock-block for PDM mics */  
+
+
+/* Lib_xua port declarations. Note, the defines come from the xn file */
+in port p_mclk_in                = PORT_MCLK_IN;               /* Master clock for the audio IO tile */
+
+/* Resources for USB feedback */
+in port p_for_mclk_count         = PORT_MCLK_COUNT;            /* Extra port for counting master clock ticks */
+
+/* Clock-block declarations */
+clock clk_audio_mclk             = on tile[1]: XS1_CLKBLK_1;   /* Master clock */
+
+/* Endpoint type tables - informs XUD what the transfer types for each Endpoint in use and also
+ * if the endpoint wishes to be informed of USB bus resets */
+XUD_EpType epTypeTableOut[]   = {XUD_EPTYPE_CTL | XUD_STATUS_ENABLE, XUD_EPTYPE_ISO};
+XUD_EpType epTypeTableIn[]    = {XUD_EPTYPE_CTL | XUD_STATUS_ENABLE, XUD_EPTYPE_ISO};
+
+int main()
+{
+    /* Channels 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;
+
+    /* Array of channels for communication between PDM mic decimator task(s) and the XUA mic buffer task */
+    streaming chan c_ds_output[2];
+
+    /* Channel for communcation between XUA_AudioHub() and the XUA mic buffer task */
+    chan c_mic_pcm;
+
+    par
+    {
+        /* 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_BUS);
+        
+        /* Endpoint 0 core from lib_xua */
+        /* Note, since we are not using many features we pass in null for quite a few params.. */
+        on tile[1]: XUA_Endpoint0(c_ep_out[0], c_ep_in[0], c_aud_ctl, null, null, null, null);
+
+        on tile[1]: 
+        {
+            /* Connect master-clock clock-block to clock-block pin */
+            set_clock_src(clk_audio_mclk, p_mclk_in);             /* Clock clock-block from mclk pin */
+            set_port_clock(p_for_mclk_count, clk_audio_mclk);     /* Clock the "count" port from the clock block */
+                                                                  /* Note, AudioHub() will start the clock */
+          
+           par
+           {
+                /* Buffering task - 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) */
+                /* 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_mic_pcm);
+            }
+        }
+
+        /* Microphone related tasks */
+        on tile[0]:
+        {
+            streaming chan c_4x_pdm_mic_0;
+            streaming chan c_4x_pdm_mic_1;
+
+            configure_clock_src_divide(clk_pdm, p_pdm_mclk, 4);  /* Master clock to PDM clock divide */
+            configure_port_clock_output(p_pdm_clk, clk_pdm);
+            configure_in_port(p_pdm_mics, clk_pdm);
+            start_clock(clk_pdm);
+
+            par
+            {
+                /* PDM receive I/O task */
+                mic_array_pdm_rx(p_pdm_mics, c_4x_pdm_mic_0, c_4x_pdm_mic_1);
+                
+                /* Run two decimator tasks for 8 mics */
+                mic_array_decimate_to_pcm_4ch(c_4x_pdm_mic_0, c_ds_output[0], MIC_ARRAY_NO_INTERNAL_CHANS);
+                mic_array_decimate_to_pcm_4ch(c_4x_pdm_mic_1, c_ds_output[1], MIC_ARRAY_NO_INTERNAL_CHANS);
+
+                XUA_PdmBuffer(c_ds_output, c_mic_pcm);
+            }
+        }
+    }
+    
+    return 0;
+}
+
+

examples/AN00248_xua_example_pdm_mics/src/audiohw.xc

@@ -0,0 +1,30 @@
+// Copyright (c) 2017-2018, XMOS Ltd, All rights reserved
+
+#include <xs1.h>
+#include <assert.h>
+#include <platform.h>
+
+#include "xua.h"
+
+/* 0: DAC reset */
+/* 1: Ethernet Phy reset */
+on tile[1] : out port p_gpio = XS1_PORT_4F;
+
+void AudioHwInit()
+{
+    /* DAC in reset */
+    p_gpio <: 0;
+
+    return;    
+}
+
+/* Configures the external audio hardware for the required sample frequency */
+void AudioHwConfig(unsigned samFreq, unsigned mClk, unsigned dsdMode,
+    unsigned sampRes_DAC, unsigned sampRes_ADC)
+{
+    /* Note, without any config the Cirrus 2100 will output it's 24.576MHz ref clock
+       to the Aux output - which we will use for mclk */
+
+    return;
+}
+//:

examples/AN00248_xua_example_pdm_mics/src/mic_array_ref.xn

@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Network xmlns="http://www.xmos.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.xmos.com http://www.xmos.com" ManuallySpecifiedRouting="true">
+  <Type>Board</Type>
+  <Name>XS2 MC Audio</Name>
+  <Declarations>
+    <Declaration>tileref tile[2]</Declaration>
+    <Declaration>tileref usb_tile</Declaration>
+  </Declarations>
+  <Packages>
+    <Package id="0" Type="XS2-UnA-512-FB236">
+      <Nodes>
+        <Node Id="0" InPackageId="0" Type="XS2-L16A-512" Oscillator="24MHz" SystemFrequency="500MHz" referencefrequency="100MHz">
+          <Boot>
+            <Source Location="SPI:bootFlash"/>
+          </Boot>
+          <Tile Number="0" Reference="tile[0]">
+            <Port Location="XS1_PORT_1B" Name="PORT_SQI_CS"/>
+            <Port Location="XS1_PORT_1C" Name="PORT_SQI_SCLK"/>
+            <Port Location="XS1_PORT_4B" Name="PORT_SQI_SIO"/>
+
+            <!-- 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"/>
+            
+            <!-- LED ports -->
+            <Port Location="XS1_PORT_8C" Name="PORT_LED0_TO_7"/>
+            <Port Location="XS1_PORT_1K" Name="PORT_LED8"/>
+            <Port Location="XS1_PORT_1L" Name="PORT_LED9"/>
+            <Port Location="XS1_PORT_8D" Name="PORT_LED10_TO_12"/>
+            <Port Location="XS1_PORT_1P" Name="PORT_LED_OEN"/>
+            
+            <!-- Button ports -->
+            <Port Location="XS1_PORT_4A" Name="PORT_BUT_A_TO_D"/>
+            
+          </Tile>
+          
+          <Tile Number="1" Reference="tile[1]">
+            <Port Location="XS1_PORT_1H"  Name="PORT_USB_TX_READYIN"/>
+            <Port Location="XS1_PORT_1J"  Name="PORT_USB_CLK"/>
+            <Port Location="XS1_PORT_1K"  Name="PORT_USB_TX_READYOUT"/>
+            <Port Location="XS1_PORT_1I"  Name="PORT_USB_RX_READY"/>
+            <Port Location="XS1_PORT_1E"  Name="PORT_USB_FLAG0"/>
+            <Port Location="XS1_PORT_1F"  Name="PORT_USB_FLAG1"/>
+            <Port Location="XS1_PORT_1G"  Name="PORT_USB_FLAG2"/>
+            <Port Location="XS1_PORT_8A"  Name="PORT_USB_TXD"/>
+            <Port Location="XS1_PORT_8B"  Name="PORT_USB_RXD"/>
+
+            <!-- Audio Ports -->         
+            <Port Location="XS1_PORT_4D"  Name="PORT_PLL_REF"/>
+            <Port Location="XS1_PORT_1O"  Name="PORT_MCLK_IN"/>
+            <Port Location="XS1_PORT_1N"  Name="PORT_I2S_LRCLK"/>
+            <Port Location="XS1_PORT_1M"  Name="PORT_I2S_BCLK"/>
+            <Port Location="XS1_PORT_1P"  Name="PORT_I2S_DAC0"/>
+            <Port Location="XS1_PORT_4E"  Name="PORT_I2C"/>
+            <Port Location="XS1_PORT_16B" Name="PORT_MCLK_COUNT"/>              
+          </Tile>
+        </Node>
+        <Node Id="1" InPackageId="1" Type="periph:XS1-SU" Reference="usb_tile" Oscillator="24MHz">
+        </Node>
+      </Nodes>
+      <Links>
+        <Link Encoding="5wire">
+          <LinkEndpoint NodeId="0" Link="8" Delays="52clk,52clk"/>
+          <LinkEndpoint NodeId="1" Link="XL0" Delays="1clk,1clk"/>
+        </Link>
+      </Links>
+    </Package>
+  </Packages>
+  <Nodes>
+    <Node Id="2" Type="device:" RoutingId="0x8000">
+      <Service Id="0" Proto="xscope_host_data(chanend c);">
+        <Chanend Identifier="c" end="3"/>
+      </Service>
+    </Node>
+  </Nodes>
+  <Links>
+    <Link Encoding="2wire" Delays="4,4" Flags="XSCOPE">
+      <LinkEndpoint NodeId="0" Link="XL0"/>
+      <LinkEndpoint NodeId="2" Chanend="1"/>
+    </Link>
+  </Links>
+  <ExternalDevices>
+    <Device NodeId="0" Tile="0" Class="SQIFlash" Name="bootFlash" Type="S25FL116K">
+      <Attribute Name="PORT_SQI_CS" Value="PORT_SQI_CS"/>
+      <Attribute Name="PORT_SQI_SCLK"   Value="PORT_SQI_SCLK"/>
+      <Attribute Name="PORT_SQI_SIO"  Value="PORT_SQI_SIO"/>
+    </Device>
+  </ExternalDevices>
+  <JTAGChain>
+    <JTAGDevice NodeId="0"/>
+    <JTAGDevice NodeId="1"/>
+  </JTAGChain>
+</Network>

examples/AN00248_xua_example_pdm_mics/src/xua_conf.h

@@ -0,0 +1,30 @@
+// Copyright (c) 2017-2019, XMOS Ltd, All rights reserved
+
+#ifndef _XUA_CONF_H_ 
+#define _XUA_CONF_H_
+
+#define NUM_USB_CHAN_OUT 0
+#define NUM_USB_CHAN_IN 8
+#define I2S_CHANS_DAC 0
+#define I2S_CHANS_ADC 0
+#define MCLK_441 (512 * 44100)
+#define MCLK_48 (512 * 48000)
+#define MIN_FREQ 48000
+#define MAX_FREQ 48000
+
+#define EXCLUDE_USB_AUDIO_MAIN
+
+#define XUA_NUM_PDM_MICS 8
+#define VENDOR_STR "XMOS"
+#define VENDOR_ID 0x20B1
+#define PRODUCT_STR_A2 "XUA PDM Example"
+#define PRODUCT_STR_A1 "XUA PDM Example"
+#define PID_AUDIO_1 1
+#define PID_AUDIO_2 2
+#define AUDIO_CLASS 2
+#define AUDIO_CLASS_FALLBACK 0
+#define BCD_DEVICE 0x1234
+#define XUA_DFU_EN 0
+#define MIC_DUAL_ENABLED 0          // Use multi-threaded design
+
+#endif

examples/AN00248_xua_example_pdm_mics/src/xud_conf.h

@@ -0,0 +1,7 @@
+// Copyright (c) 2017-2018, XMOS Ltd, All rights reserved
+
+#include "xua_conf.h"
+
+/* TODO */
+#define XUD_UAC_NUM_USB_CHAN_OUT    NUM_USB_CHAN_OUT
+#define XUD_UAC_NUM_USB_CHAN_IN     NUM_USB_CHAN_IN

lib_xua/.cproject

@@ -0,0 +1,860 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<?fileVersion 4.0.0?><cproject storage_type_id="org.eclipse.cdt.core.XmlProjectDescriptionStorage">
+	<storageModule moduleId="org.eclipse.cdt.core.settings">
+		<cconfiguration id="com.xmos.cdt.toolchain.1285928753">
+			<storageModule buildSystemId="org.eclipse.cdt.managedbuilder.core.configurationDataProvider" id="com.xmos.cdt.toolchain.1285928753" moduleId="org.eclipse.cdt.core.settings" name="Default">
+				<externalSettings/>
+				<extensions>
+					<extension id="com.xmos.cdt.core.XdeErrorParser" point="org.eclipse.cdt.core.ErrorParser"/>
+					<extension id="org.eclipse.cdt.core.GCCErrorParser" point="org.eclipse.cdt.core.ErrorParser"/>
+					<extension id="org.eclipse.cdt.core.GNU_ELF" point="org.eclipse.cdt.core.BinaryParser"/>
+					<extension id="com.xmos.cdt.core.XEBinaryParser" point="org.eclipse.cdt.core.BinaryParser"/>
+				</extensions>
+			</storageModule>
+			<storageModule moduleId="cdtBuildSystem" version="4.0.0">
+				<configuration buildProperties="" description="" id="com.xmos.cdt.toolchain.1285928753" name="Default" parent="org.eclipse.cdt.build.core.emptycfg">
+					<folderInfo id="com.xmos.cdt.toolchain.1285928753.790908561" name="/" resourcePath="">
+						<toolChain id="com.xmos.cdt.toolchain.1969897956" name="com.xmos.cdt.toolchain" superClass="com.xmos.cdt.toolchain">
+							<targetPlatform archList="all" binaryParser="com.xmos.cdt.core.XEBinaryParser;org.eclipse.cdt.core.GNU_ELF" id="com.xmos.cdt.core.platform.1615568037" isAbstract="false" osList="linux,win32,macosx" superClass="com.xmos.cdt.core.platform"/>
+							<builder arguments="-f .makefile" id="com.xmos.cdt.builder.base.45159417" keepEnvironmentInBuildfile="false" managedBuildOn="false" superClass="com.xmos.cdt.builder.base">
+								<outputEntries>
+									<entry flags="VALUE_WORKSPACE_PATH" kind="outputPath" name="bin"/>
+								</outputEntries>
+							</builder>
+							<tool id="com.xmos.cdt.xc.compiler.404499215" name="com.xmos.cdt.xc.compiler" superClass="com.xmos.cdt.xc.compiler">
+								<option id="com.xmos.xc.compiler.option.defined.symbols.1492092903" name="com.xmos.xc.compiler.option.defined.symbols" superClass="com.xmos.xc.compiler.option.defined.symbols" valueType="definedSymbols">
+									<listOptionValue builtIn="false" value="__XC__=1"/>
+									<listOptionValue builtIn="false" value="__llvm__=1"/>
+									<listOptionValue builtIn="false" value="__ATOMIC_RELAXED=0"/>
+									<listOptionValue builtIn="false" value="__ATOMIC_CONSUME=1"/>
+									<listOptionValue builtIn="false" value="__ATOMIC_ACQUIRE=2"/>
+									<listOptionValue builtIn="false" value="__ATOMIC_RELEASE=3"/>
+									<listOptionValue builtIn="false" value="__ATOMIC_ACQ_REL=4"/>
+									<listOptionValue builtIn="false" value="__ATOMIC_SEQ_CST=5"/>
+									<listOptionValue builtIn="false" value="__PRAGMA_REDEFINE_EXTNAME=1"/>
+									<listOptionValue builtIn="false" value="__VERSION__=&quot;4.2.1"/>
+									<listOptionValue builtIn="false" value="__CONSTANT_CFSTRINGS__=1"/>
+									<listOptionValue builtIn="false" value="__ORDER_LITTLE_ENDIAN__=1234"/>
+									<listOptionValue builtIn="false" value="__ORDER_BIG_ENDIAN__=4321"/>
+									<listOptionValue builtIn="false" value="__ORDER_PDP_ENDIAN__=3412"/>
+									<listOptionValue builtIn="false" value="__BYTE_ORDER__=__ORDER_LITTLE_ENDIAN__"/>
+									<listOptionValue builtIn="false" value="__LITTLE_ENDIAN__=1"/>
+									<listOptionValue builtIn="false" value="_ILP32=1"/>
+									<listOptionValue builtIn="false" value="__ILP32__=1"/>
+									<listOptionValue builtIn="false" value="__CHAR_BIT__=8"/>
+									<listOptionValue builtIn="false" value="__SCHAR_MAX__=127"/>
+									<listOptionValue builtIn="false" value="__SHRT_MAX__=32767"/>
+									<listOptionValue builtIn="false" value="__INT_MAX__=2147483647"/>
+									<listOptionValue builtIn="false" value="__LONG_MAX__=2147483647L"/>
+									<listOptionValue builtIn="false" value="__LONG_LONG_MAX__=9223372036854775807LL"/>
+									<listOptionValue builtIn="false" value="__WCHAR_MAX__=255"/>
+									<listOptionValue builtIn="false" value="__INTMAX_MAX__=9223372036854775807LL"/>
+									<listOptionValue builtIn="false" value="__SIZE_MAX__=4294967295U"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_DOUBLE__=8"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_FLOAT__=4"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_INT__=4"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_LONG__=4"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_LONG_DOUBLE__=8"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_LONG_LONG__=8"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_POINTER__=4"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_SHORT__=2"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_PTRDIFF_T__=4"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_SIZE_T__=4"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_WCHAR_T__=1"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_WINT_T__=4"/>
+									<listOptionValue builtIn="false" value="__INTMAX_TYPE__=long"/>
+									<listOptionValue builtIn="false" value="__INTMAX_FMTd__=&quot;lld&quot;"/>
+									<listOptionValue builtIn="false" value="__INTMAX_FMTi__=&quot;lli&quot;"/>
+									<listOptionValue builtIn="false" value="__INTMAX_C_SUFFIX__=LL"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_TYPE__=long"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_FMTo__=&quot;llo&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_FMTu__=&quot;llu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_FMTx__=&quot;llx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_FMTX__=&quot;llX&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_C_SUFFIX__=ULL"/>
+									<listOptionValue builtIn="false" value="__INTMAX_WIDTH__=64"/>
+									<listOptionValue builtIn="false" value="__PTRDIFF_TYPE__=int"/>
+									<listOptionValue builtIn="false" value="__PTRDIFF_FMTd__=&quot;d&quot;"/>
+									<listOptionValue builtIn="false" value="__PTRDIFF_FMTi__=&quot;i&quot;"/>
+									<listOptionValue builtIn="false" value="__PTRDIFF_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__INTPTR_TYPE__=int"/>
+									<listOptionValue builtIn="false" value="__INTPTR_FMTd__=&quot;d&quot;"/>
+									<listOptionValue builtIn="false" value="__INTPTR_FMTi__=&quot;i&quot;"/>
+									<listOptionValue builtIn="false" value="__INTPTR_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__SIZE_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__SIZE_FMTo__=&quot;o&quot;"/>
+									<listOptionValue builtIn="false" value="__SIZE_FMTu__=&quot;u&quot;"/>
+									<listOptionValue builtIn="false" value="__SIZE_FMTx__=&quot;x&quot;"/>
+									<listOptionValue builtIn="false" value="__SIZE_FMTX__=&quot;X&quot;"/>
+									<listOptionValue builtIn="false" value="__SIZE_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__WCHAR_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__WCHAR_WIDTH__=8"/>
+									<listOptionValue builtIn="false" value="__WINT_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__WINT_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__SIG_ATOMIC_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__SIG_ATOMIC_MAX__=2147483647"/>
+									<listOptionValue builtIn="false" value="__CHAR16_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__CHAR32_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__FLT_DENORM_MIN__=1.40129846e-45F"/>
+									<listOptionValue builtIn="false" value="__FLT_HAS_DENORM__=1"/>
+									<listOptionValue builtIn="false" value="__FLT_DIG__=6"/>
+									<listOptionValue builtIn="false" value="__FLT_EPSILON__=1.19209290e-7F"/>
+									<listOptionValue builtIn="false" value="__FLT_HAS_INFINITY__=1"/>
+									<listOptionValue builtIn="false" value="__FLT_HAS_QUIET_NAN__=1"/>
+									<listOptionValue builtIn="false" value="__FLT_MANT_DIG__=24"/>
+									<listOptionValue builtIn="false" value="__FLT_MAX_10_EXP__=38"/>
+									<listOptionValue builtIn="false" value="__FLT_MAX_EXP__=128"/>
+									<listOptionValue builtIn="false" value="__FLT_MAX__=3.40282347e+38F"/>
+									<listOptionValue builtIn="false" value="__FLT_MIN_10_EXP__=(-37)"/>
+									<listOptionValue builtIn="false" value="__FLT_MIN_EXP__=(-125)"/>
+									<listOptionValue builtIn="false" value="__FLT_MIN__=1.17549435e-38F"/>
+									<listOptionValue builtIn="false" value="__DBL_DENORM_MIN__=4.9406564584124654e-324"/>
+									<listOptionValue builtIn="false" value="__DBL_HAS_DENORM__=1"/>
+									<listOptionValue builtIn="false" value="__DBL_DIG__=15"/>
+									<listOptionValue builtIn="false" value="__DBL_EPSILON__=2.2204460492503131e-16"/>
+									<listOptionValue builtIn="false" value="__DBL_HAS_INFINITY__=1"/>
+									<listOptionValue builtIn="false" value="__DBL_HAS_QUIET_NAN__=1"/>
+									<listOptionValue builtIn="false" value="__DBL_MANT_DIG__=53"/>
+									<listOptionValue builtIn="false" value="__DBL_MAX_10_EXP__=308"/>
+									<listOptionValue builtIn="false" value="__DBL_MAX_EXP__=1024"/>
+									<listOptionValue builtIn="false" value="__DBL_MAX__=1.7976931348623157e+308"/>
+									<listOptionValue builtIn="false" value="__DBL_MIN_10_EXP__=(-307)"/>
+									<listOptionValue builtIn="false" value="__DBL_MIN_EXP__=(-1021)"/>
+									<listOptionValue builtIn="false" value="__DBL_MIN__=2.2250738585072014e-308"/>
+									<listOptionValue builtIn="false" value="__LDBL_DENORM_MIN__=4.9406564584124654e-324L"/>
+									<listOptionValue builtIn="false" value="__LDBL_HAS_DENORM__=1"/>
+									<listOptionValue builtIn="false" value="__LDBL_DIG__=15"/>
+									<listOptionValue builtIn="false" value="__LDBL_EPSILON__=2.2204460492503131e-16L"/>
+									<listOptionValue builtIn="false" value="__LDBL_HAS_INFINITY__=1"/>
+									<listOptionValue builtIn="false" value="__LDBL_HAS_QUIET_NAN__=1"/>
+									<listOptionValue builtIn="false" value="__LDBL_MANT_DIG__=53"/>
+									<listOptionValue builtIn="false" value="__LDBL_MAX_10_EXP__=308"/>
+									<listOptionValue builtIn="false" value="__LDBL_MAX_EXP__=1024"/>
+									<listOptionValue builtIn="false" value="__LDBL_MAX__=1.7976931348623157e+308L"/>
+									<listOptionValue builtIn="false" value="__LDBL_MIN_10_EXP__=(-307)"/>
+									<listOptionValue builtIn="false" value="__LDBL_MIN_EXP__=(-1021)"/>
+									<listOptionValue builtIn="false" value="__LDBL_MIN__=2.2250738585072014e-308L"/>
+									<listOptionValue builtIn="false" value="__POINTER_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__CHAR_UNSIGNED__=1"/>
+									<listOptionValue builtIn="false" value="__WCHAR_UNSIGNED__=1"/>
+									<listOptionValue builtIn="false" value="__WINT_UNSIGNED__=1"/>
+									<listOptionValue builtIn="false" value="__INT8_TYPE__=signed"/>
+									<listOptionValue builtIn="false" value="__INT8_FMTd__=&quot;hhd&quot;"/>
+									<listOptionValue builtIn="false" value="__INT8_FMTi__=&quot;hhi&quot;"/>
+									<listOptionValue builtIn="false" value="__INT8_C_SUFFIX__"/>
+									<listOptionValue builtIn="false" value="__INT16_TYPE__=short"/>
+									<listOptionValue builtIn="false" value="__INT16_FMTd__=&quot;hd&quot;"/>
+									<listOptionValue builtIn="false" value="__INT16_FMTi__=&quot;hi&quot;"/>
+									<listOptionValue builtIn="false" value="__INT16_C_SUFFIX__"/>
+									<listOptionValue builtIn="false" value="__INT32_TYPE__=int"/>
+									<listOptionValue builtIn="false" value="__INT32_FMTd__=&quot;d&quot;"/>
+									<listOptionValue builtIn="false" value="__INT32_FMTi__=&quot;i&quot;"/>
+									<listOptionValue builtIn="false" value="__INT32_C_SUFFIX__"/>
+									<listOptionValue builtIn="false" value="__INT64_TYPE__=long"/>
+									<listOptionValue builtIn="false" value="__INT64_FMTd__=&quot;lld&quot;"/>
+									<listOptionValue builtIn="false" value="__INT64_FMTi__=&quot;lli&quot;"/>
+									<listOptionValue builtIn="false" value="__INT64_C_SUFFIX__=LL"/>
+									<listOptionValue builtIn="false" value="__USER_LABEL_PREFIX__=_"/>
+									<listOptionValue builtIn="false" value="__FINITE_MATH_ONLY__=0"/>
+									<listOptionValue builtIn="false" value="__FLT_EVAL_METHOD__=0"/>
+									<listOptionValue builtIn="false" value="__FLT_RADIX__=2"/>
+									<listOptionValue builtIn="false" value="__DECIMAL_DIG__=17"/>
+									<listOptionValue builtIn="false" value="__xcore__=1"/>
+									<listOptionValue builtIn="false" value="__XS1B__=1"/>
+									<listOptionValue builtIn="false" value="__STDC_HOSTED__=1"/>
+									<listOptionValue builtIn="false" value="__STDC_UTF_16__=1"/>
+									<listOptionValue builtIn="false" value="__STDC_UTF_32__=1"/>
+									<listOptionValue builtIn="false" value="XCC_VERSION_YEAR=14"/>
+									<listOptionValue builtIn="false" value="XCC_VERSION_MONTH=3"/>
+									<listOptionValue builtIn="false" value="XCC_VERSION_MAJOR=1403"/>
+									<listOptionValue builtIn="false" value="XCC_VERSION_MINOR=2"/>
+									<listOptionValue builtIn="false" value="__XCC_HAVE_FLOAT__=1"/>
+									<listOptionValue builtIn="false" value="_XSCOPE_PROBES_INCLUDE_FILE=&quot;/var/folders/0l/8jd0xy095ps890m302j532580000h5/T//cc8JvR3b.h&quot;"/>
+								</option>
+								<option id="com.xmos.xc.compiler.option.include.paths.834699451" name="com.xmos.xc.compiler.option.include.paths" superClass="com.xmos.xc.compiler.option.include.paths" valueType="includePath">
+									<listOptionValue builtIn="false" value="&quot;${XMOS_TOOL_PATH}/target/include/xc&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${XMOS_TOOL_PATH}/target/include&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${XMOS_TOOL_PATH}/target/include/clang&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_logging/doc}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/doc/rst/images}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src/user/client}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src/user/class}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src/core/included}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src/core}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_logging/doc/rst}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_logging/src}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_logging}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src/user/control}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_logging/api}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/doc/rst}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/api}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/doc}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src/user}&quot;"/>
+								</option>
+								<inputType id="com.xmos.cdt.xc.compiler.input.2062798368" name="XC" superClass="com.xmos.cdt.xc.compiler.input"/>
+							</tool>
+							<tool id="com.xmos.cdt.c.compiler.1931691289" name="com.xmos.cdt.c.compiler" superClass="com.xmos.cdt.c.compiler">
+								<option id="com.xmos.c.compiler.option.defined.symbols.534062814" name="com.xmos.c.compiler.option.defined.symbols" superClass="com.xmos.c.compiler.option.defined.symbols" valueType="definedSymbols">
+									<listOptionValue builtIn="false" value="__llvm__=1"/>
+									<listOptionValue builtIn="false" value="__clang__=1"/>
+									<listOptionValue builtIn="false" value="__clang_major__=3"/>
+									<listOptionValue builtIn="false" value="__clang_minor__=6"/>
+									<listOptionValue builtIn="false" value="__clang_patchlevel__=0"/>
+									<listOptionValue builtIn="false" value="__clang_version__=&quot;3.6.0"/>
+									<listOptionValue builtIn="false" value="__GNUC_MINOR__=2"/>
+									<listOptionValue builtIn="false" value="__GNUC_PATCHLEVEL__=1"/>
+									<listOptionValue builtIn="false" value="__GNUC__=4"/>
+									<listOptionValue builtIn="false" value="__GXX_ABI_VERSION=1002"/>
+									<listOptionValue builtIn="false" value="__ATOMIC_RELAXED=0"/>
+									<listOptionValue builtIn="false" value="__ATOMIC_CONSUME=1"/>
+									<listOptionValue builtIn="false" value="__ATOMIC_ACQUIRE=2"/>
+									<listOptionValue builtIn="false" value="__ATOMIC_RELEASE=3"/>
+									<listOptionValue builtIn="false" value="__ATOMIC_ACQ_REL=4"/>
+									<listOptionValue builtIn="false" value="__ATOMIC_SEQ_CST=5"/>
+									<listOptionValue builtIn="false" value="__PRAGMA_REDEFINE_EXTNAME=1"/>
+									<listOptionValue builtIn="false" value="__VERSION__=&quot;4.2.1"/>
+									<listOptionValue builtIn="false" value="__CONSTANT_CFSTRINGS__=1"/>
+									<listOptionValue builtIn="false" value="__GXX_RTTI=1"/>
+									<listOptionValue builtIn="false" value="__ORDER_LITTLE_ENDIAN__=1234"/>
+									<listOptionValue builtIn="false" value="__ORDER_BIG_ENDIAN__=4321"/>
+									<listOptionValue builtIn="false" value="__ORDER_PDP_ENDIAN__=3412"/>
+									<listOptionValue builtIn="false" value="__BYTE_ORDER__=__ORDER_LITTLE_ENDIAN__"/>
+									<listOptionValue builtIn="false" value="__LITTLE_ENDIAN__=1"/>
+									<listOptionValue builtIn="false" value="_ILP32=1"/>
+									<listOptionValue builtIn="false" value="__ILP32__=1"/>
+									<listOptionValue builtIn="false" value="__CHAR_BIT__=8"/>
+									<listOptionValue builtIn="false" value="__SCHAR_MAX__=127"/>
+									<listOptionValue builtIn="false" value="__SHRT_MAX__=32767"/>
+									<listOptionValue builtIn="false" value="__INT_MAX__=2147483647"/>
+									<listOptionValue builtIn="false" value="__LONG_MAX__=2147483647L"/>
+									<listOptionValue builtIn="false" value="__LONG_LONG_MAX__=9223372036854775807LL"/>
+									<listOptionValue builtIn="false" value="__WCHAR_MAX__=255"/>
+									<listOptionValue builtIn="false" value="__INTMAX_MAX__=9223372036854775807LL"/>
+									<listOptionValue builtIn="false" value="__SIZE_MAX__=4294967295U"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_MAX__=18446744073709551615ULL"/>
+									<listOptionValue builtIn="false" value="__PTRDIFF_MAX__=2147483647"/>
+									<listOptionValue builtIn="false" value="__INTPTR_MAX__=2147483647"/>
+									<listOptionValue builtIn="false" value="__UINTPTR_MAX__=4294967295U"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_DOUBLE__=8"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_FLOAT__=4"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_INT__=4"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_LONG__=4"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_LONG_DOUBLE__=8"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_LONG_LONG__=8"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_POINTER__=4"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_SHORT__=2"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_PTRDIFF_T__=4"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_SIZE_T__=4"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_WCHAR_T__=1"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_WINT_T__=4"/>
+									<listOptionValue builtIn="false" value="__INTMAX_TYPE__=long"/>
+									<listOptionValue builtIn="false" value="__INTMAX_FMTd__=&quot;lld&quot;"/>
+									<listOptionValue builtIn="false" value="__INTMAX_FMTi__=&quot;lli&quot;"/>
+									<listOptionValue builtIn="false" value="__INTMAX_C_SUFFIX__=LL"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_TYPE__=long"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_FMTo__=&quot;llo&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_FMTu__=&quot;llu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_FMTx__=&quot;llx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_FMTX__=&quot;llX&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_C_SUFFIX__=ULL"/>
+									<listOptionValue builtIn="false" value="__INTMAX_WIDTH__=64"/>
+									<listOptionValue builtIn="false" value="__PTRDIFF_TYPE__=int"/>
+									<listOptionValue builtIn="false" value="__PTRDIFF_FMTd__=&quot;d&quot;"/>
+									<listOptionValue builtIn="false" value="__PTRDIFF_FMTi__=&quot;i&quot;"/>
+									<listOptionValue builtIn="false" value="__PTRDIFF_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__INTPTR_TYPE__=int"/>
+									<listOptionValue builtIn="false" value="__INTPTR_FMTd__=&quot;d&quot;"/>
+									<listOptionValue builtIn="false" value="__INTPTR_FMTi__=&quot;i&quot;"/>
+									<listOptionValue builtIn="false" value="__INTPTR_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__SIZE_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__SIZE_FMTo__=&quot;o&quot;"/>
+									<listOptionValue builtIn="false" value="__SIZE_FMTu__=&quot;u&quot;"/>
+									<listOptionValue builtIn="false" value="__SIZE_FMTx__=&quot;x&quot;"/>
+									<listOptionValue builtIn="false" value="__SIZE_FMTX__=&quot;X&quot;"/>
+									<listOptionValue builtIn="false" value="__SIZE_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__WCHAR_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__WCHAR_WIDTH__=8"/>
+									<listOptionValue builtIn="false" value="__WINT_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__WINT_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__SIG_ATOMIC_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__SIG_ATOMIC_MAX__=2147483647"/>
+									<listOptionValue builtIn="false" value="__CHAR16_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__CHAR32_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_WIDTH__=64"/>
+									<listOptionValue builtIn="false" value="__UINTPTR_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINTPTR_FMTo__=&quot;o&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTPTR_FMTu__=&quot;u&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTPTR_FMTx__=&quot;x&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTPTR_FMTX__=&quot;X&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTPTR_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__FLT_DENORM_MIN__=1.40129846e-45F"/>
+									<listOptionValue builtIn="false" value="__FLT_HAS_DENORM__=1"/>
+									<listOptionValue builtIn="false" value="__FLT_DIG__=6"/>
+									<listOptionValue builtIn="false" value="__FLT_EPSILON__=1.19209290e-7F"/>
+									<listOptionValue builtIn="false" value="__FLT_HAS_INFINITY__=1"/>
+									<listOptionValue builtIn="false" value="__FLT_HAS_QUIET_NAN__=1"/>
+									<listOptionValue builtIn="false" value="__FLT_MANT_DIG__=24"/>
+									<listOptionValue builtIn="false" value="__FLT_MAX_10_EXP__=38"/>
+									<listOptionValue builtIn="false" value="__FLT_MAX_EXP__=128"/>
+									<listOptionValue builtIn="false" value="__FLT_MAX__=3.40282347e+38F"/>
+									<listOptionValue builtIn="false" value="__FLT_MIN_10_EXP__=(-37)"/>
+									<listOptionValue builtIn="false" value="__FLT_MIN_EXP__=(-125)"/>
+									<listOptionValue builtIn="false" value="__FLT_MIN__=1.17549435e-38F"/>
+									<listOptionValue builtIn="false" value="__DBL_DENORM_MIN__=4.9406564584124654e-324"/>
+									<listOptionValue builtIn="false" value="__DBL_HAS_DENORM__=1"/>
+									<listOptionValue builtIn="false" value="__DBL_DIG__=15"/>
+									<listOptionValue builtIn="false" value="__DBL_EPSILON__=2.2204460492503131e-16"/>
+									<listOptionValue builtIn="false" value="__DBL_HAS_INFINITY__=1"/>
+									<listOptionValue builtIn="false" value="__DBL_HAS_QUIET_NAN__=1"/>
+									<listOptionValue builtIn="false" value="__DBL_MANT_DIG__=53"/>
+									<listOptionValue builtIn="false" value="__DBL_MAX_10_EXP__=308"/>
+									<listOptionValue builtIn="false" value="__DBL_MAX_EXP__=1024"/>
+									<listOptionValue builtIn="false" value="__DBL_MAX__=1.7976931348623157e+308"/>
+									<listOptionValue builtIn="false" value="__DBL_MIN_10_EXP__=(-307)"/>
+									<listOptionValue builtIn="false" value="__DBL_MIN_EXP__=(-1021)"/>
+									<listOptionValue builtIn="false" value="__DBL_MIN__=2.2250738585072014e-308"/>
+									<listOptionValue builtIn="false" value="__LDBL_DENORM_MIN__=4.9406564584124654e-324L"/>
+									<listOptionValue builtIn="false" value="__LDBL_HAS_DENORM__=1"/>
+									<listOptionValue builtIn="false" value="__LDBL_DIG__=15"/>
+									<listOptionValue builtIn="false" value="__LDBL_EPSILON__=2.2204460492503131e-16L"/>
+									<listOptionValue builtIn="false" value="__LDBL_HAS_INFINITY__=1"/>
+									<listOptionValue builtIn="false" value="__LDBL_HAS_QUIET_NAN__=1"/>
+									<listOptionValue builtIn="false" value="__LDBL_MANT_DIG__=53"/>
+									<listOptionValue builtIn="false" value="__LDBL_MAX_10_EXP__=308"/>
+									<listOptionValue builtIn="false" value="__LDBL_MAX_EXP__=1024"/>
+									<listOptionValue builtIn="false" value="__LDBL_MAX__=1.7976931348623157e+308L"/>
+									<listOptionValue builtIn="false" value="__LDBL_MIN_10_EXP__=(-307)"/>
+									<listOptionValue builtIn="false" value="__LDBL_MIN_EXP__=(-1021)"/>
+									<listOptionValue builtIn="false" value="__LDBL_MIN__=2.2250738585072014e-308L"/>
+									<listOptionValue builtIn="false" value="__POINTER_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__CHAR_UNSIGNED__=1"/>
+									<listOptionValue builtIn="false" value="__WCHAR_UNSIGNED__=1"/>
+									<listOptionValue builtIn="false" value="__WINT_UNSIGNED__=1"/>
+									<listOptionValue builtIn="false" value="__INT8_TYPE__=signed"/>
+									<listOptionValue builtIn="false" value="__INT8_FMTd__=&quot;hhd&quot;"/>
+									<listOptionValue builtIn="false" value="__INT8_FMTi__=&quot;hhi&quot;"/>
+									<listOptionValue builtIn="false" value="__INT8_C_SUFFIX__"/>
+									<listOptionValue builtIn="false" value="__INT16_TYPE__=short"/>
+									<listOptionValue builtIn="false" value="__INT16_FMTd__=&quot;hd&quot;"/>
+									<listOptionValue builtIn="false" value="__INT16_FMTi__=&quot;hi&quot;"/>
+									<listOptionValue builtIn="false" value="__INT16_C_SUFFIX__"/>
+									<listOptionValue builtIn="false" value="__INT32_TYPE__=int"/>
+									<listOptionValue builtIn="false" value="__INT32_FMTd__=&quot;d&quot;"/>
+									<listOptionValue builtIn="false" value="__INT32_FMTi__=&quot;i&quot;"/>
+									<listOptionValue builtIn="false" value="__INT32_C_SUFFIX__"/>
+									<listOptionValue builtIn="false" value="__INT64_TYPE__=long"/>
+									<listOptionValue builtIn="false" value="__INT64_FMTd__=&quot;lld&quot;"/>
+									<listOptionValue builtIn="false" value="__INT64_FMTi__=&quot;lli&quot;"/>
+									<listOptionValue builtIn="false" value="__INT64_C_SUFFIX__=LL"/>
+									<listOptionValue builtIn="false" value="__UINT8_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINT8_FMTo__=&quot;hho&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT8_FMTu__=&quot;hhu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT8_FMTx__=&quot;hhx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT8_FMTX__=&quot;hhX&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT8_C_SUFFIX__"/>
+									<listOptionValue builtIn="false" value="__UINT8_MAX__=255"/>
+									<listOptionValue builtIn="false" value="__INT8_MAX__=127"/>
+									<listOptionValue builtIn="false" value="__UINT16_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINT16_FMTo__=&quot;ho&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT16_FMTu__=&quot;hu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT16_FMTx__=&quot;hx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT16_FMTX__=&quot;hX&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT16_C_SUFFIX__"/>
+									<listOptionValue builtIn="false" value="__UINT16_MAX__=65535"/>
+									<listOptionValue builtIn="false" value="__INT16_MAX__=32767"/>
+									<listOptionValue builtIn="false" value="__UINT32_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINT32_FMTo__=&quot;o&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT32_FMTu__=&quot;u&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT32_FMTx__=&quot;x&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT32_FMTX__=&quot;X&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT32_C_SUFFIX__=U"/>
+									<listOptionValue builtIn="false" value="__UINT32_MAX__=4294967295U"/>
+									<listOptionValue builtIn="false" value="__INT32_MAX__=2147483647"/>
+									<listOptionValue builtIn="false" value="__UINT64_TYPE__=long"/>
+									<listOptionValue builtIn="false" value="__UINT64_FMTo__=&quot;llo&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT64_FMTu__=&quot;llu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT64_FMTx__=&quot;llx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT64_FMTX__=&quot;llX&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT64_C_SUFFIX__=ULL"/>
+									<listOptionValue builtIn="false" value="__UINT64_MAX__=18446744073709551615ULL"/>
+									<listOptionValue builtIn="false" value="__INT64_MAX__=9223372036854775807LL"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST8_TYPE__=signed"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST8_MAX__=127"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST8_FMTd__=&quot;hhd&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST8_FMTi__=&quot;hhi&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST8_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST8_MAX__=255"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST8_FMTo__=&quot;hho&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST8_FMTu__=&quot;hhu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST8_FMTx__=&quot;hhx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST8_FMTX__=&quot;hhX&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST16_TYPE__=short"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST16_MAX__=32767"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST16_FMTd__=&quot;hd&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST16_FMTi__=&quot;hi&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST16_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST16_MAX__=65535"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST16_FMTo__=&quot;ho&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST16_FMTu__=&quot;hu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST16_FMTx__=&quot;hx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST16_FMTX__=&quot;hX&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST32_TYPE__=int"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST32_MAX__=2147483647"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST32_FMTd__=&quot;d&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST32_FMTi__=&quot;i&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST32_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST32_MAX__=4294967295U"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST32_FMTo__=&quot;o&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST32_FMTu__=&quot;u&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST32_FMTx__=&quot;x&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST32_FMTX__=&quot;X&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST64_TYPE__=long"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST64_MAX__=9223372036854775807LL"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST64_FMTd__=&quot;lld&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST64_FMTi__=&quot;lli&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST64_TYPE__=long"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST64_MAX__=18446744073709551615ULL"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST64_FMTo__=&quot;llo&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST64_FMTu__=&quot;llu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST64_FMTx__=&quot;llx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST64_FMTX__=&quot;llX&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_FAST8_TYPE__=signed"/>
+									<listOptionValue builtIn="false" value="__INT_FAST8_MAX__=127"/>
+									<listOptionValue builtIn="false" value="__INT_FAST8_FMTd__=&quot;hhd&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_FAST8_FMTi__=&quot;hhi&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST8_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST8_MAX__=255"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST8_FMTo__=&quot;hho&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST8_FMTu__=&quot;hhu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST8_FMTx__=&quot;hhx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST8_FMTX__=&quot;hhX&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_FAST16_TYPE__=short"/>
+									<listOptionValue builtIn="false" value="__INT_FAST16_MAX__=32767"/>
+									<listOptionValue builtIn="false" value="__INT_FAST16_FMTd__=&quot;hd&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_FAST16_FMTi__=&quot;hi&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST16_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST16_MAX__=65535"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST16_FMTo__=&quot;ho&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST16_FMTu__=&quot;hu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST16_FMTx__=&quot;hx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST16_FMTX__=&quot;hX&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_FAST32_TYPE__=int"/>
+									<listOptionValue builtIn="false" value="__INT_FAST32_MAX__=2147483647"/>
+									<listOptionValue builtIn="false" value="__INT_FAST32_FMTd__=&quot;d&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_FAST32_FMTi__=&quot;i&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST32_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST32_MAX__=4294967295U"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST32_FMTo__=&quot;o&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST32_FMTu__=&quot;u&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST32_FMTx__=&quot;x&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST32_FMTX__=&quot;X&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_FAST64_TYPE__=long"/>
+									<listOptionValue builtIn="false" value="__INT_FAST64_MAX__=9223372036854775807LL"/>
+									<listOptionValue builtIn="false" value="__INT_FAST64_FMTd__=&quot;lld&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_FAST64_FMTi__=&quot;lli&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST64_TYPE__=long"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST64_MAX__=18446744073709551615ULL"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST64_FMTo__=&quot;llo&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST64_FMTu__=&quot;llu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST64_FMTx__=&quot;llx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST64_FMTX__=&quot;llX&quot;"/>
+									<listOptionValue builtIn="false" value="__USER_LABEL_PREFIX__=_"/>
+									<listOptionValue builtIn="false" value="__FINITE_MATH_ONLY__=0"/>
+									<listOptionValue builtIn="false" value="__GNUC_STDC_INLINE__=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_TEST_AND_SET_TRUEVAL=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_BOOL_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_CHAR_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_CHAR16_T_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_CHAR32_T_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_WCHAR_T_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_SHORT_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_INT_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_LONG_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_LLONG_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_POINTER_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__NO_INLINE__=1"/>
+									<listOptionValue builtIn="false" value="__FLT_EVAL_METHOD__=0"/>
+									<listOptionValue builtIn="false" value="__FLT_RADIX__=2"/>
+									<listOptionValue builtIn="false" value="__DECIMAL_DIG__=17"/>
+									<listOptionValue builtIn="false" value="__xcore__=1"/>
+									<listOptionValue builtIn="false" value="__XS1B__=1"/>
+									<listOptionValue builtIn="false" value="__STDC__=1"/>
+									<listOptionValue builtIn="false" value="__STDC_HOSTED__=1"/>
+									<listOptionValue builtIn="false" value="__STDC_VERSION__=199901L"/>
+									<listOptionValue builtIn="false" value="__STDC_UTF_16__=1"/>
+									<listOptionValue builtIn="false" value="__STDC_UTF_32__=1"/>
+									<listOptionValue builtIn="false" value="XCC_VERSION_YEAR=14"/>
+									<listOptionValue builtIn="false" value="XCC_VERSION_MONTH=3"/>
+									<listOptionValue builtIn="false" value="XCC_VERSION_MAJOR=1403"/>
+									<listOptionValue builtIn="false" value="XCC_VERSION_MINOR=2"/>
+									<listOptionValue builtIn="false" value="__XCC_HAVE_FLOAT__=1"/>
+									<listOptionValue builtIn="false" value="_XSCOPE_PROBES_INCLUDE_FILE=&quot;/var/folders/0l/8jd0xy095ps890m302j532580000h5/T//ccVdKn1b.h&quot;"/>
+								</option>
+								<option id="com.xmos.c.compiler.option.include.paths.1661660573" name="com.xmos.c.compiler.option.include.paths" superClass="com.xmos.c.compiler.option.include.paths" valueType="includePath">
+									<listOptionValue builtIn="false" value="&quot;${XMOS_TOOL_PATH}/target/include&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${XMOS_TOOL_PATH}/target/include/clang&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_logging/doc}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/doc/rst/images}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src/user/client}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src/user/class}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src/core/included}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src/core}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_logging/doc/rst}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_logging/src}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_logging}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src/user/control}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_logging/api}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/doc/rst}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/api}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/doc}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src/user}&quot;"/>
+								</option>
+								<inputType id="com.xmos.cdt.c.compiler.input.c.1188610778" name="C" superClass="com.xmos.cdt.c.compiler.input.c"/>
+							</tool>
+							<tool id="com.xmos.cdt.cxx.compiler.1403352573" name="com.xmos.cdt.cxx.compiler" superClass="com.xmos.cdt.cxx.compiler">
+								<option id="com.xmos.cxx.compiler.option.defined.symbols.665306874" name="com.xmos.cxx.compiler.option.defined.symbols" superClass="com.xmos.cxx.compiler.option.defined.symbols" valueType="definedSymbols">
+									<listOptionValue builtIn="false" value="__llvm__=1"/>
+									<listOptionValue builtIn="false" value="__clang__=1"/>
+									<listOptionValue builtIn="false" value="__clang_major__=3"/>
+									<listOptionValue builtIn="false" value="__clang_minor__=6"/>
+									<listOptionValue builtIn="false" value="__clang_patchlevel__=0"/>
+									<listOptionValue builtIn="false" value="__clang_version__=&quot;3.6.0"/>
+									<listOptionValue builtIn="false" value="__GNUC_MINOR__=2"/>
+									<listOptionValue builtIn="false" value="__GNUC_PATCHLEVEL__=1"/>
+									<listOptionValue builtIn="false" value="__GNUC__=4"/>
+									<listOptionValue builtIn="false" value="__GXX_ABI_VERSION=1002"/>
+									<listOptionValue builtIn="false" value="__ATOMIC_RELAXED=0"/>
+									<listOptionValue builtIn="false" value="__ATOMIC_CONSUME=1"/>
+									<listOptionValue builtIn="false" value="__ATOMIC_ACQUIRE=2"/>
+									<listOptionValue builtIn="false" value="__ATOMIC_RELEASE=3"/>
+									<listOptionValue builtIn="false" value="__ATOMIC_ACQ_REL=4"/>
+									<listOptionValue builtIn="false" value="__ATOMIC_SEQ_CST=5"/>
+									<listOptionValue builtIn="false" value="__PRAGMA_REDEFINE_EXTNAME=1"/>
+									<listOptionValue builtIn="false" value="__VERSION__=&quot;4.2.1"/>
+									<listOptionValue builtIn="false" value="__CONSTANT_CFSTRINGS__=1"/>
+									<listOptionValue builtIn="false" value="__GXX_RTTI=1"/>
+									<listOptionValue builtIn="false" value="__DEPRECATED=1"/>
+									<listOptionValue builtIn="false" value="__GNUG__=4"/>
+									<listOptionValue builtIn="false" value="__GXX_WEAK__=1"/>
+									<listOptionValue builtIn="false" value="__private_extern__=extern"/>
+									<listOptionValue builtIn="false" value="__ORDER_LITTLE_ENDIAN__=1234"/>
+									<listOptionValue builtIn="false" value="__ORDER_BIG_ENDIAN__=4321"/>
+									<listOptionValue builtIn="false" value="__ORDER_PDP_ENDIAN__=3412"/>
+									<listOptionValue builtIn="false" value="__BYTE_ORDER__=__ORDER_LITTLE_ENDIAN__"/>
+									<listOptionValue builtIn="false" value="__LITTLE_ENDIAN__=1"/>
+									<listOptionValue builtIn="false" value="_ILP32=1"/>
+									<listOptionValue builtIn="false" value="__ILP32__=1"/>
+									<listOptionValue builtIn="false" value="__CHAR_BIT__=8"/>
+									<listOptionValue builtIn="false" value="__SCHAR_MAX__=127"/>
+									<listOptionValue builtIn="false" value="__SHRT_MAX__=32767"/>
+									<listOptionValue builtIn="false" value="__INT_MAX__=2147483647"/>
+									<listOptionValue builtIn="false" value="__LONG_MAX__=2147483647L"/>
+									<listOptionValue builtIn="false" value="__LONG_LONG_MAX__=9223372036854775807LL"/>
+									<listOptionValue builtIn="false" value="__WCHAR_MAX__=255"/>
+									<listOptionValue builtIn="false" value="__INTMAX_MAX__=9223372036854775807LL"/>
+									<listOptionValue builtIn="false" value="__SIZE_MAX__=4294967295U"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_MAX__=18446744073709551615ULL"/>
+									<listOptionValue builtIn="false" value="__PTRDIFF_MAX__=2147483647"/>
+									<listOptionValue builtIn="false" value="__INTPTR_MAX__=2147483647"/>
+									<listOptionValue builtIn="false" value="__UINTPTR_MAX__=4294967295U"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_DOUBLE__=8"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_FLOAT__=4"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_INT__=4"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_LONG__=4"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_LONG_DOUBLE__=8"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_LONG_LONG__=8"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_POINTER__=4"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_SHORT__=2"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_PTRDIFF_T__=4"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_SIZE_T__=4"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_WCHAR_T__=1"/>
+									<listOptionValue builtIn="false" value="__SIZEOF_WINT_T__=4"/>
+									<listOptionValue builtIn="false" value="__INTMAX_TYPE__=long"/>
+									<listOptionValue builtIn="false" value="__INTMAX_FMTd__=&quot;lld&quot;"/>
+									<listOptionValue builtIn="false" value="__INTMAX_FMTi__=&quot;lli&quot;"/>
+									<listOptionValue builtIn="false" value="__INTMAX_C_SUFFIX__=LL"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_TYPE__=long"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_FMTo__=&quot;llo&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_FMTu__=&quot;llu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_FMTx__=&quot;llx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_FMTX__=&quot;llX&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_C_SUFFIX__=ULL"/>
+									<listOptionValue builtIn="false" value="__INTMAX_WIDTH__=64"/>
+									<listOptionValue builtIn="false" value="__PTRDIFF_TYPE__=int"/>
+									<listOptionValue builtIn="false" value="__PTRDIFF_FMTd__=&quot;d&quot;"/>
+									<listOptionValue builtIn="false" value="__PTRDIFF_FMTi__=&quot;i&quot;"/>
+									<listOptionValue builtIn="false" value="__PTRDIFF_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__INTPTR_TYPE__=int"/>
+									<listOptionValue builtIn="false" value="__INTPTR_FMTd__=&quot;d&quot;"/>
+									<listOptionValue builtIn="false" value="__INTPTR_FMTi__=&quot;i&quot;"/>
+									<listOptionValue builtIn="false" value="__INTPTR_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__SIZE_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__SIZE_FMTo__=&quot;o&quot;"/>
+									<listOptionValue builtIn="false" value="__SIZE_FMTu__=&quot;u&quot;"/>
+									<listOptionValue builtIn="false" value="__SIZE_FMTx__=&quot;x&quot;"/>
+									<listOptionValue builtIn="false" value="__SIZE_FMTX__=&quot;X&quot;"/>
+									<listOptionValue builtIn="false" value="__SIZE_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__WCHAR_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__WCHAR_WIDTH__=8"/>
+									<listOptionValue builtIn="false" value="__WINT_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__WINT_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__SIG_ATOMIC_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__SIG_ATOMIC_MAX__=2147483647"/>
+									<listOptionValue builtIn="false" value="__CHAR16_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__CHAR32_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINTMAX_WIDTH__=64"/>
+									<listOptionValue builtIn="false" value="__UINTPTR_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINTPTR_FMTo__=&quot;o&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTPTR_FMTu__=&quot;u&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTPTR_FMTx__=&quot;x&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTPTR_FMTX__=&quot;X&quot;"/>
+									<listOptionValue builtIn="false" value="__UINTPTR_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__FLT_DENORM_MIN__=1.40129846e-45F"/>
+									<listOptionValue builtIn="false" value="__FLT_HAS_DENORM__=1"/>
+									<listOptionValue builtIn="false" value="__FLT_DIG__=6"/>
+									<listOptionValue builtIn="false" value="__FLT_EPSILON__=1.19209290e-7F"/>
+									<listOptionValue builtIn="false" value="__FLT_HAS_INFINITY__=1"/>
+									<listOptionValue builtIn="false" value="__FLT_HAS_QUIET_NAN__=1"/>
+									<listOptionValue builtIn="false" value="__FLT_MANT_DIG__=24"/>
+									<listOptionValue builtIn="false" value="__FLT_MAX_10_EXP__=38"/>
+									<listOptionValue builtIn="false" value="__FLT_MAX_EXP__=128"/>
+									<listOptionValue builtIn="false" value="__FLT_MAX__=3.40282347e+38F"/>
+									<listOptionValue builtIn="false" value="__FLT_MIN_10_EXP__=(-37)"/>
+									<listOptionValue builtIn="false" value="__FLT_MIN_EXP__=(-125)"/>
+									<listOptionValue builtIn="false" value="__FLT_MIN__=1.17549435e-38F"/>
+									<listOptionValue builtIn="false" value="__DBL_DENORM_MIN__=4.9406564584124654e-324"/>
+									<listOptionValue builtIn="false" value="__DBL_HAS_DENORM__=1"/>
+									<listOptionValue builtIn="false" value="__DBL_DIG__=15"/>
+									<listOptionValue builtIn="false" value="__DBL_EPSILON__=2.2204460492503131e-16"/>
+									<listOptionValue builtIn="false" value="__DBL_HAS_INFINITY__=1"/>
+									<listOptionValue builtIn="false" value="__DBL_HAS_QUIET_NAN__=1"/>
+									<listOptionValue builtIn="false" value="__DBL_MANT_DIG__=53"/>
+									<listOptionValue builtIn="false" value="__DBL_MAX_10_EXP__=308"/>
+									<listOptionValue builtIn="false" value="__DBL_MAX_EXP__=1024"/>
+									<listOptionValue builtIn="false" value="__DBL_MAX__=1.7976931348623157e+308"/>
+									<listOptionValue builtIn="false" value="__DBL_MIN_10_EXP__=(-307)"/>
+									<listOptionValue builtIn="false" value="__DBL_MIN_EXP__=(-1021)"/>
+									<listOptionValue builtIn="false" value="__DBL_MIN__=2.2250738585072014e-308"/>
+									<listOptionValue builtIn="false" value="__LDBL_DENORM_MIN__=4.9406564584124654e-324L"/>
+									<listOptionValue builtIn="false" value="__LDBL_HAS_DENORM__=1"/>
+									<listOptionValue builtIn="false" value="__LDBL_DIG__=15"/>
+									<listOptionValue builtIn="false" value="__LDBL_EPSILON__=2.2204460492503131e-16L"/>
+									<listOptionValue builtIn="false" value="__LDBL_HAS_INFINITY__=1"/>
+									<listOptionValue builtIn="false" value="__LDBL_HAS_QUIET_NAN__=1"/>
+									<listOptionValue builtIn="false" value="__LDBL_MANT_DIG__=53"/>
+									<listOptionValue builtIn="false" value="__LDBL_MAX_10_EXP__=308"/>
+									<listOptionValue builtIn="false" value="__LDBL_MAX_EXP__=1024"/>
+									<listOptionValue builtIn="false" value="__LDBL_MAX__=1.7976931348623157e+308L"/>
+									<listOptionValue builtIn="false" value="__LDBL_MIN_10_EXP__=(-307)"/>
+									<listOptionValue builtIn="false" value="__LDBL_MIN_EXP__=(-1021)"/>
+									<listOptionValue builtIn="false" value="__LDBL_MIN__=2.2250738585072014e-308L"/>
+									<listOptionValue builtIn="false" value="__POINTER_WIDTH__=32"/>
+									<listOptionValue builtIn="false" value="__CHAR_UNSIGNED__=1"/>
+									<listOptionValue builtIn="false" value="__WCHAR_UNSIGNED__=1"/>
+									<listOptionValue builtIn="false" value="__WINT_UNSIGNED__=1"/>
+									<listOptionValue builtIn="false" value="__INT8_TYPE__=signed"/>
+									<listOptionValue builtIn="false" value="__INT8_FMTd__=&quot;hhd&quot;"/>
+									<listOptionValue builtIn="false" value="__INT8_FMTi__=&quot;hhi&quot;"/>
+									<listOptionValue builtIn="false" value="__INT8_C_SUFFIX__"/>
+									<listOptionValue builtIn="false" value="__INT16_TYPE__=short"/>
+									<listOptionValue builtIn="false" value="__INT16_FMTd__=&quot;hd&quot;"/>
+									<listOptionValue builtIn="false" value="__INT16_FMTi__=&quot;hi&quot;"/>
+									<listOptionValue builtIn="false" value="__INT16_C_SUFFIX__"/>
+									<listOptionValue builtIn="false" value="__INT32_TYPE__=int"/>
+									<listOptionValue builtIn="false" value="__INT32_FMTd__=&quot;d&quot;"/>
+									<listOptionValue builtIn="false" value="__INT32_FMTi__=&quot;i&quot;"/>
+									<listOptionValue builtIn="false" value="__INT32_C_SUFFIX__"/>
+									<listOptionValue builtIn="false" value="__INT64_TYPE__=long"/>
+									<listOptionValue builtIn="false" value="__INT64_FMTd__=&quot;lld&quot;"/>
+									<listOptionValue builtIn="false" value="__INT64_FMTi__=&quot;lli&quot;"/>
+									<listOptionValue builtIn="false" value="__INT64_C_SUFFIX__=LL"/>
+									<listOptionValue builtIn="false" value="__UINT8_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINT8_FMTo__=&quot;hho&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT8_FMTu__=&quot;hhu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT8_FMTx__=&quot;hhx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT8_FMTX__=&quot;hhX&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT8_C_SUFFIX__"/>
+									<listOptionValue builtIn="false" value="__UINT8_MAX__=255"/>
+									<listOptionValue builtIn="false" value="__INT8_MAX__=127"/>
+									<listOptionValue builtIn="false" value="__UINT16_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINT16_FMTo__=&quot;ho&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT16_FMTu__=&quot;hu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT16_FMTx__=&quot;hx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT16_FMTX__=&quot;hX&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT16_C_SUFFIX__"/>
+									<listOptionValue builtIn="false" value="__UINT16_MAX__=65535"/>
+									<listOptionValue builtIn="false" value="__INT16_MAX__=32767"/>
+									<listOptionValue builtIn="false" value="__UINT32_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINT32_FMTo__=&quot;o&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT32_FMTu__=&quot;u&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT32_FMTx__=&quot;x&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT32_FMTX__=&quot;X&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT32_C_SUFFIX__=U"/>
+									<listOptionValue builtIn="false" value="__UINT32_MAX__=4294967295U"/>
+									<listOptionValue builtIn="false" value="__INT32_MAX__=2147483647"/>
+									<listOptionValue builtIn="false" value="__UINT64_TYPE__=long"/>
+									<listOptionValue builtIn="false" value="__UINT64_FMTo__=&quot;llo&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT64_FMTu__=&quot;llu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT64_FMTx__=&quot;llx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT64_FMTX__=&quot;llX&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT64_C_SUFFIX__=ULL"/>
+									<listOptionValue builtIn="false" value="__UINT64_MAX__=18446744073709551615ULL"/>
+									<listOptionValue builtIn="false" value="__INT64_MAX__=9223372036854775807LL"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST8_TYPE__=signed"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST8_MAX__=127"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST8_FMTd__=&quot;hhd&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST8_FMTi__=&quot;hhi&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST8_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST8_MAX__=255"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST8_FMTo__=&quot;hho&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST8_FMTu__=&quot;hhu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST8_FMTx__=&quot;hhx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST8_FMTX__=&quot;hhX&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST16_TYPE__=short"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST16_MAX__=32767"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST16_FMTd__=&quot;hd&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST16_FMTi__=&quot;hi&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST16_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST16_MAX__=65535"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST16_FMTo__=&quot;ho&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST16_FMTu__=&quot;hu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST16_FMTx__=&quot;hx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST16_FMTX__=&quot;hX&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST32_TYPE__=int"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST32_MAX__=2147483647"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST32_FMTd__=&quot;d&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST32_FMTi__=&quot;i&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST32_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST32_MAX__=4294967295U"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST32_FMTo__=&quot;o&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST32_FMTu__=&quot;u&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST32_FMTx__=&quot;x&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST32_FMTX__=&quot;X&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST64_TYPE__=long"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST64_MAX__=9223372036854775807LL"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST64_FMTd__=&quot;lld&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_LEAST64_FMTi__=&quot;lli&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST64_TYPE__=long"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST64_MAX__=18446744073709551615ULL"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST64_FMTo__=&quot;llo&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST64_FMTu__=&quot;llu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST64_FMTx__=&quot;llx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_LEAST64_FMTX__=&quot;llX&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_FAST8_TYPE__=signed"/>
+									<listOptionValue builtIn="false" value="__INT_FAST8_MAX__=127"/>
+									<listOptionValue builtIn="false" value="__INT_FAST8_FMTd__=&quot;hhd&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_FAST8_FMTi__=&quot;hhi&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST8_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST8_MAX__=255"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST8_FMTo__=&quot;hho&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST8_FMTu__=&quot;hhu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST8_FMTx__=&quot;hhx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST8_FMTX__=&quot;hhX&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_FAST16_TYPE__=short"/>
+									<listOptionValue builtIn="false" value="__INT_FAST16_MAX__=32767"/>
+									<listOptionValue builtIn="false" value="__INT_FAST16_FMTd__=&quot;hd&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_FAST16_FMTi__=&quot;hi&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST16_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST16_MAX__=65535"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST16_FMTo__=&quot;ho&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST16_FMTu__=&quot;hu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST16_FMTx__=&quot;hx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST16_FMTX__=&quot;hX&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_FAST32_TYPE__=int"/>
+									<listOptionValue builtIn="false" value="__INT_FAST32_MAX__=2147483647"/>
+									<listOptionValue builtIn="false" value="__INT_FAST32_FMTd__=&quot;d&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_FAST32_FMTi__=&quot;i&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST32_TYPE__=unsigned"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST32_MAX__=4294967295U"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST32_FMTo__=&quot;o&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST32_FMTu__=&quot;u&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST32_FMTx__=&quot;x&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST32_FMTX__=&quot;X&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_FAST64_TYPE__=long"/>
+									<listOptionValue builtIn="false" value="__INT_FAST64_MAX__=9223372036854775807LL"/>
+									<listOptionValue builtIn="false" value="__INT_FAST64_FMTd__=&quot;lld&quot;"/>
+									<listOptionValue builtIn="false" value="__INT_FAST64_FMTi__=&quot;lli&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST64_TYPE__=long"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST64_MAX__=18446744073709551615ULL"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST64_FMTo__=&quot;llo&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST64_FMTu__=&quot;llu&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST64_FMTx__=&quot;llx&quot;"/>
+									<listOptionValue builtIn="false" value="__UINT_FAST64_FMTX__=&quot;llX&quot;"/>
+									<listOptionValue builtIn="false" value="__USER_LABEL_PREFIX__=_"/>
+									<listOptionValue builtIn="false" value="__FINITE_MATH_ONLY__=0"/>
+									<listOptionValue builtIn="false" value="__GNUC_GNU_INLINE__=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_TEST_AND_SET_TRUEVAL=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_BOOL_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_CHAR_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_CHAR16_T_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_CHAR32_T_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_WCHAR_T_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_SHORT_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_INT_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_LONG_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_LLONG_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__GCC_ATOMIC_POINTER_LOCK_FREE=1"/>
+									<listOptionValue builtIn="false" value="__NO_INLINE__=1"/>
+									<listOptionValue builtIn="false" value="__FLT_EVAL_METHOD__=0"/>
+									<listOptionValue builtIn="false" value="__FLT_RADIX__=2"/>
+									<listOptionValue builtIn="false" value="__DECIMAL_DIG__=17"/>
+									<listOptionValue builtIn="false" value="__xcore__=1"/>
+									<listOptionValue builtIn="false" value="__XS1B__=1"/>
+									<listOptionValue builtIn="false" value="__STDC__=1"/>
+									<listOptionValue builtIn="false" value="__STDC_HOSTED__=1"/>
+									<listOptionValue builtIn="false" value="__cplusplus=199711L"/>
+									<listOptionValue builtIn="false" value="__STDC_UTF_16__=1"/>
+									<listOptionValue builtIn="false" value="__STDC_UTF_32__=1"/>
+									<listOptionValue builtIn="false" value="XCC_VERSION_YEAR=14"/>
+									<listOptionValue builtIn="false" value="XCC_VERSION_MONTH=3"/>
+									<listOptionValue builtIn="false" value="XCC_VERSION_MAJOR=1403"/>
+									<listOptionValue builtIn="false" value="XCC_VERSION_MINOR=2"/>
+									<listOptionValue builtIn="false" value="__XCC_HAVE_FLOAT__=1"/>
+									<listOptionValue builtIn="false" value="_XSCOPE_PROBES_INCLUDE_FILE=&quot;/var/folders/0l/8jd0xy095ps890m302j532580000h5/T//cc8vh80e.h&quot;"/>
+								</option>
+								<option id="com.xmos.cxx.compiler.option.include.paths.1031009526" name="com.xmos.cxx.compiler.option.include.paths" superClass="com.xmos.cxx.compiler.option.include.paths" valueType="includePath">
+									<listOptionValue builtIn="false" value="&quot;${XMOS_TOOL_PATH}/target/include&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${XMOS_TOOL_PATH}/target/include/clang&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${XMOS_TOOL_PATH}/target/include/c++/v1&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_logging/doc}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/doc/rst/images}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src/user/client}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src/user/class}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src/core/included}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src/core}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_logging/doc/rst}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_logging/src}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_logging}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src/user/control}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_logging/api}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/doc/rst}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/api}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/doc}&quot;"/>
+									<listOptionValue builtIn="false" value="&quot;${workspace_loc:/lib_xud/src/user}&quot;"/>
+								</option>
+								<inputType id="com.xmos.cdt.cxx.compiler.input.cpp.223196941" name="C++" superClass="com.xmos.cdt.cxx.compiler.input.cpp"/>
+							</tool>
+						</toolChain>
+					</folderInfo>
+					<sourceEntries>
+						<entry excluding=".build*" flags="VALUE_WORKSPACE_PATH|RESOLVED" kind="sourcePath" name=""/>
+					</sourceEntries>
+				</configuration>
+			</storageModule>
+			<storageModule moduleId="org.eclipse.cdt.core.externalSettings"/>
+		</cconfiguration>
+	</storageModule>
+	<storageModule moduleId="cdtBuildSystem" version="4.0.0">
+		<project id="lib_xua.null.1378855182" name="lib_xua"/>
+	</storageModule>
+	<storageModule moduleId="scannerConfiguration">
+		<autodiscovery enabled="true" problemReportingEnabled="true" selectedProfileId=""/>
+	</storageModule>
+	<storageModule moduleId="org.eclipse.cdt.core.LanguageSettingsProviders"/>
+</cproject>

lib_xua/.gitignore

@@ -0,0 +1,5 @@
+.cproject
+.makefile
+.project
+.settings
+.xproject

lib_xua/.makefile

@@ -0,0 +1,8 @@
+all:
+	@echo "** Module only - only builds as part of application **"
+
+
+clean:
+	@echo "** Module only - only builds as part of application **"
+
+

lib_xua/.project

@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>lib_xua</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>com.xmos.cdt.core.ProjectInfoSyncBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>com.xmos.cdt.core.LegacyProjectCheckerBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>com.xmos.cdt.core.ModulePathBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.cdt.managedbuilder.core.genmakebuilder</name>
+			<triggers>clean,full,incremental,</triggers>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.cdt.managedbuilder.core.ScannerConfigBuilder</name>
+			<triggers>full,incremental,</triggers>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>org.eclipse.cdt.core.cnature</nature>
+		<nature>org.eclipse.cdt.managedbuilder.core.managedBuildNature</nature>
+		<nature>org.eclipse.cdt.managedbuilder.core.ScannerConfigNature</nature>
+		<nature>com.xmos.cdt.core.XdeProjectNature</nature>
+	</natures>
+</projectDescription>

lib_xua/.xproject

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><xproject><repository>lib_xua</repository><partnum>XM-012639-SM</partnum></xproject>

lib_xua/LICENSE.txt

@@ -1,6 +1,6 @@
 Software Release License Agreement
 
-Copyright (c) 2017-2018, XMOS, All rights reserved.
+Copyright (c) 2017-2020, XMOS, All rights reserved.
 
 BY ACCESSING, USING, INSTALLING OR DOWNLOADING THE XMOS SOFTWARE, YOU AGREE TO BE BOUND BY THE FOLLOWING TERMS. IF YOU DO NOT AGREE TO THESE, DO NOT ATTEMPT TO DOWNLOAD, ACCESS OR USE THE XMOS Software.
 

lib_xua/api/xua.h

@@ -6,13 +6,17 @@
 #include "xua_conf_full.h"
 
 #if __XC__ || __STDC__
-#include "xua_audiohub.h"
+    #include "xua_audiohub.h"
 
-#include "xua_endpoint0.h"
+    #include "xua_endpoint0.h"
 
-#include "xua_buffer.h"
+    #include "xua_buffer.h"
+#endif
 
-//#include "xua_dfu.h"
+#if __XC__
+    #if XUA_NUM_PDM_MICS > 0
+        #include "xua_pdm_mic.h"
+    #endif
 #endif
 
 #endif

lib_xua/api/xua_audiohub.h

@@ -5,8 +5,9 @@
 #if __XC__
 
 #include "xccompat.h"
+#include "xs1.h"
 
-#ifndef NO_USB
+#if XUA_USB_EN
 #include "dfu_interface.h"
 #endif
 
@@ -15,24 +16,44 @@
  *  This function drives I2S ports and handles samples to/from other digital
  *  I/O threads.
  *
- *  \param c_aud Audio sample channel connected to the mixer() thread or the
- *              decouple() thread
- *  \param c_dig channel connected to the clockGen() thread for
- *               receiving/transmitting samples
- *  \param c_config An optional channel that will be passed on to the
- *                  CODEC configuration functions.
+ *  \param c_aud            Audio sample channel connected to the mixer() thread or the
+ *                          decouple() thread
+ *
+ *  \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 p_mclk_in        Master clock inport port (must be 1-bit)
+ *
+ *  \param p_lrclk          Nullable port for I2S sample clock
+ *
+ *  \param p_bclk           Nullable port for I2S bit
+ *
+ *  \param p_i2s_dac        Nullable array of ports for I2S data output lines
+ *
+ *  \param p_i2s_adc        Nullable array of ports for I2S data input lines
+ *
+ *  \param c_dig            channel connected to the clockGen() thread for
+ *                          receiving/transmitting samples
  */
-void XUA_AudioHub(chanend ?c_aud
-#if (XUA_SPDIF_TX_EN) && (SPDIF_TX_TILE != AUDIO_IO_TILE)
+void XUA_AudioHub(chanend ?c_aud, 
+    clock ?clk_audio_mclk, 
+    clock ?clk_audio_bclk, 
+    in port p_mclk_in,
+    buffered _XUA_CLK_DIR port:32 ?p_lrclk,
+    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)
     , chanend c_spdif_tx
 #endif
-#if(defined(SPDIF_RX) || defined(ADAT_RX))
+#if((SPDIF_RX) || (ADAT_RX))
     , chanend c_dig
 #endif
 #if (XUD_TILE != 0) && (AUDIO_IO_TILE == 0) && (XUA_DFU_EN == 1)
    , server interface i_dfu ?dfuInterface
 #endif
-#if (NUM_PDM_MICS > 0)
+#if (XUA_NUM_PDM_MICS > 0)
     , chanend c_pdm_in
 #endif
 );

lib_xua/api/xua_buffer.h

@@ -1,4 +1,4 @@
-// Copyright (c) 2011-2018, XMOS Ltd, All rights reserved
+// Copyright (c) 2011-2019, XMOS Ltd, All rights reserved
 #ifndef __XUA_BUFFER_H__
 #define __XUA_BUFFER_H__
 
@@ -51,14 +51,14 @@ void XUA_Buffer(
             chanend c_iap_ea_native_data,
 #endif
 #endif
-#if defined(SPDIF_RX) || defined(ADAT_RX)
+#if (SPDIF_RX) || (ADAT_RX)
             chanend ?c_int,
             chanend ?c_clk_int,
 #endif
             chanend c_sof,
             chanend c_aud_ctl,
             in port p_off_mclk
-#ifdef HID_CONTROLS
+#if( 0 < HID_CONTROLS )
             , chanend c_hid
 #endif
             , chanend c_aud
@@ -90,14 +90,14 @@ void XUA_Buffer_Ep(chanend c_aud_out,
             chanend c_iap_ea_native_data,
 #endif
 #endif
-#if defined(SPDIF_RX) || defined(ADAT_RX)
+#if (SPDIF_RX) || (ADAT_RX)
             chanend ?c_int,
             chanend ?c_clk_int,
 #endif
             chanend c_sof,
             chanend c_aud_ctl,
             in port p_off_mclk
-#ifdef HID_CONTROLS
+#if( 0 < HID_CONTROLS )
             , chanend c_hid
 #endif
 #ifdef CHAN_BUFF_CTRL

lib_xua/api/xua_conf_default.h

@@ -1,4 +1,4 @@
-// Copyright (c) 2011-2018, XMOS Ltd, All rights reserved
+// Copyright (c) 2011-2020, XMOS Ltd, All rights reserved
 /*
  * @brief       Defines relating to device configuration and customisation of lib_xua
  * @author      Ross Owen, XMOS Limited
@@ -56,6 +56,13 @@
 #define PDM_TILE        AUDIO_IO_TILE
 #endif
 
+/** 
+ * @brief Disable USB functionalty just leaving AudioHub 
+ */
+#ifndef XUA_USB_EN
+#define XUA_USB_EN      1
+#endif
+
 /**
  * @brief Number of input channels (device to host). Default: NONE (Must be defined by app)
  */
@@ -235,10 +242,6 @@
 #define AUDIO_CLASS_FALLBACK  0     /* Default to not falling back to UAC 1 */
 #endif
 
-#if defined(AUDIO_CLASS_FALLBACK) && (AUDIO_CLASS_FALLBACK==0)
-#undef AUDIO_CLASS_FALLBACK
-#endif
-
 /**
  * @brief Whether or not to run UAC2 in full-speed. When disabled device can either operate in
  *        UAC1 mode in full-speed (if AUDIO_CLASS_FALLBACK enabled) or return "null" descriptors.
@@ -247,7 +250,7 @@
  */
 #if (AUDIO_CLASS == 2)
     /* Whether to run in Audio Class 2.0 mode in USB Full-speed */
-    #if !defined(FULL_SPEED_AUDIO_2) && !defined(AUDIO_CLASS_FALLBACK)
+    #if !defined(FULL_SPEED_AUDIO_2) && (AUDIO_CLASS_FALLBACK == 0)
         #define FULL_SPEED_AUDIO_2    1     /* Default to falling back to UAC2 */
     #endif
 #endif
@@ -257,7 +260,7 @@
 #endif
 
 /* Some checks on full-speed functionality */
-#if defined(FULL_SPEED_AUDIO_2) && defined(AUDIO_CLASS_FALLBACK)
+#if defined(FULL_SPEED_AUDIO_2) && (AUDIO_CLASS_FALLBACK)
 #error FULL_SPEED_AUDIO_2 and AUDIO_CLASS_FALLBACK enabled!
 #endif
 
@@ -271,20 +274,27 @@
 /**
  * @brief Number of PDM microphones in the design. Default: None
  */
-#ifndef NUM_PDM_MICS
-#define NUM_PDM_MICS            (0)
+#ifndef XUA_NUM_PDM_MICS
+#define XUA_NUM_PDM_MICS            (0)
 #endif
 
 /**
  * @brief PDM Microphone first channel index, defines which channels microphones will be input on.
  * Note, indexed from 0.
  *
- * Default: 0 (i.e. channels [0:NUM_PDM_MICS-1])
+ * Default: 0 (i.e. channels [0:XUA_NUM_PDM_MICS-1])
  * */
 #ifndef PDM_MIC_INDEX
 #define PDM_MIC_INDEX           (0)
 #endif
 
+/**
+ * @brief Size of a frame of microphone data samples. Default: 1
+ */
+#ifndef XUA_MIC_FRAME_SIZE
+#define XUA_MIC_FRAME_SIZE      (1)
+#endif
+
 /**
  * @brief Enable MIDI functionality including buffering, descriptors etc. Default: DISABLED
  */
@@ -347,11 +357,6 @@
 #define SPDIF_RX              (0)
 #endif
 
-/* Tidy up old SPDIF_RX usage */
-#if defined(SPDIF_RX) && (SPDIF_RX == 0)
-#undef SPDIF_RX
-#endif
-
 /**
  * @brief Enables ADAT Rx. Default: 0 (Disabled)
  */
@@ -359,17 +364,13 @@
 #define ADAT_RX               (0)
 #endif
 
-#if defined(ADAT_RX) && (ADAT_RX == 0)
-#undef ADAT_RX
-#endif
-
 /**
  * @brief S/PDIF Rx first channel index, defines which channels S/PDIF will be input on.
  * Note, indexed from 0.
  *
  * Default: NONE (Must be defined by app when SPDIF_RX enabled)
  */
-#if defined (SPDIF_RX) || defined (__DOXYGEN__)
+#if (SPDIF_RX) || defined (__DOXYGEN__)
 #ifndef SPDIF_RX_INDEX
     #error SPDIF_RX_INDEX not defined and SPDIF_RX defined
     #define SPDIF_RX_INDEX 0 /* Default define for doxygen */
@@ -382,7 +383,7 @@
  *
  * Default: NONE (Must be defined by app when ADAT_RX enabled)
  */
-#if defined(ADAT_RX) || defined(__DOXYGEN__)
+#if (ADAT_RX) || defined(__DOXYGEN__)
 #ifndef ADAT_RX_INDEX
     #error ADAT_RX_INDEX not defined and ADAT_RX defined
     #define ADAT_RX_INDEX (0) /* Default define for doxygen */
@@ -393,7 +394,7 @@
 #endif
 #endif
 
-#ifdef ADAT_RX
+#if ADAT_RX
 
 /* Setup input stream formats for ADAT */
 #if(MAX_FREQ > 96000)
@@ -431,10 +432,6 @@
 #define HID_CONTROLS       (0)
 #endif
 
-#if defined(HID_CONTROLS) && (HID_CONTROLS == 0)
-#undef HID_CONTROLS
-#endif
-
 /* @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.
@@ -445,6 +442,16 @@
 #define CODEC_MASTER       (0)
 #endif
 
+/**
+ * @brief Serial Number String used by the device
+ *
+ * Default: ""
+ */
+#ifndef SERIAL_STR
+#define SERIAL_STR               ""
+#endif
+
+
 /**
  * @brief Vendor String used by the device. This is also pre-pended to various strings used by the design.
  *
@@ -500,7 +507,7 @@
  *
  * Default: 0x0003
  */
-#if (AUDIO_CLASS==1) || defined(AUDIO_CLASS_FALLBACK) || defined(__DOXYGEN__)
+#if (AUDIO_CLASS == 1) || (AUDIO_CLASS_FALLBACK) || defined(__DOXYGEN__)
 #ifndef PID_AUDIO_1
 #define PID_AUDIO_1              (0x0003)
 #endif
@@ -1164,6 +1171,10 @@
 #endif
 
 
+#if (defined(UAC_FORCE_FEEDBACK_EP) && UAC_FORCE_FEEDBACK_EP == 0)
+#undef UAC_FORCE_FEEDBACK_EP
+#endif
+
 #ifndef __ASSEMBLER__
 /* Endpoint addresses enums */
 enum USBEndpointNumber_In
@@ -1173,13 +1184,13 @@ enum USBEndpointNumber_In
     ENDPOINT_NUMBER_IN_FEEDBACK,
 #endif
     ENDPOINT_NUMBER_IN_AUDIO,
-#if defined(SPDIF_RX) || defined(ADAT_RX)
+#if (SPDIF_RX) || (ADAT_RX)
     ENDPOINT_NUMBER_IN_INTERRUPT,   /* Audio interrupt/status EP */
 #endif
 #ifdef MIDI
     ENDPOINT_NUMBER_IN_MIDI,
 #endif
-#ifdef HID_CONTROLS
+#if( 0 < HID_CONTROLS )
     ENDPOINT_NUMBER_IN_HID,
 #endif
 #ifdef IAP
@@ -1251,9 +1262,9 @@ enum USBEndpointNumber_Out
 #endif
 
 /* Length of clock unit/clock-selector units */
-#if defined(SPDIF_RX) && defined(ADAT_RX)
+#if (SPDIF_RX) && (ADAT_RX)
 #define NUM_CLOCKS               (3)
-#elif defined(SPDIF_RX) || defined(ADAT_RX)
+#elif (SPDIF_RX) || (ADAT_RX)
 #define NUM_CLOCKS               (2)
 #else
 #define NUM_CLOCKS               (1)
@@ -1444,6 +1455,12 @@ enum USBEndpointNumber_Out
 #error Bad DEFAULT_MCLK_FREQ
 #endif
 
+/* DFU functional descriptor wDetachTimeOut field (milliseconds)
+ * Time for device to wait for bus reset after DETACH request before reverting to idle state */
+#ifndef DFU_DETACH_TIME_OUT
+#define DFU_DETACH_TIME_OUT 250
+#endif
+
 #if ((MCLK_441 % MIN_FREQ) == 0)
 #define MIN_FREQ_44 MIN_FREQ
 #define MIN_FREQ_48 ((48000 * 512)/((44100 * 512)/MIN_FREQ))
@@ -1455,3 +1472,13 @@ enum USBEndpointNumber_Out
 #define MIN_FREQ_44 (((44100*512)/((48000 * 512)/MIN_FREQ))*2)
 #endif
 
+/* Internal define for port declaration */
+#if CODEC_MASTER
+    #define _XUA_CLK_DIR in
+#else
+    #define _XUA_CLK_DIR out
+#endif
+
+#if (CODEC_MASTER == 1) && (DSD_CHANS_DAC != 0) 
+#error CODEC_MASTER with DSD is currently unsupported 
+#endif

lib_xua/api/xua_conf_full.h

@@ -8,4 +8,6 @@
 
 #include "xua_conf_default.h"
 
+
+
 #endif

lib_xua/api/xua_endpoint0.h

@@ -1,4 +1,4 @@
-// Copyright (c) 2011-2018, XMOS Ltd, All rights reserved
+// Copyright (c) 2011-2020, XMOS Ltd, All rights reserved
 
 #ifndef _XUA_ENDPOINT0_H_
 #define _XUA_ENDPOINT0_H_
@@ -28,5 +28,105 @@ 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_);
 
+/** Function to set the Vendor ID value
+ *
+ *  \param vid vendor ID value to set
+*/
+void XUA_Endpoint0_setVendorId(unsigned short vid);
+
+/** Function to set the Product ID value
+ *
+ *  \param pid Product ID value to set
+*/
+void XUA_Endpoint0_setProductId(unsigned short pid);
+
+
+/** Function to set the Vendor string
+ *
+ *  \param vendor_str Vendor string to set
+*/
+#ifdef __XC__
+void XUA_Endpoint0_setVendorStr(char * unsafe vendor_str);
+#else
+void XUA_Endpoint0_setVendorStr(char * vendor_str);
+#endif
+
+/** Function to set the Product string
+ *
+ *  \param product_str Product string to set
+*/
+
+#ifdef __XC__
+void XUA_Endpoint0_setProductStr(char * unsafe product_str);
+#else
+void XUA_Endpoint0_setProductStr(char * product_str);
+#endif
+
+/** Function to set the Serial string
+ *
+ *  \param serial_str Serial string to set
+*/
+#ifdef __XC__
+void XUA_Endpoint0_setSerialStr(char * unsafe serial_str);
+#else
+void XUA_Endpoint0_setSerialStr(char * serial_str);
+#endif
+
+/** Function to set the BCD device
+ *
+ *  \param bcdDevice BCD device to set
+
+*/
+
+void XUA_Endpoint0_setBcdDevice(unsigned short bcdDevice);
+
+/** Function to get the Vendor string
+ *
+ *  \return vendor string
+*/
+#ifdef __XC__
+char * unsafe XUA_Endpoint0_getVendorStr();
+#else
+char *  XUA_Endpoint0_getVendorStr();
+#endif
+
+/** Function to get the Product string
+ *
+ *  \return Product string
+*/
+#ifdef __XC__
+char * unsafe XUA_Endpoint0_getProductStr();
+#else
+char *  XUA_Endpoint0_getProductStr();
+#endif
+
+/** Function to get the Serial Number string
+ *
+ *  \return Serial string
+*/
+#ifdef __XC__
+char * unsafe XUA_Endpoint0_getSerialStr();
+#else
+char *  XUA_Endpoint0_getSerialStr();
+#endif
+
+/** Function to get the Vendor ID
+ *
+ *  \return Vendor ID
+*/
+unsigned short XUA_Endpoint0_getVendorId();
+
+/** Function to get the Product ID
+ *
+ *  \return Product ID
+*/
+unsigned short XUA_Endpoint0_getProductId();
+
+/** Function to get the BCD device
+ *
+ *  \return BCD device
+*/
+unsigned short XUA_Endpoint0_getBcdDevice();
+
 #endif
 #endif

lib_xua/api/xua_pdm_mic.h

@@ -1,7 +1,15 @@
 // Copyright (c) 2015-2018, XMOS Ltd, All rights reserved
 
+#ifndef XUA_PDM_MIC_H
+#define XUA_PDM_MIC_H
+
+/* Included from lib_mic_array */
 #include "mic_array.h"
 
+
+/* Configures PDM ports/clocks */
+void xua_pdm_mic_config(in port p_pdm_mclk, in port p_pdm_clk, buffered in port:32 p_pdm_mics, clock clk_pdm);
+
 #ifdef MIC_PROCESSING_USE_INTERFACE
 /* Interface based user processing */
 typedef interface mic_process_if
@@ -12,7 +20,7 @@ typedef interface mic_process_if
 
 
 [[combinable]]
-void pdm_buffer(streaming chanend c_ds_output[2], chanend c_audio
+void XUA_PdmBuffer(streaming chanend c_ds_output[2], chanend c_audio
 #ifdef MIC_PROCESSING_USE_INTERFACE
    , client mic_process_if i_mic_process
 #endif
@@ -22,7 +30,7 @@ void pdm_buffer(streaming chanend c_ds_output[2], chanend c_audio
 void user_pdm_process(server mic_process_if i_mic_data);
 
 /* PDM interface and decimation cores */
-void pdm_mic(streaming chanend c_ds_output[2]);
+void xua_pdm_mic(streaming chanend c_ds_output[2], buffered in port:32 p_pdm_mics);
 
 #else
 
@@ -33,10 +41,11 @@ void user_pdm_init();
 
 /* PDM interface and decimation cores */
 [[combinable]]
-void pdm_buffer(streaming chanend c_ds_output[2], chanend c_audio);
+void XUA_PdmBuffer(streaming chanend c_ds_output[2], chanend c_audio);
 
 /* PDM interface and decimation cores */
-void pdm_mic(streaming chanend c_ds_output[2]);
+void xua_pdm_mic(streaming chanend c_ds_output[2], buffered in port:32 p_pdm_mics);
 
 #endif
+#endif
 

lib_xua/api/xua_usb_params_funcs.h

@@ -0,0 +1,18 @@
+// Copyright (c) 2017-2020, XMOS Ltd, All rights reserved
+
+#ifndef __XUA_API_H__
+#define __XUA_API_H__
+
+#include <stdint.h>
+
+void set_usb_to_device_rate(uint32_t rate);
+void set_device_to_usb_rate(uint32_t rate);
+void set_usb_to_device_bit_res(uint32_t rate);
+void set_device_to_usb_bit_res(uint32_t rate);
+
+uint32_t get_usb_to_device_rate();
+uint32_t get_device_to_usb_rate();
+uint32_t get_usb_to_device_bit_res();
+uint32_t get_device_to_usb_bit_res();
+
+#endif  //__XUA_API_H__

lib_xua/doc/.gitignore

@@ -0,0 +1 @@
+pdf

lib_xua/doc/rst/.gitignore

@@ -0,0 +1 @@
+_build

lib_xua/doc/rst/feat.rst

@@ -0,0 +1,117 @@
+
+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.
+
+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.
+
+
+

lib_xua/doc/rst/hw.rst

@@ -0,0 +1,62 @@
+
+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. 
+
+Please also see application note AN00246.
+
+
+xCORE-200 Multi-Channel 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 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.
+
+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.
+
+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.
+
+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.
+
+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
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+A standard XMOS xSYS interface is provided to allow host debug of the board via JTAG.
+
+|newpage|
+

lib_xua/doc/rst/index.rst

@@ -2,20 +2,38 @@
 .. include:: ../../../README.rst
 
 
-XMOS USB Audio
-==============
+About This Document
+-------------------
 
-This document details the XMOS USB Audio Library.  This library
-enables the development of USB Audio devices on the XMOS xCORE architecture.
+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 the library, its basic use 
-and resources required.
-
-This document assumes familiarity with the XMOS xCORE architecture, the
-Universal Serial Bus 2.0 Specification (and related specifications),
+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.
 
-Known Issues
-============
+
+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>
+    Known Issues <issues>
+
+
 
 .. include:: ../../../CHANGELOG.rst

lib_xua/doc/rst/issues.rst

@@ -0,0 +1,20 @@
+|appendix|
+
+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
+
+- (#14173) I2S input is completely disabled when DSD output is active - any input stream to the host will contain 0 samples
+
+- (#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.
+
+- (#14883) Before DoP mode is detected a small number of DSD samples will be played out as PCM via I2S
+
+- (#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
+
+-  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.

lib_xua/doc/rst/overview.rst

@@ -0,0 +1,77 @@
+USB Audio Solution Overview
+---------------------------
+
+
+.. table::
+ :class: vertical-borders
+
+ +-------------------------------------------------------------------------------------------------------------------------------+
+ |                        **Functionality**                                                                                      |
+ +-------------------------------------------------------------------------------------------------------------------------------+
+ +-------------------------------------------------------------------------------------------------------------------------------+
+ | Provides USB interface to audio I/O.                                                                                          |
+ |                                                                                                                               |
+ +-------------------------------------------------------------------------------------------------------------------------------+
+ +-------------------------------------------------------------------------------------------------------------------------------+
+ |                       **Supported Standards**                                                                                 |
+ +-------------------------------------------------------------------------------------------------------------------------------+
+ +---------------------------------+---------------------------------------------------------------------------------------------+
+ |   USB                           | USB 2.0 (Full-speed and High-speed)                                                         |
+ |                                 +---------------------------------------------------------------------------------------------+
+ |                                 | `USB Audio Class 1.0 <http://www.usb.org/developers/devclass_docs/audio10.pdf>`_            |
+ |                                 +---------------------------------------------------------------------------------------------+
+ |                                 | `USB Audio Class 2.0 <http://www.usb.org/developers/devclass_docs/Audio2.0_final.zip>`_     |
+ |                                 +---------------------------------------------------------------------------------------------+
+ |                                 | `USB Firmware Upgrade (DFU) 1.1 <http://www.usb.org/developers/devclass_docs/DFU_1.1.pdf>`_ |
+ |                                 +---------------------------------------------------------------------------------------------+
+ |                                 | `USB Midi Device Class 1.0 <http://www.usb.org/developers/devclass_docs/midi10.pdf>`_       |
+ +---------------------------------+---------------------------------------------------------------------------------------------+
+ |   Audio                         |   I2S/TDM                                                                                   |
+ |                                 +---------------------------------------------------------------------------------------------+
+ |                                 |   S/PDIF                                                                                    |
+ |                                 +---------------------------------------------------------------------------------------------+
+ |                                 |   ADAT                                                                                      |
+ |                                 +---------------------------------------------------------------------------------------------+
+ |                                 |   Direct Stream Digital (DSD)                                                               |
+ |                                 +---------------------------------------------------------------------------------------------+
+ |                                 |   PDM Microphones                                                                           |
+ |                                 +---------------------------------------------------------------------------------------------+
+ |                                 |   MIDI                                                                                      |
+ +---------------------------------+---------------------------------------------------------------------------------------------+
+ +-------------------------------------------------------------------------------------------------------------------------------+
+ |                  **Supported Sample Frequencies**                                                                             |
+ +-------------------------------------------------------------------------------------------------------------------------------+
+ +-------------------------------------------------------------------------------------------------------------------------------+
+ | 44.1kHz, 48kHz, 88.2kHz, 96kHz, 176.4kHz, 192kHz, 352.8kHz, 384kHz                                                            |
+ +-------------------------------------------------------------------------------------------------------------------------------+
+ +-------------------------------------------------------------------------------------------------------------------------------+
+ |                             **Supported Devices**                                                                             |
+ +-------------------------------------------------------------------------------------------------------------------------------+
+ +---------------------------------+---------------------------------------------------------------------------------------------+
+ | XMOS Devices                    |   xCORE-200 Series                                                                          |
+ +---------------------------------+---------------------------------------------------------------------------------------------+
+ +-------------------------------------------------------------------------------------------------------------------------------+
+ |                       **Requirements**                                                                                        |
+ +-------------------------------------------------------------------------------------------------------------------------------+
+ +---------------------------------+---------------------------------------------------------------------------------------------+
+ | Development Tools               | xTIMEcomposer Development Tools v14 or later                                                |
+ +---------------------------------+---------------------------------------------------------------------------------------------+
+ | USB                             | xCORE-200 Series device with integrated USB Phy                                             |
+ +---------------------------------+---------------------------------------------------------------------------------------------+
+ | 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)                       |
+ +---------------------------------+---------------------------------------------------------------------------------------------+
+ +-------------------------------------------------------------------------------------------------------------------------------+
+ |                       **Licensing and Support**                                                                               |
+ +-------------------------------------------------------------------------------------------------------------------------------+
+ +-------------------------------------------------------------------------------------------------------------------------------+
+ |   Reference code provided without charge under license from XMOS.                                                             |
+ +-------------------------------------------------------------------------------------------------------------------------------+
+ |   Please visit http://www.xmos.com/support/contact for support.                                                               |
+ +-------------------------------------------------------------------------------------------------------------------------------+
+ |   Reference code is maintained by XMOS Limited.                                                                               |
+ +-------------------------------------------------------------------------------------------------------------------------------+
+
+
+

lib_xua/doc/rst/sw.rst

@@ -0,0 +1,89 @@
+
+.. _usb_audio_sec_architecture:
+
+USB Audio Software Overview
+---------------------------
+
+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.
+
+

lib_xua/doc/rst/sw_adat.rst

@@ -0,0 +1,54 @@
+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.

lib_xua/doc/rst/sw_audio.rst

@@ -0,0 +1,176 @@
+.. _usb_audio_sec_audio:
+
+AudioHub/I2S
+............
+
+The AudioHub task performs many functions. It receives and transmits samples from/to the decoupler or mixer core over an XC channel.
+
+It also drives several in and out I2S/TDM channels to/from a CODEC, DAC, ADC etc - from now on 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. 
+
+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.
+
+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). 
+
+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 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.
+
+.. _usb_audio_codec_signals:
+
+.. list-table:: I2S Signals
+   :header-rows: 1
+   :widths: 20 80
+  
+   * - Signal
+     - Description
+   * - LRCLK 
+     - The word clock, transition at the start of a sample
+   * - BCLK     
+     - The bit clock, clocks data in and out
+   * - SDIN
+     - Sample data in (from CODEC/ADC to the XMOS device)
+   * - SDOUT 
+     - Sample data out (from the XMOS device to CODEC/DAC)
+   * - MCLK
+     - The master clock running the CODEC/DAC/ADC
+
+The bit clock controls the rate at which data is transmitted to and from the external audio hardware.
+
+In the case where the XMOS device is the master, it divides the MCLK to generate the required signals for both BCLK and LRCLK,
+with BCLK then being used to clock data in (SDIN) and data out (SDOUT) of the external audio hardware.
+
+:ref:`usb_audio_example_clock_divides` shows some example clock frequencies and divides for different sample rates:
+
+.. _usb_audio_example_clock_divides:
+
+.. list-table:: Clock Divide examples
+  :header-rows: 1
+  :widths: 30 25 25 20
+
+  * - Sample Rate (kHz)    
+    - MCLK (MHz)
+    - BCLK (MHz)
+    - Divide
+  * - 44.1  
+    - 11.2896 
+    - 2.819 
+    - 4
+  * - 88.2 
+    - 11.2896
+    - 5.638 
+    - 2
+  * - 176.4 
+    - 11.2896
+    - 11.2896 
+    - 1
+  * - 48 
+    - 24.576 
+    - 3.072 
+    - 8
+  * - 96 
+    - 24.576 
+    - 6.144 
+    - 4
+  * - 192 
+    - 24.576 
+    - 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. 
+
+
+Port Configuration (xCORE Master)
++++++++++++++++++++++++++++++++++
+
+The default software configuration is xCORE is I2S master.  That is, the XMOS device provides the BCLK and LRCLK signals to the external audio hardware
+
+xCORE ports and XMOS clocks provide many valuable features for implementing I2S. This section describes how these are configured
+and used to drive the I2S interface.
+
+.. only:: latex
+
+  .. figure:: images/port_config.pdf
+
+    Ports and Clocks (xCORE master)
+
+.. only:: html
+
+  .. figure:: images/port_config.png
+
+    Ports and Clocks (xCORE master)
+
+The code to configure the ports and clocks is in the ``ConfigAudioPorts()`` function. Developers should not need to modify this.
+
+The xCORE inputs MCLK and divides it down to generate BCLK and LRCLK. 
+
+To achieve this MCLK is input into the device using the 1-bit port ``p_mclk``. This is attached to the clock block ``clk_audio_mclk``, which is in
+turn used to clock the BCLK port, ``p_bclk``. BCLK is used to clock the LRCLK (``p_lrclk``) and data signals SDIN (``p_sdin``) and SDOUT (``p_sdout``). 
+
+Again, a clock block is used (``clk_audio_bclk``) which has ``p_bclk`` as its input and is used to clock the ports ``p_lrclk``, ``p_sdin`` and ``p_sdout``.
+The preceding diagram shows the connectivity of ports and clock blocks.
+
+``p_sdin`` and ``p_sdout`` are configured as buffered ports with a transfer width of 32, so all 32 bits are
+input in one input statement. This allows the software to input, process and output 32-bit words, whilst the ports serialize and
+deserialize to the single I/O pin connected to each port.
+
+xCORE-200 series devices have the ability to divide an extenal 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 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.
+
+Changing Audio Sample Frequency
++++++++++++++++++++++++++++++++
+
+.. _usb_audio_sec_chang-audio-sample:
+
+When the host changes sample frequency, a new frequency is sent to
+the audio driver core by Endpoint 0 (via the buffering cores and mixer).
+
+First, a change of sample frequency is reported by sending the new frequency over an XC channel. The audio core
+detects this by checking for the presence of a control token on the channel channel 
+
+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.
+
+
+

lib_xua/doc/rst/sw_clocking.rst

@@ -0,0 +1,35 @@
+.. _usb_audio_sec_clock_recovery:
+
+External Clock Recovery (ClockGen)
+----------------------------------
+
+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.
+
+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).
+
+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.
+
+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.  
+
+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.
+
+This 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.
+
+
+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.

lib_xua/doc/rst/sw_detail.rst

@@ -0,0 +1,27 @@
+
+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
+..
+

lib_xua/doc/rst/sw_dfu.rst

@@ -0,0 +1,27 @@
+.. _usb_audio_sec_dfu:
+
+Device Firmware Upgrade (DFU)
+=============================
+
+The DFU interface handles updates to the boot image of the device. The DFU code is called from 
+the Endpoint 0 core.
+
+The interface links USB to the XMOS flash user library (see :ref:`libflash_api`). In Application 
+mode the DFU can accept commands to reset the device into DFU mode. There are two ways to do this:
+
+-  The host can send a ``DETACH`` request and then reset the
+   device. If the device is reset by the host within a specified
+   timeout, it will start in DFU mode (this is initially set to
+   one second and is configurable from the host).
+
+-  The host can send a custom user request
+   ``XMOS_DFU_RESETDEVICE`` to the DFU interface that 
+   resets the device immediately into DFU mode.
+
+
+Once the device is in DFU mode. The DFU interface can accept commands defined by the 
+`DFU 1.1 class specification <http://www.usb.org/developers/devclass_docs/DFU_1.1.pdf*USB>`_. In
+addition the interface accepts the custom command ``XMOS_DFU_REVERTFACTORY`` which reverts the active
+boot image to the factory image. Note that the XMOS specific command request
+identifiers are defined in ``dfu_types.h`` within ``module_dfu``.
+

lib_xua/doc/rst/sw_ep0.rst

@@ -0,0 +1,349 @@
+|newpage|
+
+.. _usb_audio_sec_usb:
+
+Endpoint 0: Management and Control
+..................................
+
+All USB devices must support a mandatory control endpoint, Endpoint 0.  This controls the management tasks of the USB device.
+
+These tasks can be generally split into enumeration, audio configuration and firmware upgrade requests.
+
+Enumeration
+~~~~~~~~~~~
+
+When the device is first attached to a host, enumeration occurs.  This process involves the host interrogating the device as to its functionality. The device does this by presenting several interfaces to the host via a set of descriptors.
+
+During the enumeration process the host will issue various commands to the device including assigning the device a unique address on the bus.
+
+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:
+
+    - Requests for standard descriptors (Device descriptor, configuration descriptor etc) and string descriptors
+    - USB GET/SET INTERFACE requests
+    - USB GET/SET_CONFIGURATION requests
+    - USB SET_ADDRESS requests
+
+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()`` 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()``).
+
+The function returns ``XUD_RES_ERR`` if the request was not recognised by the ``USB_StandardRequests()`` function and a STALL has been issued. 
+
+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.
+
+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.
+
+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.
+
+Any device specific requests are handled - in this case Audio Class, MIDI class, DFU requests etc.  
+
+Some of the common Audio Class requests and their associated behaviour will now be examined. 
+
+Audio Requests
+++++++++++++++
+
+When the host issues an audio request (e.g. sample rate or volume change), it sends a command to Endpoint 0. Like all requests this is returned from ``USB_GetSetupPacket()``. After some parsing (namely as Class Request to an Audio Interface) the request is handled by either the ``AudioClassRequests_1()`` or ``AudioClassRequests_2()`` function (based on whether the device is running in Audio Class 1.0 or 2.0 mode).
+
+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.
+
+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 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.
+
+.. _usb_audio_sec_audio-requ-volume: 
+
+Audio Request: Volume Control
++++++++++++++++++++++++++++++
+
+When the host requests a volume change, it
+sends an audio interface request to Endpoint 0. An array is
+maintained in the Endpoint 0 core that is updated with such a
+request.
+
+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
+component (if the mixer component is used). Handling the volume in the
+mixer gives the decoupler more performance to handle more channels.
+
+If the effect of the volume control array on the audio input and
+output is implemented by the decoupler, the ``decoupler`` core 
+reads the volume values from this array. Note that this array is shared
+between Endpoint 0 and the decoupler core. This is done in a safe
+manner, since only Endpoint 0 can write to the array, word update
+is atomic between cores and the decoupler core only reads from
+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
+are described in :ref:`usb_audio_sec_mixer`.
+
+Audio Endpoints (Endpoint Buffer and Decoupler)
+...............................................
+
+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. 
+
+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
+~~~~~~~~~
+
+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
+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``.
+
+Audio Buffering Scheme
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This scheme is executed by co-operation between the buffering
+core, the decouple core and the XUD library.
+
+For data going from the device to the host the following scheme is
+used:
+
+
+#. The decouple core receives samples from the audio 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
+   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
+   packet.
+
+#. When the buffer core has sent this buffer, it signals to the
+   decouple that the buffer has been sent and the decouple core
+   moves the read pointer of the FIFO.
+
+
+For data going from the host to the device the following scheme is
+used:
+
+
+#. The decouple core passes a pointer to the buffering core
+   pointing into a FIFO of data and signals to the XUD library that
+   the buffering 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.
+
+#. Upon receiving this signal the decoupler core updates the
+   write pointer of the FIFO and provides a new pointer to the
+   buffering 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.
+
+
+Decoupler/Audio Core interaction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To meet timing requirements of the audio system, 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).  
+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
+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 
+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.
+
+The complete communication scheme is shown in the table below (for non sample
+frequency change case):
+
+
+.. table::  Decouple/Audio System Channel Communication
+
+ +-----------------+-----------------+-----------------------------------------+
+ | Decouple        | Audio System    | Note                                    |
+ +=================+=================+=========================================+
+ |                 | outuint()       | Audio system requests sample exchange   |
+ +-----------------+-----------------+-----------------------------------------+
+ | inuint()        |                 | Interrupt fires and inuint performed    |
+ +-----------------+-----------------+-----------------------------------------+
+ | outuint()       |                 | Decouple sends ack                      |
+ +-----------------+-----------------+-----------------------------------------+
+ |                 | testct()        | Checks for CT indicating SF change      |
+ +-----------------+-----------------+-----------------------------------------+
+ |                 | inuint()        | Word indication ACK input (No SF change)|
+ +-----------------+-----------------+-----------------------------------------+
+ | inuint()        | outuint()       | Sample transfer (Device to Host)        |
+ +-----------------+-----------------+-----------------------------------------+
+ | inuint()        | outuint()       |                                         |
+ +-----------------+-----------------+-----------------------------------------+
+ | inuint()        | outuint()       |                                         |
+ +-----------------+-----------------+-----------------------------------------+
+ | ...             |                 |                                         |
+ +-----------------+-----------------+-----------------------------------------+
+ | outuint()       | inuint()        | Sample transfer (Host to Device)        |
+ +-----------------+-----------------+-----------------------------------------+
+ | outuint()       | inuint()        |                                         |
+ +-----------------+-----------------+-----------------------------------------+
+ | outuint()       | inuint()        |                                         |
+ +-----------------+-----------------+-----------------------------------------+
+ | outuint()       | inuint()        |                                         |
+ +-----------------+-----------------+-----------------------------------------+
+ | ...             |                 |                                         |
+ +-----------------+-----------------+-----------------------------------------+
+
+.. note::
+    The request and acknowledgement sent to/from Decouple 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) 
+
+Asynchronous Feedback
++++++++++++++++++++++
+
+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*.
+
+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.
+
+After each received USB 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.
+
+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.
+
+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.
+
+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
+
+ +-----------------+-------------+-------------+
+ | Frequency (kHz) | Min Packet  | Max Packet  |
+ +=================+=============+=============+
+ | 44.1            | 5           | 6           |
+ +-----------------+-------------+-------------+
+ | 48              | 5           | 7           |
+ +-----------------+-------------+-------------+
+ | 88.2            | 10          | 11          |
+ +-----------------+-------------+-------------+
+ | 96              | 11          | 13          |
+ +-----------------+-------------+-------------+
+ | 176.4           | 20          | 21          | 
+ +-----------------+-------------+-------------+
+ | 192             | 23          | 25          |
+ +-----------------+-------------+-------------+
+
+
+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.
+
+
+
+.. .. _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: 

lib_xua/doc/rst/sw_hid.rst

@@ -0,0 +1,48 @@
+Audio Controls via Human Interface Device (HID)
+------------------------------------------------
+
+The design supports simple audio controls such as play/pause, volume up/down etc via the USB Human
+Interface Device Class Specification.
+
+This functionality is enabled by setting the ``HID_CONTROLS`` define to ``1``.  Setting to ``0`` 
+disables this feature.
+
+When turned on the following items are enabled:
+
+    #. HID descriptors are enabled in the Configuration Descriptor informing the host that the device has HID interface
+    #. A Get Report Descriptor request is enabled in ``endpoint0``.
+    #. Endpoint data handling is enabled in the ``buffer`` core
+
+The Get Descriptor Request enabled in endpoint 0 returns the report descriptor for the HID device.
+This details the format of the HID reports returned from the device to the host.  It maps a bit in 
+the report to a function such as play/pause.
+
+The USB Audio Framework implements a report descriptor that should fit most basic audio device controls.
+If further controls are necessary the HID Report Descriptor in ``descriptors.h`` should be modified.  
+The default report size is 1 byte with the format as follows:
+
+.. table:: Default HID Report Format
+
+   +-------------+-------------------------+
+   | Bit         | Function                |
+   +=============+=========================+
+   | 0           | Play/Pause              |
+   +-------------+-------------------------+
+   | 1           | Scan Next Track         |
+   +-------------+-------------------------+
+   | 2           | Scan Prev Track         |
+   +-------------+-------------------------+
+   | 3           | Volume Up               |
+   +-------------+-------------------------+
+   | 4           | Volume Down             |
+   +-------------+-------------------------+
+   | 5           | Mute                    |
+   +-------------+-------------------------+
+   | 6-7         | Unused                  |
+   +-------------+-------------------------+
+
+On each HID report request from the host the function ``Vendor_ReadHidButtons(unsigned char hidData[])`` is called from ``buffer()``.  This function is passed an array ``hidData[]`` by reference.  The programmer should report the state of his buttons into this array. For example, if a volume up command is desired, bit 3 should be set to 1, else 0.
+
+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`.

lib_xua/doc/rst/sw_iap.rst

@@ -0,0 +1,9 @@
+
+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.

lib_xua/doc/rst/sw_midi.rst

@@ -0,0 +1,7 @@
+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``.

lib_xua/doc/rst/sw_mixer.rst

@@ -0,0 +1,181 @@
+.. _usb_audio_sec_mixer:
+
+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 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 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.
+
+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:
+
+   * The USB inputs to the host---these samples are sent to the decoupler core.
+
+   * The outputs to the audio interface on the device---these samples
+     are sent to the audio driver.
+
+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.
+
+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.
+
+Control
+~~~~~~~
+
+The mixers can receive the following control commands from the Endpoint 0 core via a channel: 
+
+.. list-table:: Mixer Component Commands
+ :header-rows: 1
+
+ * - Command
+   - Description
+
+ * - ``SET_SAMPLES_TO_HOST_MAP``
+   - Sets the source of one of the audio streams going to the host.
+
+ * - ``SET_SAMPLES_TO_DEVICE_MAP``
+   - Sets the source of one of the audio streams going to the audio
+     driver.
+
+ * - ``SET_MIX_MULT``
+   - Sets the multiplier for one of the inputs to a mixer.
+
+ * - ``SET_MIX_MAP``
+   - Sets the source of one of the inputs to a mixer.
+
+ * - ``SET_MIX_IN_VOL``
+   - If volume adjustment is being done in the mixer, this command
+     sets the volume multiplier of one of the USB audio inputs.
+
+ * - ``SET_MIX_OUT_VOL``
+   - If volume adjustment is being done in the mixer, this command
+     sets the volume multiplier of one of the USB audio outputs.
+
+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. 
+
+For details, consult the README file in the host_usb_mixer_control directory.
+
+The main requirements of this control are to
+
+  * Set the mapping of input channels into the mixer
+  * Set the coefficients for each mixer output of 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.
+
+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. 
+
+First consider the inputs to the mixer::
+
+  ./xmos_mixer --display-aud-channel-map 0
+
+displays which channels are mapped to which mixer inputs::
+
+  ./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::
+
+  ./xmos_mixer --display-aud-channel-map 0
+
+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::
+
+  ./xmos_mixer --display-aud-channel-map-sources 0
+
+So 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
+
+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.
+
+The mixer nodes need to be individually set. They can be displayed
+with::
+
+  ./xmos_mixer --display-mixer-nodes 0
+
+To get the audio from the analogue inputs to outputs 1 and 2, nodes 80
+and 89 need to be set::
+
+  ./xmos_mixer --set-value 0 80 0
+  ./xmos_mixer --set-value 0 89 0
+
+At the same time, the original mixer outputs can be muted::
+
+  ./xmos_mixer --set-value 0 0 -inf
+  ./xmos_mixer --set-value 0 9 -inf
+
+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. 
+
+To demonstrate this, firstly undo the changes above::
+
+  ./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::
+
+  ./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.
+
+
+
+

lib_xua/doc/rst/sw_pdm.rst

@@ -0,0 +1,114 @@
+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. 
+
+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
+to user selectable output sample rates. 
+
+.. note:: 
+    The ``lib_mic_array`` library is only available for xCORE-200 series devices.
+
+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:
+
+ .. figure:: images/pdm_chan4.pdf
+            :width: 100%
+
+            One to four channel count PDM interface
+
+
+for 5-8 channels three logical cores are required, as shown below:
+
+ .. figure:: images/pdm_chan8.pdf
+            :width: 100%
+
+            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).
+
+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.
+
+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. 
+
+
+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:
+
+.. _pdm_wire_table:
+
+.. list-table:: PDM microphone data and signal wires
+     :class: vertical-borders horizontal-borders
+     
+     * - *CLOCK*
+       - Clock line, the PDM clock the used by the microphones to 
+         drive the data out.
+     * - *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 
+PDM clock source. 
+
+The input clock for the microphones can be generated in a multitude of
+ways. For example, a 3.072MHz clock can be generated on the board, or the xCORE can
+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
++++++++++++++++++++++++++++++++++++++++++++++
+
+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 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:: 
+
+    configure_clock_src_divide(pdmclk, p_mclk, MCLK_TO_PDM_CLK_DIV);
+    configure_port_clock_output(p_pdm_clk, pdmclk);
+    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::
+
+    par
+    {
+        mic_array_pdm_rx(p_pdm_mics, c_4x_pdm_mic_0, c_4x_pdm_mic_1);
+        mic_array_decimate_to_pcm_4ch(c_4x_pdm_mic_0, c_ds_output[0]);
+        mic_array_decimate_to_pcm_4ch(c_4x_pdm_mic_1, c_ds_output[1]);
+        pdm_process(c_ds_output, c_pcm_out);
+    }
+
+The ``pdm_process()`` task includes the main integration code, it takes audio from the ``lib_mic_array`` cores, buffers 
+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
+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
+is required.

lib_xua/doc/rst/sw_resource.rst

@@ -0,0 +1,51 @@
+.. _usb_audio_sec_resource_usage:
+
+Resource Usage
+--------------
+
+The following table details the resource usage of each
+component of the reference design software.
+
+.. table:: Resource Usage
+
+ +---------------+---------------+---------------------+-------------------------------------+
+ |   Component   |   Cores       |   Memory (KB)       |   Ports                             |
+ +===============+===============+=====================+=====================================+
+ | XUD library   |  1            | 9 (6 code)          | ULPI ports                          |
+ |               |               |                     |                                     |
+ +---------------+---------------+---------------------+-------------------------------------+
+ | Endpoint 0    |  1            | 17.5 (10.5 code)    | none                                |
+ +---------------+---------------+---------------------+-------------------------------------+
+ | USB Buffering |  1            | 22.5 (1 code)       | none                                |
+ +---------------+---------------+---------------------+-------------------------------------+
+ | Audio driver  |  1            | 8.5 (6 code)        | See :ref:`usb_audio_sec_audio`      |
+ +---------------+---------------+---------------------+-------------------------------------+
+ | S/PDIF Tx     |  1            | 3.5 (2 code)        | 1 x 1 bit port                      |
+ +---------------+---------------+---------------------+-------------------------------------+
+ | S/PDIF Rx     |  1            | 3.7 (3.7 code)      | 1 x 1 bit port                      |
+ +---------------+---------------+---------------------+-------------------------------------+
+ | 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                   |
+ +---------------+---------------+---------------------+-------------------------------------+
+ | Mixer         |  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.
+
+.. note::
+
+    The XUD library requires an 80MIPS core to function correctly
+    (i.e. on a 500MHz part only six cores can run).
+
+.. 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.

lib_xua/doc/rst/sw_spdif.rst

@@ -0,0 +1,140 @@
+S/PDIF Transmit
+...............
+
+``lib_xua`` supports the development of devices with S/PDIF transmit throught the use of ``lib_spdif``.
+The XMOS S/SPDIF transmitter component runs in a single core and supports sample-rates upto 192kHz.
+
+The S/PDIF transmitter core takes PCM audio samples via a channel and outputs them
+in S/PDIF format to a port.  A lookup table is used to encode the audio data into the required format. 
+
+It receives samples from the Audio I/O core two at a time (for left and right). For each sample,
+it performs a lookup on each byte, generating 16 bits of encoded data which it outputs to a port.
+
+S/PDIF sends data in frames, each containing 192 samples of the left and right channels.
+
+Audio samples are encapsulated into S/PDIF words (adding preamble, parity, channel status and validity
+bits) and transmitted in biphase-mark encoding (BMC) with respect to an *external* master clock.
+
+Note that a minor change to the ``SpdifTransmitPortConfig`` function would enable *internal* master
+clock generation (e.g. when clock source is already locked to desired audio clock).
+
+..  list-table:: S/PDIF Capabilities
+   
+   * - **Sample frequencies**   
+     - 44.1, 48, 88.2, 96, 176.4, 192 kHz
+   * - **Master clock ratios** 
+     - 128x, 256x, 512x
+   * - **Library**  
+     - ``lib_spdif``
+
+Clocking
+++++++++
+
+.. only:: latex
+
+ .. figure:: images/spdif.pdf
+
+   D-Type Jitter Reduction
+
+.. only:: html
+
+ .. figure:: images/spdif.png
+
+   D-Type Jitter Reduction
+
+
+The S/PDIF signal is output at a rate dictated by the external master clock. The master clock must 
+be 1x 2x or 4x the BMC bit rate (that is 128x 256x or 512x audio sample rate, respectively). 
+For example, the minimum master clock frequency for 192kHz is therefore 24.576MHz.
+
+This resamples the master clock to its clock domain (oscillator), which introduces jitter of 2.5-5 ns on the S/PDIF signal. 
+A typical jitter-reduction scheme is an external D-type flip-flop clocked from the master clock (as shown in the preceding diagram).
+
+Usage
++++++
+
+The interface to the S/PDIF transmitter core is via a normal channel with streaming built-ins
+(``outuint``, ``inuint``). Data format should be 24-bit left-aligned in a 32-bit word: ``0x12345600``
+
+The following protocol is used on the channel:
+
+.. list-table:: S/PDIF Component Protocol
+
+  * - ``outct`` 
+    -  New sample rate command
+  * - ``outuint`` 
+    - Sample frequency (Hz)
+  * - ``outuint`` 
+    - Master clock frequency (Hz)
+  * - ``outuint``
+    - Left sample
+  * - ``outuint``
+    - Right sample 
+  * - ``outuint`` 
+    - Left sample
+  * - ``outuint`` 
+    - Right sample
+  * - ``...``
+    -
+  * - ``...``
+    -
+
+
+
+Output stream structure
++++++++++++++++++++++++
+
+The stream is composed of words with the following structure shown in
+:ref:`usb_audio_spdif_stream_structure`. The channel status bits are
+0x0nc07A4, where c=1 for left channel, c=2 for right channel and n
+indicates sampling frequency as shown in :ref:`usb_audio_spdif_sample_bits`.
+
+.. _usb_audio_spdif_stream_structure:
+
+.. list-table:: S/PDIF Stream Structure
+     :header-rows: 1
+     :widths: 10 32 58
+     
+     * - Bits 
+       - 
+       -
+     * - 0:3
+       - Preamble 
+       - Correct B M W order, starting at sample 0
+     * - 4:27 
+       - Audio sample 
+       - Top 24 bits of given word
+     * - 28 
+       - Validity bit 
+       - Always 0
+     * - 29 
+       - Subcode data (user bits) 
+       - Unused, set to 0
+     * - 30 
+       - Channel status 
+       - See below
+     * - 31 
+       - Parity 
+       - Correct parity across bits 4:30
+     
+
+.. _usb_audio_spdif_sample_bits:
+
+.. list-table:: Channel Status Bits
+  :header-rows: 1
+
+  * - Frequency (kHz)
+    - n
+  * - 44.1
+    - 0
+  * - 48
+    - 2
+  * - 88.2
+    - 8
+  * - 96
+    - A
+  * - 176.4
+    - C
+  * - 192
+    - E
+

lib_xua/doc/rst/sw_spdif_rx.rst

@@ -0,0 +1,95 @@
+S/PDIF Receive
+---------------
+
+XMOS devices can support S/PDIF receive up to 192kHz. 
+
+The S/PDIF receiver module uses a clockblock 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. 
+
+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
+     :widths: 10 32
+     
+     * - Bits 
+       - 
+     * - 0:3
+       - A tag (see below) 
+     * - 4:28
+       - PCM encoded sample value
+     * - 29:31
+       - User bits (parity, etc)
+
+The tag has one of three values:
+
+.. list-table:: S/PDIF RX Tags
+     :header-rows: 1
+     :widths: 10 32
+     
+     * - Tag
+       - Meaning
+     * - FRAME\_X
+       - Sample on channel 0 (Left for stereo)
+     * - FRAME\_Y
+       - Sample on another channel (Right if for stereo)
+     * - 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.
+
+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`)
+
+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).
+
+Ideally the parity of each word/sample received should be checked.  This is done using the built in 
+``crc32`` function (see ``xs1.h``):
+
+.. literalinclude:: sc_usb_audio/module_usb_audio/clocking/clockgen.xc
+  :start-after: //:badParity
+  :end-before: //:
+
+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::
+
+
+  while(1) 
+  {
+     c_spdif_rx :> data;
+
+     if(badParity(data)
+       continue;
+
+     tag = data & 0xF; 
+
+     /* Extract 24bit audio sample */
+     sample = (data << 4) & 0xFFFFFF00;
+
+     switch(tag)
+     {
+       case FRAME_X:
+       case FRAME_X:
+         // Store left
+         break;
+
+       case FRAME_Z:
+         // Store right
+         break;
+     }
+  }
+
+
+
+

lib_xua/doc/rst/sw_usb_audio_class.rst

@@ -0,0 +1,57 @@
+USB Audio Class Version Support
+-------------------------------
+
+The XMOS USB Audio framework supports both USB Audio Class 1.0 and Audio Class 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 improvement, amoungst 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 
++++++++++++++++
+
+Audio Class 1.0 is fully supported in Apple OSX.  Audio Class 1.0 is fully supported in all modern Microsoft Windows operating systems (i.e. Windows XP and later). 
+
+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 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
+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. 
+
+.. note::
+
+    To ensure specification compliance, Audio Class 1.0 mode *always* operates at full-speed USB. 
+
+The device will operate in full-speed Audio Class 1.0 mode if one of the following is true:
+
+-  The code is compiled for USB Audio Class 1.0 only.
+
+-  The code is compiled for USB Audio Class 2.0 and it is connected
+   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`. 
+
+When running in Audio Class 1.0 mode the following restrictions are applied:
+
+- MIDI is disabled.
+
+- DFU is disabled (Since Windows operating systems would prompt for a DFU driver to be installed)
+
+Due to bandwidth limitations of full-speed USB the following sample-frequency restrictions are also applied:
+
+-  Sample rate is limited to a maximum of 48kHz if both input and output are enabled.
+
+-  Sample rate is limited to a maximum of 96kHz if only input *or* output is enabled.
+

lib_xua/doc/rst/sw_xud.rst

@@ -0,0 +1,18 @@
+
+XMOS USB Device (XUD) Library
+.............................
+
+All low level communication with the USB host is handled by the XMOS USB Device (XUD) library - `lib_xud`
+
+The ``XUD_Main()`` function runs in its own core and communicates with endpoint cores though a 
+mixture of shared memory and channel communications.
+
+For more details and full XUD API documentation please refer to `lib_xud`.
+
+:ref:`usb_audio_threads` shows the XUD library communicating with two other cores:
+
+-  Endpoint 0: This core controls the enumeration/configuration tasks of the USB device.
+
+-  Endpoint Buffer: This core sends/receives data packets from the XUD library.  
+   The core receives audio data from the AudioHub, MIDI data from the MIDI core etc.
+

lib_xua/doc/rst/using.rst

@@ -0,0 +1,176 @@
+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`.
+
+Reviewing application note AN00246 is highly recommended at this point.
+
+Library structure
+~~~~~~~~~~~~~~~~~
+
+The code is split into several directories.
+
+.. list-table:: lib_xua structure
+
+ * - core
+   - Common code for USB audio applications
+ * - midi
+   - MIDI I/O code
+ * - dfu
+   - Device Firmware Upgrade code
+
+
+Note, the midi and dfu directories are potential candidates for separate libs in their own right.
+
+
+Including in a project
+~~~~~~~~~~~~~~~~~~~~~~
+
+All `lib_xua` functions can be accessed via the ``xua.h`` header filer::
+
+  #include <xua.h>
+
+It is also required to add ``lib_xua`` to the ``USED_MODULES`` field of your application Makefile::
+
+  USED_MODULES = .. lib_xua ...
+
+
+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 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
+
+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` defintions 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 - 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 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::
+
+    #ifndef _XUA_CONF_H_
+    #define _XUA_CONF_H_
+
+    /* Output channel count */
+    #define XUA_NUM_USB_CHAN_OUT (2)
+    
+    /* Product string */
+    #define XUA_PRODUCT_STR_A2 "My Product"
+
+    #endif
+
+
+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``.
+
+

lib_xua/doc/rst/xdoc.conf

@@ -1,2 +1,2 @@
 XMOSNEWSTYLE = 1
-DOXYGEN_DIRS=../../api
+DOXYGEN_DIRS=../../api

lib_xua/host/xmosdfu/.gitignore

@@ -0,0 +1 @@
+xmosdfu

lib_xua/host/xmosdfu/xmosdfu.cpp

@@ -1,3 +1,4 @@
+// Copyright (c) 2012-2018, XMOS Ltd, All rights reserved
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -307,8 +308,20 @@ int read_dfu_image(char *file)
     {
         unsigned int numBytes = 0;
         numBytes = dfu_upload(0, block_count, 64, block_data);
+        /* Upload is completed when dfu_upload() returns an empty block */
         if (numBytes == 0)
         {
+            /* If upload is complete, but no block has been read,
+               issue a warning about the upgrade image
+            */
+            if (block_count==0) {
+                printf("... WARNING: Upgrade image size is 0: check if image is present in the flash\n");
+            }
+            break;
+        }
+        else if (numBytes < 0)
+        {
+            fprintf(stderr,"dfu_upload error (%d)\n", numBytes);
             break;
         }
         fwrite(block_data, 1, block_size, outFile);
@@ -338,8 +351,8 @@ static void print_usage(const char *program_name, const char *error_msg)
     print_device_list(stderr, "      ");
 
     fprintf(stderr, "    And COMMAND is one of:\n");
-    fprintf(stderr, "       --download <firmware> : install a new firmware\n");
-    fprintf(stderr, "       --upload <firmware>   : extract a firmware image\n");
+    fprintf(stderr, "       --download <firmware> : write an upgrade image\n");
+    fprintf(stderr, "       --upload <firmware>   : read the upgrade image\n");
     fprintf(stderr, "       --revertfactory       : revert to the factory image\n");
     fprintf(stderr, "       --savecustomstate     : \n");
     fprintf(stderr, "       --restorecustomstate  : \n");

lib_xua/module_build_info

@@ -1,36 +1,68 @@
-# You can set flags specifically for your module by using the MODULE_XCC_FLAGS
-# variable. So the following
-#
-#   MODULE_XCC_FLAGS = $(XCC_FLAGS) -O3
-#
-# specifies that everything in the modules should have the application
-# build flags with -O3 appended (so the files will build at
-# optimization level -O3).
-#
-# You can also set MODULE_XCC_C_FLAGS, MODULE_XCC_XC_FLAGS etc..
+VERSION = 1.1.0
 
-MODULE_XCC_FLAGS = $(XCC_FLAGS) -O3 -DREF_CLK_FREQ=100 -fasm-linenum -fcomment-asm  -fsubword-select
+DEPENDENT_MODULES = lib_logging(>=3.0.0) \
+                    lib_xassert(>=4.0.0) \
+                    lib_xud(>=1.0.0) \
+                    lib_spdif(>=4.0.0) \
+                    lib_mic_array(>=4.0.0)
+
+MODULE_XCC_FLAGS = $(XCC_FLAGS) \
+                   -O3 \
+                   -DREF_CLK_FREQ=100 \
+                   -fasm-linenum \
+                   -fcomment-asm
+
+# Core
+XCC_FLAGS_xua_endpoint0.c = $(MODULE_XCC_FLAGS) -Os -mno-dual-issue
+XCC_FLAGS_xua_ep0_uacreqs.xc = $(MODULE_XCC_FLAGS) -Os -mno-dual-issue
+XCC_FLAGS_dbcalc.xc = $(MODULE_XCC_FLAGS) -Os -mno-dual-issue
+XCC_FLAGS_audioports.c = $(MODULE_XCC_FLAGS) -Os -mno-dual-issue
+XCC_FLAGS_audioports.xc = $(MODULE_XCC_FLAGS) -Os -mno-dual-issue
+
+# DFU
+XCC_FLAGS_dfu.xc = $(MODULE_XCC_FLAGS) -Os -mno-dual-issue
+XCC_FLAGS_flash_interface.c = $(MODULE_XCC_FLAGS) -Os -mno-dual-issue
+XCC_FLAGS_flashlib_user.c = $(MODULE_XCC_FLAGS) -Os -mno-dual-issue
 
 OPTIONAL_HEADERS += xua_conf.h
 
-VERSION = 0.1.2
+EXPORT_INCLUDE_DIRS = api \
+                      src/core \
+                      src/core/audiohub \
+                      src/core/buffer/ep \
+                      src/core/endpoint0 \
+                      src/dfu
 
-DEPENDENT_MODULES = lib_logging(>=2.1.0) lib_xud(>=0.1.0)
+INCLUDE_DIRS = $(EXPORT_INCLUDE_DIRS) \
+               src/core/buffer/decouple \
+               src/core/clocking \
+               src/core/mixer \
+               src/core/pdm_mics \
+               src/core/ports \
+               src/core/support \
+               src/core/support/powersave \
+               src/core/user \
+               src/core/user/audiostream \
+               src/core/user/hid \
+               src/core/user/hostactive \
+               src/midi
 
-#ignore host dir
-SOURCE_DIRS = src/*
+SOURCE_DIRS = src/core \
+              src/core/audiohub \
+              src/core/buffer/decouple \
+              src/core/buffer/ep \
+              src/core/clocking \
+              src/core/endpoint0 \
+              src/core/mixer \
+              src/core/pdm_mics \
+              src/core/ports \
+              src/core/support \
+              src/core/support/powersave \
+              src/core/user/audiostream \
+              src/core/user/hostactive \
+              src/core/xuduser \
+              src/dfu \
+              src/hid \
+              src/midi
 
-#core
 EXCLUDE_FILES += descriptors_2.rst
-XCC_FLAGS_xua_endpoint0.c = -Os -mno-dual-issue $(XCC_FLAGS)
-XCC_FLAGS_xua_ep0_uacreqs.xc = -Os -mno-dual-issue $(XCC_FLAGS)
-XCC_FLAGS_dbcalc.xc = -Os -mno-dual-issue $(XCC_FLAGS)
-XCC_FLAGS_audioports.c = -Os -mno-dual-issue $(XCC_FLAGS)
-XCC_FLAGS_audioports.xc = -Os -mno-dual-issue $(XCC_FLAGS)
-
-#dfu
-XCC_FLAGS_dfu.xc = -Os -mno-dual-issue $(XCC_FLAGS)
-XCC_FLAGS_flash_interface.c = -Os -mno-dual-issue $(XCC_FLAGS)
-XCC_FLAGS_flashlib_user.c = -Os -mno-dual-issue $(XCC_FLAGS)
-
-

lib_xua/src/core/audiohub/audiohub_adat.h

@@ -0,0 +1,52 @@
+// Copyright (c) 2018, XMOS Ltd, All rights reserved
+
+unsigned adatCounter = 0;
+unsigned adatSamples[8];
+
+#pragma unsafe arrays
+static inline void TransferAdatTxSamples(chanend c_adat_out, const unsigned samplesFromHost[], int smux, int handshake)
+{
+
+    /* Do some re-arranging for SMUX.. */
+    unsafe
+    {
+        unsigned * unsafe samplesFromHostAdat = &samplesFromHost[ADAT_TX_INDEX];
+
+        /* Note, when smux == 1 this loop just does a straight 1:1 copy */
+        //if(smux != 1)
+        {
+            int adatSampleIndex = adatCounter;
+            for(int i = 0; i < (8/smux); i++)
+            {
+                adatSamples[adatSampleIndex] = samplesFromHostAdat[i];
+                adatSampleIndex += smux;
+            }
+        }
+    }
+
+    adatCounter++;
+
+    if(adatCounter == smux)
+    {
+
+#ifdef ADAT_TX_USE_SHARED_BUFF
+        unsafe
+        {
+            /* Wait for ADAT core to be done with buffer */
+            /* Note, we are "running ahead" of the ADAT core */
+            inuint(c_adat_out);
+
+            /* Send buffer pointer over to ADAT core */
+            volatile unsigned * unsafe samplePtr = &adatSamples;
+            outuint(c_adat_out, (unsigned) samplePtr);
+        }
+#else
+#pragma loop unroll
+        for (int i = 0; i < 8; i++)
+        {
+            outuint(c_adat_out, samplesFromHost[ADAT_TX_INDEX + i]);
+        }
+#endif
+        adatCounter = 0;
+    }
+}

lib_xua/src/core/audiohub/audiohub_dsd.h

@@ -0,0 +1,94 @@
+// Copyright (c) 2018, XMOS Ltd, All rights reserved
+
+#if (DSD_CHANS_DAC != 0)
+extern buffered out port:32 p_dsd_dac[DSD_CHANS_DAC];
+extern buffered out port:32 p_dsd_clk;
+#endif
+
+/* I2S Data I/O*/
+#if (I2S_CHANS_DAC != 0)
+extern buffered out port:32 p_i2s_dac[I2S_WIRES_DAC];
+#endif
+
+#if (I2S_CHANS_ADC != 0)
+extern buffered in port:32  p_i2s_adc[I2S_WIRES_ADC];
+#endif
+
+/* This function performs the DSD native loop and outputs a 32b DSD stream per loop */
+static inline void DoDsdNative(unsigned samplesOut[], unsigned &dsdSample_l, unsigned &dsdSample_r, unsigned divide)
+{
+     /* 8 bits per chan, 1st 1-bit sample in MSB */
+    dsdSample_l =  samplesOut[0];
+    dsdSample_r =  samplesOut[1];
+    dsdSample_r = bitrev(byterev(dsdSample_r));
+    dsdSample_l = bitrev(byterev(dsdSample_l));
+
+    asm volatile("out res[%0], %1"::"r"(p_dsd_dac[0]),"r"(dsdSample_l));
+    asm volatile("out res[%0], %1"::"r"(p_dsd_dac[1]),"r"(dsdSample_r));
+}
+
+/* This function performs the DOP loop and collects 16b of DSD per loop 
+   and outputs a 32b word into the port buffer every other cycle. */
+static inline void DoDsdDop(int &everyOther, unsigned samplesOut[], unsigned &dsdSample_l, unsigned &dsdSample_r, unsigned divide)
+{
+    if(!everyOther)
+    {
+        dsdSample_l = ((samplesOut[0] & 0xffff00) << 8);
+        dsdSample_r = ((samplesOut[1] & 0xffff00) << 8);
+        everyOther = 1;
+    }
+    else 
+    {
+        everyOther = 0;
+        dsdSample_l =  dsdSample_l | ((samplesOut[0] & 0xffff00) >> 8);
+        dsdSample_r =  dsdSample_r | ((samplesOut[1] & 0xffff00) >> 8);
+
+        asm volatile("out res[%0], %1"::"r"(p_dsd_dac[0]),"r"(bitrev(dsdSample_l)));
+        asm volatile("out res[%0], %1"::"r"(p_dsd_dac[1]),"r"(bitrev(dsdSample_r)));
+    }
+}
+
+/* When DSD is enabled and streaming is standard PCM, this function checks for a series of DoP markers in the upper byte.
+   If found it will exit deliver() with the command to restart in DoP mode.
+   When in DoP mode, this function will check for a single absence of the DoP marker and exit deliver() with the command
+   to restart in I2S mode. */
+static inline int DoDsdDopCheck(unsigned &dsdMode, int &dsdCount, unsigned curSamFreq, unsigned samplesOut[], unsigned &dsdMarker)
+{
+    /* Check for DSD - note we only move into DoP mode if valid DoP Freq */
+    /* Currently we only check on channel 0 - we get all 0's on channels without data */
+    if((dsdMode == DSD_MODE_OFF) && (curSamFreq > 96000))
+    {
+        if((DSD_MASK(samplesOut[0]) == dsdMarker) && (DSD_MASK(samplesOut[1]) == dsdMarker))
+        {
+            dsdCount++;
+            dsdMarker ^= DSD_MARKER_XOR;
+            if(dsdCount == DSD_EN_THRESH)
+            {
+                dsdMode = DSD_MODE_DOP;
+                dsdCount = 0;
+                dsdMarker = DSD_MARKER_2;
+                return 0;
+            }
+        }
+        else
+        {
+            dsdCount = 0;
+            dsdMarker = DSD_MARKER_2;
+        }
+    }
+    else if(dsdMode == DSD_MODE_DOP) 
+    {
+        /* If we are running in DOP mode, check if we need to come out */
+        if((DSD_MASK(samplesOut[0]) != DSD_MARKER_1) && (DSD_MASK(samplesOut[1]) != DSD_MARKER_1))
+        {
+            if((DSD_MASK(samplesOut[0]) != DSD_MARKER_2) && (DSD_MASK(samplesOut[1]) != DSD_MARKER_2))
+            {
+                dsdMode = DSD_MODE_OFF;
+                return 0;
+            }
+        }
+    }
+    return 1;
+}
+
+

lib_xua/src/core/audiohub/audiohub_initport.xc

@@ -0,0 +1,118 @@
+// Copyright (c) 2018, XMOS Ltd, All rights reserved
+#include "xua.h"
+
+#include "dsd_support.h"
+
+#if (DSD_CHANS_DAC != 0)
+extern buffered out port:32 p_dsd_dac[DSD_CHANS_DAC];
+extern buffered out port:32 p_dsd_clk;
+#endif
+
+extern unsigned dsdMode;
+
+#if !CODEC_MASTER
+void InitPorts_master(unsigned divide, buffered _XUA_CLK_DIR port:32 p_lrclk, 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 (DSD_CHANS_DAC > 0)
+    if(dsdMode == DSD_MODE_OFF)
+    {
+#endif
+
+#if (I2S_CHANS_ADC != 0 || I2S_CHANS_DAC != 0)
+
+        /* Clear I2S port buffers */
+        clearbuf(p_lrclk);
+
+#if (I2S_CHANS_DAC != 0)
+        for(int i = 0; i < I2S_WIRES_DAC; i++)
+        {
+            clearbuf(p_i2s_dac[i]);
+        }
+#endif
+
+#if (I2S_CHANS_ADC != 0)
+        for(int i = 0; i < I2S_WIRES_ADC; i++)
+        {
+            clearbuf(p_i2s_adc[i]);
+        }
+#endif
+
+#pragma xta endpoint "divide_1"
+        unsigned tmp;
+        p_lrclk <: 0 @ tmp;
+        tmp += 100;
+
+        /* Since BCLK is free-running, setup outputs/inputs at a known point in the future */
+#if (I2S_CHANS_DAC != 0)
+#pragma loop unroll
+        for(int i = 0; i < I2S_WIRES_DAC; i++)
+        {
+            p_i2s_dac[i] @ tmp <: 0;
+        }
+#endif
+
+        p_lrclk @ tmp <: 0x7FFFFFFF;
+
+#if (I2S_CHANS_ADC != 0)
+        for(int i = 0; i < I2S_WIRES_ADC; i++)
+        {
+            asm("setpt res[%0], %1"::"r"(p_i2s_adc[i]),"r"(tmp-1));
+        }
+#endif
+#endif /* (I2S_CHANS_ADC != 0 || I2S_CHANS_DAC != 0) */
+
+
+#if (DSD_CHANS_DAC > 0)
+    } /* if (!dsdMode) */
+    else
+    {
+        /* p_dsd_clk must start high */
+        p_dsd_clk <: 0x80000000;
+    }
+#endif
+}
+
+#else 
+
+void InitPorts_slave(unsigned divide, buffered _XUA_CLK_DIR port:32 p_lrclk, 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 (I2S_CHANS_ADC != 0 || I2S_CHANS_DAC != 0)
+    unsigned tmp;
+
+    /* Wait for LRCLK edge (in I2S LRCLK = 0 is left, TDM rising edge is start of frame) */
+    p_lrclk when pinseq(0) :> void;
+    p_lrclk when pinseq(1) :> void;
+    p_lrclk when pinseq(0) :> void;
+    p_lrclk when pinseq(1) :> void;
+#if I2S_MODE_TDM
+    p_lrclk when pinseq(0) :> void;
+    p_lrclk when pinseq(1) :> void @ tmp;
+#else
+    p_lrclk when pinseq(0) :> void @ tmp;
+#endif
+
+    tmp += (I2S_CHANS_PER_FRAME * 32) - 32 + 1 ;
+    /* E.g. 2 * 32 - 32 + 1 = 33 for stereo */
+    /* E.g. 8 * 32 - 32 + 1 = 225 for 8 chan TDM */
+
+#if (I2S_CHANS_DAC != 0)
+#pragma loop unroll
+    for(int i = 0; i < I2S_WIRES_DAC; i++)
+    {
+        p_i2s_dac[i] @ tmp <: 0;
+    }
+#endif
+
+#if (I2S_CHANS_ADC != 0)
+#pragma loop unroll
+    for(int i = 0; i < I2S_WIRES_ADC; i++)
+    {
+       asm("setpt res[%0], %1"::"r"(p_i2s_adc[i]),"r"(tmp-1));
+    }
+#endif
+
+    asm("setpt res[%0], %1"::"r"(p_lrclk),"r"(tmp-1));
+#endif /* (I2S_CHANS_ADC != 0 || I2S_CHANS_DAC != 0) */
+}
+#endif
+

lib_xua/src/core/buffer/decouple/decouple.xc

@@ -1,21 +1,24 @@
-// Copyright (c) 2011-2018, XMOS Ltd, All rights reserved
-#ifndef NO_USB
-#include <xs1.h>
+// Copyright (c) 2011-2020, XMOS Ltd, All rights reserved
 #include "xua.h"
+
+#if XUA_USB_EN
+#include <xs1.h>
 #include "xc_ptr.h"
 #include "interrupt.h"
 #include "xua_commands.h"
 #include "xud.h"
+#include "xua_usb_params_funcs.h"
 
 #ifdef NATIVE_DSD
 #include "usbaudio20.h"             /* Defines from the USB Audio 2.0 Specifications */
 #endif
 
-#ifdef HID_CONTROLS
+#if( 0 < HID_CONTROLS )
 #include "user_hid.h"
 #endif
 #define MAX(x,y) ((x)>(y) ? (x) : (y))
 
+
 /* TODO use SLOTSIZE to potentially save memory */
 /* Note we could improve on this, for one subslot is set to 4 */
 /* The *4 is conversion to bytes, note we're assuming a slotsize of 4 here whic is potentially as waste */
@@ -135,6 +138,7 @@ unsigned unpackData = 0;
 unsigned packState = 0;
 unsigned packData = 0;
 
+
 /* Default to something sensible but the following are setup at stream start (unless UAC1 only..) */
 #if (AUDIO_CLASS == 2)
 unsigned g_curSubSlot_Out = HS_STREAM_FORMAT_OUTPUT_1_SUBSLOT_BYTES;
@@ -144,7 +148,6 @@ unsigned g_curSubSlot_Out = FS_STREAM_FORMAT_OUTPUT_1_SUBSLOT_BYTES;
 unsigned g_curSubSlot_In  = FS_STREAM_FORMAT_INPUT_1_SUBSLOT_BYTES;
 #endif
 
-
 /* IN packet size. Init to something sensible, but expect to be re-set before stream start */
 #if (AUDIO_CLASS==2)
 int g_maxPacketSize = MAX_DEVICE_AUD_PACKET_SIZE_IN_HS;
@@ -157,6 +160,10 @@ int g_maxPacketSize = MAX_DEVICE_AUD_PACKET_SIZE_IN_FS;
 void handle_audio_request(chanend c_mix_out)
 {
     int space_left;
+#if(defined XUA_USB_DESCRIPTOR_OVERWRITE_RATE_RES)
+    g_curSubSlot_Out = get_usb_to_device_bit_res() >> 3;
+    g_curSubSlot_In = get_device_to_usb_bit_res() >> 3;
+#endif
 
     /* Input word that triggered interrupt and handshake back */
     unsigned underflowSample = inuint(c_mix_out);
@@ -1031,4 +1038,4 @@ void XUA_Buffer_Decouple(chanend c_mix_out
 #endif /* NUM_USB_CHAN_IN > 0 */
     }
 }
-#endif /* NO_USB */
+#endif /* XUA_USB_EN */

lib_xua/src/core/buffer/decouple/decouple_interrupt.c

@@ -1,5 +1,6 @@
 // Copyright (c) 2015-2018, XMOS Ltd, All rights reserved
-#ifndef NO_USB
+#include "xua.h"
+#if XUA_USB_EN
 #include "interrupt.h"
 
 register_interrupt_handler(handle_audio_request, 1, 200)

lib_xua/src/core/buffer/decouple/get_adc_counts.c

@@ -1,5 +1,6 @@
 // Copyright (c) 2011-2018, XMOS Ltd, All rights reserved
-#ifndef NO_USB
+#include "xua.h"
+#if XUA_USB_EN
 #include "xud.h"
 
 extern XUD_BusSpeed_t g_curUsbSpeed;
@@ -50,5 +51,5 @@ void GetADCCounts(unsigned samFreq, int *min, int *mid, int *max)
     }
 
 }
-#endif /* NO_USB */
+#endif /* XUA_USB_EN */