'Release: 3.2.0rc1'

Document moving and rename. Fixes for latest xdoc.

.github/CODEOWNERS

@@ -0,0 +1 @@
+*  @xross

.gitignore

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

CHANGELOG.rst

@@ -1,13 +1,202 @@
 lib_xua Change Log
 ==================
 
+3.2.0
+-----
+
+  * CHANGED:   Updated tests to use lib_locks (was legacy module_locks)
+  * CHANGED:   Exclude HID Report functions unless the HID feature is enabled
+  * CHANGED:   Explicit feedback EP enabled by default (see
+    UAC_FORCE_FEEDBACK_EP)
+  * FIXED:     Incorrect conditional compilation of HID report code
+  * FIXED:     Input/output descriptors written when input/output not enabled.
+    (Audio class 1.0 mode using XUA_USB_DESCRIPTOR_OVERWRITE_RATE_RES)
+
+  * Changes to dependencies:
+
+    - lib_dsp: 5.0.0 -> 6.2.1
+
+    - lib_locks: Added dependency 2.1.0
+
+    - lib_logging: 3.0.0 -> 3.1.1
+
+    - lib_mic_array: 4.0.0 -> 4.5.0
+
+    - lib_spdif: 4.0.0 -> 4.1.0
+
+    - lib_xassert: 4.0.0 -> 4.1.0
+
+    - lib_xud: 2.0.0 -> 2.1.0
+
+3.1.0
+-----
+
+  * CHANGED:   Removed logic from HID API functions allowing a Report ID of 0 to
+    be used as "all/any" Report
+
+3.0.0
+-----
+
+  * ADDED:     Support for HID Report IDs
+  * CHANGED:   Renamed the HID API file xua_hid_report_descriptor.h to
+    xua_hid_report.h
+  * REMOVED:   Support for HID Reports containing controls from mixed usage
+    pages
+
+2.1.1
+-----
+
+  * CHANGED:   Setting of HID report items
+
+2.1.0
+-----
+
+  * CHANGED:   Updated clock blocks to support lib_xud v2.0.0
+
+  * Changes to dependencies:
+
+    - lib_xud: 1.2.0 -> 2.0.0
+
+2.0.0
+-----
+
+  * ADDED:     Function to get a Report item description
+  * ADDED:     Support for multiple flash specs defined by DFU_FLASH_DEVICE
+  * ADDED:     Nullable c_aud_ctl chan-end optimisation for fixed rate devices
+  * CHANGED:   Check HID Usage Page when changing a Report item description
+  * CHANGED:   HID event ID from list to bit and byte location in HID Report
+  * CHANGED:   Interface to UserHIDRecordEvent()
+
+1.3.0
+-----
+
+  * ADDED:     Build default HID Report descriptor at boot-time
+  * ADDED:     Function to return length of HID Report
+  * CHANGED:   Move HID descriptors to ease maintenance
+  * CHANGED:   Move legacy tests to separate directory
+  * CHANGED:   Replace unused GPI-specific HID event names with generic ones
+  * CHANGED:   HID Report to return multiple bytes
+  * CHANGED:   NO_USB conditional compilation switch with XUA_USB_EN
+  * CHANGED:   Clock blocks used for BCLK and MCLK
+  * CHANGED:   Arguments no longer supported by XUD_Main
+  * REMOVED:   Support for XS1 based devices
+
+1.2.0
+-----
+
+  * ADDED:     Updates for xcore.ai/XS3 compatibility
+  * ADDED:     Makefile.Win32 for xmosdfu on Windows
+  * CHANGED:   Use XMOS Public Licence Version 1
+  * FIXED:     Bump default BCD device number to v1.2.0
+  * FIXED:     xmosdfu now fails with an error when given a directory (#119)
+  * FIXED:     Compilation errors related to HID code
+  * FIXED:     Runtime error when using mic array interface
+  * FIXED:     Automate HID Report Descriptor length in AC1 HID Descriptor
+
+1.1.1
+-----
+
+  * CHANGED:   Pin Python package versions
+  * FIXED:     Zero length input packets generated before enumeration causing
+    I2S timing pushout at startup
+
+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
+  * ADDED:     Guards to user_hid.h and xua_hid.h
+  * ADDED:     UAC1 HID support for AC Stop (End Call), Volume Increment and
+    Volume Decrement
+  * CHANGED:   UAC1 HID to report function keys f21 through f24 as specified by
+    customer
+  * CHANGED:   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
+  * FIXED:     Descriptors for XUA_ADAPTIVE incorrectly defined for IN endpoint
+
+  * Changes to dependencies:
+
+    - lib_spdif: 3.1.0 -> 4.0.0
+
+    - lib_xassert: 3.0.1 -> 4.0.0
+
+0.2.1
+-----
+
+  * FIXED:     Fix descriptors for XUA_ADAPTIVE
+
+  * Changes to dependencies:
+
+    - lib_logging: 2.1.1 -> 3.0.0
+
+    - lib_xud: 0.1.0 -> 0.2.0
+
+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
+  * CHANGED:   I2S hardware resources no longer used globally and must be passed
+    to XUA_AudioHub()
+  * CHANGED:   XUA_AudioHub() no longer pars S/PDIF transmitter task
+  * CHANGED:   Moved to lib_spdif (from module_spdif_tx & module_spdif_rx)
+  * CHANGED:   Define NUM_PDM_MICS renamed to XUA_NUM_PDM_MICS
+  * CHANGED:   Define NO_USB renamed to XUA_USB_EN
+  * CHANGED:   Build files updated to support new "xcommon" behaviour in xwaf.
+  * FIXED:     wChannelConfig in UAC1 descriptor set according to output channel
+    count
+  * FIXED:     Indexing of ADAT channel strings (#18059)
+  * FIXED:     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: Simple USB Audio Device using lib_xua
+  * CHANGED:   xmosdfu emits warning if empty image read via upload
+  * CHANGED:   Simplified mclk port sharing - no longer uses unsafe pointer
+  * FIXED:     Runtime exception issues when incorrect feedback calculated
+    (introduced in sc_usb_audio 6.13)
+  * FIXED:     Output sample counter reset on stream start. Caused playback
+    issues on some Linux based hosts
+
 0.1.1
 -----
 
-  * RESOLVED:   Configurations where I2S_CHANS_DAC and I2S_CHANS_ADC are both 0
-    now build
-  * RESOLVED:   Deadlock in mixer when MAX_MIX_COUNT > 0 for larger channel
-    counts
+  * FIXED:   Configurations where I2S_CHANS_DAC and I2S_CHANS_ADC are both 0 now
+    build
+  * FIXED:   Deadlock in mixer when MAX_MIX_COUNT > 0 for larger channel counts
 
   * Changes to dependencies:
 
@@ -18,31 +207,31 @@ lib_xua Change Log
 0.1.0
 -----
 
-  * ADDED:      FB_USE_REF_CLOCK to allow feedback generation from xCORE
-    internal reference
-  * ADDED:      Linux Makefile for xmosdfu host application
-  * ADDED:      Raspberry Pi Makefile for xmosdfu host application
-  * ADDED:      Documentation of PID argument to xmosdfu
-  * ADDED:      Optional build time microphone delay line (MIC_BUFFER_DEPTH)
-  * CHANGE:     Removal of audManage_if, users should define their own
-    interfaces as required
-  * CHANGE:     Vendor specific control interface in UAC1 descriptor now has a
+  * ADDED:     FB_USE_REF_CLOCK to allow feedback generation from xCORE internal
+    reference
+  * ADDED:     Linux Makefile for xmosdfu host application
+  * ADDED:     Raspberry Pi Makefile for xmosdfu host application
+  * ADDED:     Documentation of PID argument to xmosdfu
+  * ADDED:     Optional build time microphone delay line (MIC_BUFFER_DEPTH)
+  * CHANGED:   Removal of audManage_if, users should define their own interfaces
+    as required
+  * CHANGED:   Vendor specific control interface in UAC1 descriptor now has a
     string descriptor so it shows up with a descriptive name in Windows Device
     Manager
-  * CHANGE:     DFU_BCD_DEVICE removed (now uses BCD_DEVICE)
-  * CHANGE:     Renaming in descriptors.h to avoid clashes with application
-  * CHANGE:     Make device reboot function no-argument (was one channel end)
-  * RESOLVED:   FIR gain compensation for PDM mics set incorrectly for divide of
+  * CHANGED:   DFU_BCD_DEVICE removed (now uses BCD_DEVICE)
+  * CHANGED:   Renaming in descriptors.h to avoid clashes with application
+  * CHANGED:   Make device reboot function no-argument (was one channel end)
+  * FIXED:     FIR gain compensation for PDM mics set incorrectly for divide of
     8
-  * RESOLVED:   Incorrect xmosdfu DYLD path in test script code
-  * RESOLVED:   xmosdfu cannot find XMOS device on modern MacBook Pro (#17897)
-  * RESOLVED:   Issue when feedback is initially incorrect when two SOF's are
-    not yet received
-  * RESOLVED:   AUDIO_TILE and PDM_TILE may now share the same value/tile
-  * RESOLVED:   Cope with out of order interface numbers in xmosdfu
-  * RESOLVED:   DSD playback not functional on xCORE-200 (introduced in
+  * FIXED:     Incorrect xmosdfu DYLD path in test script code
+  * FIXED:   xmosdfu cannot find XMOS device on modern MacBook Pro (#17897)
+  * FIXED:   Issue when feedback is initially incorrect when two SOF's are not
+    yet received
+  * FIXED:   AUDIO_TILE and PDM_TILE may now share the same value/tile
+  * FIXED:   Cope with out of order interface numbers in xmosdfu
+  * FIXED:   DSD playback not functional on xCORE-200 (introduced in
     sc_usb_audio 6.14)
-  * RESOLVED:   Improvements made to clock sync code in TDM slave mode
+  * FIXED:   Improvements made to clock sync code in TDM slave mode
 
 
 Legacy release history
@@ -52,105 +241,105 @@ Legacy release history
 
 7.4.1
 -----
-    - RESOLVED:   Exception due to null chanend when using NO_USB
+    - FIXED:   Exception due to null chanend when using NO_USB
 
 7.4.0
 -----
-    - RESOLVED:   PID_DFU now based on AUDIO_CLASS. This potentially caused issues
+    - FIXED:   PID_DFU now based on AUDIO_CLASS. This potentially caused issues
       with UAC1 DFU
 
 
 7.3.0
 -----
-    - CHANGE:     Example OSX DFU host app updated to now take PID as runtime 
+    - CHANGED:    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
 
 7.2.0
 -----
     - ADDED:      DFU to UAC1 descriptors (guarded by DFU and FORCE_UAC1_DFU)
-    - RESOLVED:   Removed 'reinterpretation to type of larger alignment' warnings
-    - RESOLVED:   DFU flash code run on tile[0] even if XUD_TILE and AUDIO_IO_TILE are not 0
+    - FIXED:      Removed 'reinterpretation to type of larger alignment' warnings
+    - FIXED:      DFU flash code run on tile[0] even if XUD_TILE and AUDIO_IO_TILE are not 0
 
 7.1.0
 -----
     - ADDED:      UserBufferManagementInit() to reset any state required in UserBufferManagement()
     - ADDED:      I2S output up-sampling (enabled when AUD_TO_USB_RATIO is > 1)
     - ADDED:      PDM Mic decimator output rate can now be controlled independently (via AUD_TO_MICS_RATIO)
-    - CHANGE:     Rename I2S input down-sampling (enabled when AUD_TO_USB_RATIO is > 1, rather than via I2S_DOWNSAMPLE_FACTOR)
-    - RESOLVED:   Crosstalk between input channels when I2S input down-sampling is enabled
-    - RESOLVED:   Mic decimation data tables properly sized when mic sample-rate < USB audio sample-rate
+    - CHANGED:    Rename I2S input down-sampling (enabled when AUD_TO_USB_RATIO is > 1, rather than via I2S_DOWNSAMPLE_FACTOR)
+    - FIXED:      Crosstalk between input channels when I2S input down-sampling is enabled
+    - FIXED:      Mic decimation data tables properly sized when mic sample-rate < USB audio sample-rate
 
 7.0.1
 -----
-    - RESOLVED:   PDM microphone decimation issue at some sample rates caused by integration
+    - FIXED:      PDM microphone decimation issue at some sample rates caused by integration
 
 7.0.0
 ------
     - ADDED:      I2S down-sampling (I2S_DOWNSAMPLE_FACTOR)
     - ADDED:      I2S resynchronisation when in slave mode (CODEC_MASTER=1)
-    - CHANGE:     Various memory optimisations when MAX_FREQ = MIN_FREQ
-    - CHANGE:     Memory optimisations in audio buffering
-    - CHANGE:     Various memory optimisations in UAC1 mode
-    - CHANGE:     user_pdm_process() API change
-    - CHANGE:     PDM Mic decimator table now related to MIN_FREQ (memory optimisation)
-    - RESOLVED:   Audio request interrupt handler properly eliminated
+    - CHANGED:    Various memory optimisations when MAX_FREQ = MIN_FREQ
+    - CHANGED:    Memory optimisations in audio buffering
+    - CHANGED:    Various memory optimisations in UAC1 mode
+    - CHANGED:    user_pdm_process() API change
+    - CHANGED:    PDM Mic decimator table now related to MIN_FREQ (memory optimisation)
+    - FIXED:      Audio request interrupt handler properly eliminated
 
 6.30.0
 ------
-    - RESOLVED:   Number of PDM microphone channels configured now based on NUM_PDM_MICS define
-                  (previously hard-coded)
-    - RESOLVED:   PDM microphone clock divide now based MCLK defines (previously hard-coded)
-    - CHANGE:     Second microphone decimation core only run if NUM_PDM_MICS > 4
+    - FIXED:   Number of PDM microphone channels configured now based on NUM_PDM_MICS define
+    (previously hard-coded)
+    - FIXED:   PDM microphone clock divide now based MCLK defines (previously hard-coded)
+    - CHANGED: Second microphone decimation core only run if NUM_PDM_MICS > 4
 
 6.20.0
 ------
-    - RESOLVED:   Intra-frame sample delays of 1/2 samples on input streaming in TDM mode
-    - RESOLVED:   Build issue with NUM_USB_CHAN_OUT set to 0 and MIXER enabled
-    - RESOLVED:   SPDIF_TX_INDEX not defined build warning only emitted when SPDIF_TX defined
-    - RESOLVED:   Failure to enter DFU mode when configured without input volume control
+    - FIXED:   Intra-frame sample delays of 1/2 samples on input streaming in TDM mode
+    - FIXED:   Build issue with NUM_USB_CHAN_OUT set to 0 and MIXER enabled
+    - FIXED:   SPDIF_TX_INDEX not defined build warning only emitted when SPDIF_TX defined
+    - FIXED:   Failure to enter DFU mode when configured without input volume control
 
 6.19.0
 ------
-    - RESOLVED:   SPDIF_TX_INDEX not defined build warning only emitted when SPDIF_TX defined
-    - RESOLVED:   Failure to enter DFU mode when configured without input volume control
+    - FIXED:   SPDIF_TX_INDEX not defined build warning only emitted when SPDIF_TX defined
+    - FIXED:   Failure to enter DFU mode when configured without input volume control
 
 6.18.1
 ------
-    - ADDED:      Vendor Specific control interface added to UAC1 descriptors to allow control of
-                  XVSM params from Windows (via lib_usb)
+    - ADDED:   Vendor Specific control interface added to UAC1 descriptors to allow control of
+                XVSM params from Windows (via lib_usb)
 
 6.18.0
 ------
-    - ADDED:      Call to VendorRequests() and VendorRequests_Init() to Endpoint 0
-    - ADDED:      VENDOR_REQUESTS_PARAMS define to allow for custom parameters to VendorRequest calls
-    - RESOLVED:   FIR gain compensation set appropriately in lib_mic_array usage
-    - CHANGE:     i_dsp interface renamed i_audManage
+    - ADDED:   Call to VendorRequests() and VendorRequests_Init() to Endpoint 0
+    - ADDED:   VENDOR_REQUESTS_PARAMS define to allow for custom parameters to VendorRequest calls
+    - FIXED:   FIR gain compensation set appropriately in lib_mic_array usage
+    - CHANGED: i_dsp interface renamed i_audManage
 
 6.16.0
 ------
     - ADDED:      Call to UserBufferManagement()
     - ADDED:      PDM_MIC_INDEX in devicedefines.h and usage
-    - CHANGE:     pdm_buffer() task now combinable
-    - CHANGE:     Audio I/O task now takes i_dsp interface as a parameter
-    - CHANGE:     Removed built-in support for A/U series internal ADC
-    - CHANGE:     User PDM Microphone processing now uses an interface (previously function call)
+    - CHANGED:    pdm_buffer() task now combinable
+    - CHANGED:    Audio I/O task now takes i_dsp interface as a parameter
+    - CHANGED:    Removed built-in support for A/U series internal ADC
+    - CHANGED:    User PDM Microphone processing now uses an interface (previously function call)
 
 6.15.2
 ------
-    - RESOLVED:   interrupt.h (used in audio buffering) now compatible with xCORE-200 ABI
+    - FIXED:   interrupt.h (used in audio buffering) now compatible with xCORE-200 ABI
 
 6.15.1
 ------
-    - RESOLVED:   DAC data mis-alignment issue in TDM/I2S slave mode
-    - CHANGE:     Updates to support API changes in lib_mic_array version 2.0
+    - FIXED:   DAC data mis-alignment issue in TDM/I2S slave mode
+    - CHANGED:    Updates to support API changes in lib_mic_array version 2.0
 
 6.15.0
 ------
 
-    - RESOLVED:   UAC 1.0 descriptors now support multi-channel volume control (previously were
+    - FIXED:   UAC 1.0 descriptors now support multi-channel volume control (previously were
                   hard-coded as stereo)
-    - CHANGE:     Removed 32kHz sample-rate support when PDM microphones enabled (lib_mic_array
+    - CHANGED:    Removed 32kHz sample-rate support when PDM microphones enabled (lib_mic_array
                   currently does not support non-integer decimation factors)
 
 6.14.0
@@ -164,75 +353,75 @@ Legacy release history
                   list and UAC 1.0 descriptors
     - ADDED:      Support for the use and integration of PDM microphones (including PDM to PCM
                   conversion) via lib_mic_array
-    - RESOLVED:   MIDI data not accepted after "sleep" in OSX 10.11 (El Capitan) - related to sc_xud
+    - FIXED:   MIDI data not accepted after "sleep" in OSX 10.11 (El Capitan) - related to sc_xud
                   issue #17092
-    - CHANGE:     Asynchronous feedback system re-implemented to allow for the first two ADDED
+    - CHANGED:    Asynchronous feedback system re-implemented to allow for the first two ADDED
                   changelog items
-    - CHANGE:     Hardware divider used to generate bit-clock from master clock (xCORE-200 only).
+    - CHANGED:    Hardware divider used to generate bit-clock from master clock (xCORE-200 only).
                   Allows easy support for greater number of master-clock to sample-rate ratios.
-    - CHANGE:     module_queue no longer uses any assert module/lib
+    - CHANGED:    module_queue no longer uses any assert module/lib
 
 6.13.0
 ------
     - ADDED:      Device now uses implicit feedback when input stream is available (previously explicit
                   feedback pipe always used). This saves chanend/EP resources and means less processing
                   burden for the host. Previous behaviour available by enabling UAC_FORCE_FEEDBACK_EP
-    - RESOLVED:   Exception when SPDIF_TX and ADAT_TX both enabled due to clock-block being configured
+    - FIXED:   Exception when SPDIF_TX and ADAT_TX both enabled due to clock-block being configured
                   after already started. Caused by SPDIF_TX define check typo
-    - RESOLVED:   DFU flag address changed to properly conform to memory address range allocated to
+    - FIXED:   DFU flag address changed to properly conform to memory address range allocated to
                   apps by tools
-    - RESOLVED:   Build failure when DFU disabled
-    - RESOLVED:   Build issue when I2S_CHANS_ADC/DAC set to 0 and CODEC_MASTER enabled
-    - RESOLVED:   Typo in MCLK_441 checking for MIN_FREQ define
-    - CHANGE:     Mixer and non-mixer channel comms scheme (decouple <-> audio path) now identical
-    - CHANGE:     Input stream buffering modified such that during overflow older samples are removed
+    - FIXED:   Build failure when DFU disabled
+    - FIXED:   Build issue when I2S_CHANS_ADC/DAC set to 0 and CODEC_MASTER enabled
+    - FIXED:   Typo in MCLK_441 checking for MIN_FREQ define
+    - CHANGED:    Mixer and non-mixer channel comms scheme (decouple <-> audio path) now identical
+    - CHANGED:    Input stream buffering modified such that during overflow older samples are removed
                   rather than ignoring most recent samples. Removes any chance of stale input packets
                   being sent to host
-    - CHANGE:     module_queue (in sc_usb_audio) now uses lib_xassert rather than module_xassert
+    - CHANGED:    module_queue (in sc_usb_audio) now uses lib_xassert rather than module_xassert
 
 6.12.6
 ------
-    - RESOLVED:   Build error when DFU is disabled
-    - RESOLVED:   Build error when I2S_CHANS_ADC or I2S_CHANS_DAC set to 0 and CODEC_MASTER enabled
+    - FIXED:   Build error when DFU is disabled
+    - FIXED:   Build error when I2S_CHANS_ADC or I2S_CHANS_DAC set to 0 and CODEC_MASTER enabled
 
 6.12.5
 ------
-    - RESOLVED:   Stream issue when NUM_USB_CHAN_IN < I2S_CHANS_ADC
+    - FIXED:   Stream issue when NUM_USB_CHAN_IN < I2S_CHANS_ADC
 
 6.12.4
 ------
-    - RESOLVED:   DFU fail when DSD enabled and USB library not running on tile[0]
+    - FIXED:   DFU fail when DSD enabled and USB library not running on tile[0]
 
 6.12.3
 ------
-    - RESOLVED:   Method for storing persistent state over a DFU reboot modified to improve resilience
+    - FIXED:   Method for storing persistent state over a DFU reboot modified to improve resilience
                   against code-base and tools changes
 
 6.12.2
 ------
-    - RESOLVED:   Reboot code (used for DFU) failure in tools versions > 14.0.2 (xCORE-200 only)
-    - RESOLVED:   Run-time exception in mixer when MAX_MIX_COUNT > 0 (xCORE-200 only)
-    - RESOLVED:   MAX_MIX_COUNT checked properly for mix strings in string table
-    - CHANGE:     DFU code re-written to use an XC interface. The flash-part may now be connected
+    - FIXED:   Reboot code (used for DFU) failure in tools versions > 14.0.2 (xCORE-200 only)
+    - FIXED:   Run-time exception in mixer when MAX_MIX_COUNT > 0 (xCORE-200 only)
+    - FIXED:   MAX_MIX_COUNT checked properly for mix strings in string table
+    - CHANGED:    DFU code re-written to use an XC interface. The flash-part may now be connected
                   to a separate tile to the tile running USB code
-    - CHANGE:     DFU code can now use quad-SPI flash
-    - CHANGE:     Example xmos_dfu application now uses a list of PIDs to allow adding PIDs easier.
+    - CHANGED:    DFU code can now use quad-SPI flash
+    - CHANGED:    Example xmos_dfu application now uses a list of PIDs to allow adding PIDs easier.
                   --listdevices command also added.
-    - CHANGE:     I2S_CHANS_PER_FRAME and I2S_WIRES_xxx defines tidied
+    - CHANGED:    I2S_CHANS_PER_FRAME and I2S_WIRES_xxx defines tidied
 
 6.12.1
 ------
-    - RESOLVED:   Fixes to TDM input timing/sample-alignment when BCLK=MCLK
-    - RESOLVED:   Various minor fixes to allow ADAT_RX to run on xCORE 200 MC AUDIO hardware
-    - CHANGE:     Moved from old SPDIF define to SPDIF_TX
+    - FIXED:   Fixes to TDM input timing/sample-alignment when BCLK=MCLK
+    - FIXED:   Various minor fixes to allow ADAT_RX to run on xCORE 200 MC AUDIO hardware
+    - CHANGED:    Moved from old SPDIF define to SPDIF_TX
 
 6.12.0
 ------
     - ADDED:      Checks for XUD_200_SERIES define where required
-    - RESOLVED:   Run-time exception due to decouple interrupt not entering correct issue mode
+    - FIXED:   Run-time exception due to decouple interrupt not entering correct issue mode
                   (affects XCORE-200 only)
-    - CHANGE:     SPDIF Tx Core may now reside on a different tile from I2S
-    - CHANGE:     I2C ports now in structure to match new module_i2c_singleport/shared API.
+    - CHANGED:    SPDIF Tx Core may now reside on a different tile from I2S
+    - CHANGED:    I2C ports now in structure to match new module_i2c_singleport/shared API.
 
   * Changes to dependencies:
 
@@ -242,48 +431,48 @@ Legacy release history
 
 6.11.3
 ------
-    - RESOLVED:  (Major) Streaming issue when mixer not enabled (introduced in 6.11.2)
+    - FIXED:  (Major) Streaming issue when mixer not enabled (introduced in 6.11.2)
 
 6.11.2
 ------
-    - RESOLVED:   (Major) Enumeration issue when MAX_MIX_COUNT > 0 only. Introduced in mixer
+    - FIXED:   (Major) Enumeration issue when MAX_MIX_COUNT > 0 only. Introduced in mixer
                   optimisations in 6.11.0. Only affects designs using mixer functionality.
-    - RESOLVED:   (Normal) Audio buffering request system modified such that the mixer output is
+    - FIXED:   (Normal) Audio buffering request system modified such that the mixer output is
                   not silent when in underflow case (i.e. host output stream not active) This issue was
                   introduced with the addition of DSD functionality and only affects designs using
                   mixer functionality.
-    - RESOLVED:   (Minor) Potential build issue due to duplicate labels in inline asm in
+    - FIXED:   (Minor) Potential build issue due to duplicate labels in inline asm in
                   set_interrupt_handler macro
-    - RESOLVED:   (Minor) BCD_DEVICE define in devicedefines.h now guarded by ifndef (caused issues
+    - FIXED:   (Minor) BCD_DEVICE define in devicedefines.h now guarded by ifndef (caused issues
                   with DFU test build configs.
-    - RESOLVED:   (Minor) String descriptor for Clock Selector unit incorrectly reported
-    - RESOLVED:   (Minor) BCD_DEVICE in devicedefines.h now guarded by #ifndef (Caused issues with
+    - FIXED:   (Minor) String descriptor for Clock Selector unit incorrectly reported
+    - FIXED:   (Minor) BCD_DEVICE in devicedefines.h now guarded by #ifndef (Caused issues with
                   default DFU test build configs.
-    - CHANGE:     HID report descriptor defines added to shared user_hid.h
-    - CHANGE:     Now uses module_adat_rx from sc_adat (local module_usb_audio_adat removed)
+    - CHANGED:    HID report descriptor defines added to shared user_hid.h
+    - CHANGED:    Now uses module_adat_rx from sc_adat (local module_usb_audio_adat removed)
 
 6.11.1
 ------
     - ADDED:      ADAT transmit functionality, including SMUX. See ADAT_TX and ADAT_TX_INDEX.
-    - RESOLVED:   (Normal) Build issue with CODEC_MASTER (xCore is I2S slave) enabled
-    - RESOLVED:   (Minor) Channel ordering issue in when TDM and CODEC_MASTER mode enabled
-    - RESOLVED:   (Normal) DFU fails when SPDIF_RX enabled due to clock block being shared between SPDIF
+    - FIXED:   (Normal) Build issue with CODEC_MASTER (xCore is I2S slave) enabled
+    - FIXED:   (Minor) Channel ordering issue in when TDM and CODEC_MASTER mode enabled
+    - FIXED:   (Normal) DFU fails when SPDIF_RX enabled due to clock block being shared between SPDIF
                   core and FlashLib
 
 6.11.0
 ------
     - ADDED:      Basic TDM I2S functionality added. See I2S_CHANS_PER_FRAME and I2S_MODE_TDM
-    - CHANGE:     Various optimisations in 'mixer' core to improve performance for higher
+    - CHANGED:    Various optimisations in 'mixer' core to improve performance for higher
                   channel counts including the use of XC unsafe pointers instead of inline ASM
-    - CHANGE:     Mixer mapping disabled when MAX_MIX_COUNT is 0 since this is wasted processing.
-    - CHANGE:     Descriptor changes to allow for channel input/output channel count up to 32
+    - CHANGED:    Mixer mapping disabled when MAX_MIX_COUNT is 0 since this is wasted processing.
+    - CHANGED:    Descriptor changes to allow for channel input/output channel count up to 32
                   (previous limit was 18)
 
 6.10.0
 ------
-    - CHANGE:     Endpoint management for iAP EA Native Transport now merged into buffer() core.
+    - CHANGED:    Endpoint management for iAP EA Native Transport now merged into buffer() core.
                   Previously was separate core (as added in 6.8.0).
-    - CHANGE:     Minor optimisation to I2S port code for inputs from ADC
+    - CHANGED:    Minor optimisation to I2S port code for inputs from ADC
 
 6.9.0
 -----
@@ -291,35 +480,35 @@ Legacy release history
                   supported (4 channels at 96kHz).
     - ADDED:      Explicit build warnings if sample rate/depth & channel combination exceeds
                   available USB bus bandwidth.
-    - RESOLVED:   (Major) Reinstated ADAT input functionality, including descriptors and clock
+    - FIXED:   (Major) Reinstated ADAT input functionality, including descriptors and clock
                   generation/control and stream configuration defines/tables.
-    - RESOLVED:   (Major) S/PDIF/ADAT sample transfer code in audio() (from ClockGen()) moved to
+    - FIXED:   (Major) S/PDIF/ADAT sample transfer code in audio() (from ClockGen()) moved to
                   aid timing.
-    - CHANGE:     Modifying mix map now only affects specified mix, previous was applied to all
+    - CHANGED:    Modifying mix map now only affects specified mix, previous was applied to all
                   mixes. CS_XU_MIXSEL control selector now takes values 0 to MAX_MIX_COUNT + 1
                   (with 0 affecting all mixes).
-    - CHANGE:     Channel c_dig_rx is no longer nullable, assists with timing due to removal of
+    - CHANGED:    Channel c_dig_rx is no longer nullable, assists with timing due to removal of
                   null checks inserted by compiler.
-    - CHANGE:     ADAT SMUX selection now based on device sample frequency rather than selected
+    - CHANGED:    ADAT SMUX selection now based on device sample frequency rather than selected
                   stream format - Endpoint 0 now configures clockgen() on a sample-rate change
                   rather than stream start.
 
 6.8.0
 -----
     - ADDED:      Evaluation support for iAP EA Native Transport endpoints
-    - RESOLVED:   (Minor) Reverted change in 6.5.1 release where sample rate listing in Audio Class
+    - FIXED:   (Minor) Reverted change in 6.5.1 release where sample rate listing in Audio Class
                   1.0 descriptors was trimmed (previously 4 rates were always reported). This change
                   appears to highlight a Windows (only) enumeration issue with the Input & Output
                   configs
-    - RESOLVED:   (Major) Mixer functionality re-instated, including descriptors and various required
+    - FIXED:   (Major) Mixer functionality re-instated, including descriptors and various required
                   updates compatibility with 13 tools
-    - RESOLVED:   (Major) Endpoint 0 was requesting an out of bounds channel whilst requesting level data
-    - RESOLVED:   (Major) Fast mix code not operates correctly in 13 tools, assembler inserting long jmp
+    - FIXED:   (Major) Endpoint 0 was requesting an out of bounds channel whilst requesting level data
+    - FIXED:   (Major) Fast mix code not operates correctly in 13 tools, assembler inserting long jmp
                   instructions
-    - RESOLVED:   (Minor) LED level meter code now compatible with 13 tools (shared mem access)
-    - RESOLVED    (Minor) Ordering of level data from the device now matches channel ordering into
+    - FIXED:   (Minor) LED level meter code now compatible with 13 tools (shared mem access)
+    - FIXED:    (Minor) Ordering of level data from the device now matches channel ordering into
                   mixer (previously the device input data and the stream from host were swapped)
-    - CHANGE:     Level meter buffer naming now resemble functionality
+    - CHANGED:    Level meter buffer naming now resemble functionality
 
 
 Legacy release history

Jenkinsfile

@@ -0,0 +1,198 @@
+@Library('xmos_jenkins_shared_library@v0.18.0') _
+
+getApproval()
+
+pipeline {
+  agent none
+  environment {
+    REPO = 'lib_xua'
+    VIEW = getViewName(REPO)
+  }
+  options {
+    skipDefaultCheckout()
+  }
+  stages {
+    stage('Basic tests') {
+      agent {
+        label 'x86_64 && linux'
+      }
+      stages {
+        stage('Get view') {
+          steps {
+            xcorePrepareSandbox("${VIEW}", "${REPO}")
+          }
+        }
+        stage('Library checks') {
+          steps {
+            xcoreLibraryChecks("${REPO}")
+          }
+        }
+        stage('XS2 Tests') {
+          failFast true
+          parallel {
+            stage('Legacy tests') {
+              steps {
+                runXmostest("${REPO}", 'legacy_tests')
+              }
+            }
+            stage('Unit tests') {
+              steps {
+                dir("${REPO}") {
+                  dir('tests') {
+                    dir('xua_unit_tests') {
+                      withVenv {
+                        runWaf('.', "configure clean build --target=xcore200")
+//                        runWaf('.', "configure clean build --target=xcoreai")
+//                        stash name: 'xua_unit_tests', includes: 'bin/*xcoreai.xe, '
+                        viewEnv() {
+                          runPython("TARGET=XCORE200 pytest -s")
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+//        stage('xcore.ai Verification') {
+//          agent {
+//            label 'xcore.ai-explorer'
+//          }
+//          options {
+//            skipDefaultCheckout()
+//          }
+//          stages{
+//            stage('Get View') {
+//              steps {
+//                xcorePrepareSandbox("${VIEW}", "${REPO}")
+//              }
+//            }
+//            stage('Unit tests') {
+//              steps {
+//                dir("${REPO}") {
+//                  dir('tests') {
+//                    dir('xua_unit_tests') {
+//                      withVenv {
+//                        unstash 'xua_unit_tests'
+//                        viewEnv() {
+//                          runPython("TARGET=XCOREAI pytest -s")
+//                        }
+//                      }
+//                    }
+//                  }
+//                }
+//              }
+//            }
+//          } // stages
+//          post {
+//            cleanup {
+//              cleanWs()
+//            }
+//          }
+//        }
+        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&&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&&macOS'
+          }
+          steps {
+            xcorePrepareSandbox("${VIEW}", "${REPO}")
+            dir("${REPO}/${REPO}/host/xmosdfu") {
+              sh 'make -f Makefile.OSX64'
+            }
+          }
+          post {
+            cleanup {
+              xcoreCleanSandbox()
+            }
+          }
+        }
+        stage('Build Pi host app') {
+          agent {
+            label 'pi'
+          }
+          steps {
+            dir("${REPO}") {
+              checkout scm
+              dir("${REPO}/host/xmosdfu") {
+                sh 'make -f Makefile.Pi'
+              }
+            }
+          }
+          post {
+            cleanup {
+              xcoreCleanSandbox()
+            }
+          }
+        }
+        stage('Build Windows host app') {
+          agent {
+            label 'x86_64&&windows'
+          }
+          steps {
+            dir("${REPO}") {
+              checkout scm
+              dir("${REPO}/host/xmosdfu") {
+                runVS('nmake /f Makefile.Win32')
+              }
+            }
+          }
+          post {
+            cleanup {
+              xcoreCleanSandbox()
+            }
+          }
+        }
+      }
+    }
+    stage('Update') {
+      agent {
+        label 'x86_64 && linux'
+      }
+      steps {
+        updateViewfiles()
+      }
+      post {
+        cleanup {
+          xcoreCleanSandbox()
+        }
+      }
+    }
+  }
+}

LICENSE.rst

@@ -0,0 +1,84 @@
+*******************************
+XMOS PUBLIC LICENCE: Version 1
+*******************************
+
+Subject to the conditions and limitations below, permission is hereby granted by XMOS LIMITED (“XMOS”), free of charge, to any person or entity obtaining a copy of the XMOS Software.
+
+**1. Definitions**
+
+**“Applicable Patent Rights”** means: (a) where XMOS is the grantor of the rights, (i) claims of patents that are now or in future owned by or assigned to XMOS and (ii) that cover subject matter contained in the Software, but only to the extent it is necessary to use, reproduce or distribute the Software without infringement; and (b) where you are the grantor of the rights, (i) claims of patents that are now or in future owned by or assigned to you and (ii) that cover the subject matter contained in your Derivatives, taken alone or in combination with the Software.
+
+**“Compiled Code”** means any compiled, binary, machine readable or executable version of the Source Code.
+
+**“Contributor”** means any person or entity that creates or contributes to the creation of Derivatives.
+
+**“Derivatives”** means any addition to, deletion from and/or change to the substance, structure of the Software, any previous Derivatives, the combination of the Derivatives and the Software and/or any respective portions thereof.
+
+**“Source Code”** means the human readable code that is suitable for making modifications but excluding any Compiled Code.
+
+**“Software”** means the software and associated documentation files which XMOS makes available and which contain a notice identifying the software as original XMOS software and referring to the software being subject to the terms of this XMOS Public Licence.
+
+This Licence refers to XMOS Software and does not relate to any XMOS hardware or devices which are protected by intellectual property rights (including patent and trade marks) which may be sold to you under a separate agreement.
+
+
+**2. Licence**
+
+**Permitted Uses, Conditions and Restrictions.**  Subject to the conditions below, XMOS grants you a worldwide, royalty free, non-exclusive licence, to the extent of any Patent Rights to do the following:
+
+2.1 **Unmodified Software.** You may use, copy, display, publish, distribute and make available unmodified copies of the Software:
+
+2.1.1 for personal or academic, non-commercial purposes; or
+
+2.1.2 for commercial purposes provided the Software is at all times used on a device designed, licensed or developed by XMOS and, provided that in each instance (2.1.1 and 2.1.2):
+
+(a) you must retain and reproduce in all copies of the Software the copyright and proprietary notices and disclaimers of XMOS as they appear in the Software, and keep intact all notices and disclaimers in the Software files that refer to this Licence; and
+
+(b) you must include a copy of this Licence with every copy of the Software and documentation you publish, distribute and make available and you may not offer or impose any terms on such Software that alter or restrict this Licence or the intent of such Licence, except as permitted below (Additional Terms).
+
+The licence above does not include any Compiled Code which XMOS may make available under a separate support and licence agreement.
+
+2.2 **Derivatives.** You may create and modify Derivatives and use, copy, display, publish, distribute and make available Derivatives:
+
+2.2.1 for personal or academic, non-commercial purposes; or
+
+2.2.2 for commercial purposes, provided the Derivatives are at all times used on a device designed, licensed or developed by XMOS and, provided that in each instance (2.2.1 and 2.2.2):
+
+(a) you must comply with the terms of clause 2.1 with respect to the Derivatives;
+
+(b) you must copy (to the extent it doesn’t already exist) the notice below in each file of the Derivatives, and ensure all the modified files carry prominent notices stating that you have changed the files and the date of any change; and
+
+(c) if you sublicence, distribute or otherwise make the Software and/or the Derivatives available for commercial purposes, you must provide that the Software and Derivatives are at all times used on a device designed, licensed or developed by XMOS.
+
+Without limitation to these terms and clause 3 below, the Source Code and Compiled Code to your Derivatives may at your discretion (but without obligation) be released, copied, displayed, published, distributed and made available; and if you elect to do so, it must be under the terms of this Licence including the terms of the licence at clauses 2.2.1, 2.2.2 and clause 3 below.
+
+2.3 **Distribution of Executable Versions.**  If you distribute or make available Derivatives, you must include a prominent notice in the code itself as well as in all related documentation, stating that the Source Code of the Software from which the Derivatives are based is available under the terms of this Licence, with information on how and where to obtain such Source Code.
+
+**3. Your Grant of Rights.**  In consideration and as a condition to this Licence, you grant to any person or entity receiving or distributing any Derivatives, a non-exclusive, royalty free, perpetual, irrevocable license under your Applicable Patent Rights and all other intellectual property rights owned or controlled by you, to use, copy, display, publish, distribute and make available your Derivatives of the same scope and extent as XMOS’s licence under clause 2.2 above.
+
+**4. Combined Products.**  You may create a combined product by combining Software, Derivatives and other code not covered by this Licence as a single application or product. In such instance, you must comply with the requirements of this Licence for any portion of the Software and/or Derivatives.
+
+**5. Additional Terms.**  You may choose to offer, and to charge a fee for, warranty, support, indemnity or liability obligations and/or other rights consistent with the term of this Licence (“Additional Terms”) to any legitimate recipients of the Software and/or Derivatives.  The terms on which you provide such Additional Terms are on your sole responsibility and you shall indemnify, defend and hold XMOS harmless against any claims asserted against XMOS.
+
+**6. New Versions.**  XMOS may publish revised and/or new versions of this Licence from time to time to accommodate changes to the Licence terms, new versions, updates and bug fixes of the Software.  Each version will be given a distinguishing version number.  Once Software has been published under a particular version of this Licence, you may continue to use it under the terms of that version.  You may also choose to use the latest version of the Software under any subsequent version published by XMOS.  Only XMOS shall have the right to modify these terms.
+
+**7. IPR and Ownership**
+Any rights, including all intellectual property rights and all trademarks not expressly granted herein are reserved in full by the authors or copyright holders. Any requests for additional permissions by XMOS including any rights to use XMOS trademarks, should be made (without obligation) to XMOS at **support@xmos.com**
+
+Nothing herein shall limit any rights that XMOS is otherwise entitled to under the doctrines of patent exhaustion, implied license, or legal estoppel.  Neither the name of the authors, the copyright holders or any contributors may be used to endorse or promote any Derivatives from this Software without specific written permission.  Any attempt to deal with the Software which does not comply with this Licence shall be void and shall automatically terminate any rights granted under this licence (including any licence of any intellectual property rights granted herein).
+Subject to the licences granted under this Licence any Contributor retains all rights, title and interest in and to any Derivatives made by Contributor subject to the underlying rights of XMOS in the Software.  XMOS shall retain all rights, title and interest in the Software and any Derivatives made by XMOS (“XMOS Derivatives”).  XMOS Derivatives will not automatically be subject to this Licence and XMOS shall be entitled to licence such rights on any terms (without obligation) as it sees fit.
+
+**8. Termination**
+
+8.1 This Licence will automatically terminate immediately, without notice to you, if:
+
+(a) you fail to comply with the terms of this Licence; and/or
+
+(b) you directly or indirectly commence any action for patent or intellectual property right infringement against XMOS, or any parent, group, affiliate or subsidiary of XMOS; provided XMOS did not first commence an action or patent infringement against you in that instance; and/or
+
+(c) the terms of this Licence are held by any court of competent jurisdiction to be unenforceable in whole or in part.
+
+**9. Critical Applications.**  Unless XMOS has agreed in writing with you an agreement specifically governing use of the Goods in military, aerospace, automotive or medically related functions (collectively and individually hereinafter referred to as "Special Use"), any permitted use of the Software excludes Special Use. Notwithstanding any agreement between XMOS and you for Special Use, Special Use shall be at your own risk, and you shall fully indemnify XMOS against any damages, losses, costs and claims (direct and indirect) arising out of any Special Use.
+
+**10. NO WARRANTY OR SUPPORT.**  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL XMOS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, WARRANTY, CIVIL TORT (INCLUDING NEGLIGENCE), PRODUCTS LIABILITY OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE INCLUDING GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES EVEN IF SUCH PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES AND NOT WITHSTANDING THE FAILURE OF ESSENTIAL PURPOSE.  IN SOME JURISDICTIONS PARTIES ARE UNABLE TO LIMIT LIABILTY IN THIS WAY, IF THIS APPLIES TO YOUR JURISDICTION THIS LIABILITY CLAUSE ABOVE MAY NOT APPLY.  NOTWITHSTANDING THE ABOVE, IN NO EVENT SHALL XMOS’s TOTAL LIABILITY TO YOU FOR ALL DAMAGES, LOSS OR OTHERWISE EXCEED $50.
+
+**11. Governing Law and Jurisdiction.**  This Licence constitutes the entire agreement between the parties with respect to the subject matter hereof. The Licence shall be governed by the laws of England and the conflict of laws and UN Convention on Contracts for the International Sale of Goods, shall not apply.

LICENSE.txt

@@ -1,135 +0,0 @@
-Software Release License Agreement
-
-Copyright (c) 2011-2018, 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 lib_xua software

README.rst

@@ -1,18 +1,84 @@
 lib_xua
 =======
 
-USB Audio Shared Components. For use in the XMOS USB Audio Refererence Designs.
+:Latest release: 3.2.0rc1
 
 
-Required software (dependencies)
-................................
+:Scope: General Use
 
-  * lib_logging
-  * lib_xud
+Summary
+-------
 
-Checking dependent libs
+USB Audio Shared Components for use in the XMOS USB Audio Refererence Designs.
+
+This library enables the development of USB Audio devices on the XMOS xCORE architecture.
+
+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
+
+- Synchronisation to external digital streams i.e. S/PDIF or ADAT
+
+- I2S slave & master modes
+
+- TDM slave & master modes
+
+- 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.
 
 Software version and dependencies
 .................................
 
-.. libdeps::
+The CHANGELOG contains information about the current and previous versions.
+For a list of direct dependencies, look for DEPENDENT_MODULES in lib_xua/module_build_info.
+
+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
+
+Required software (dependencies)
+================================
+
+  * lib_locks (git@github.com:xmos/lib_locks.git)
+  * lib_logging (git@github.com:xmos/lib_logging)
+  * lib_mic_array (git@github.com:xmos/lib_mic_array.git)
+  * lib_xassert (git@github.com:xmos/lib_xassert)
+  * lib_dsp (git@github.com:xmos/lib_dsp)
+  * lib_spdif (git@github.com:xmos/lib_spdif)
+  * lib_xud (git@github.com:xmos/lib_xud)
+

doc/dfu/rst/building_xmos_dfu.rst

@@ -0,0 +1,56 @@
+.. _usb_audiosec_building_xmos_dfu:
+
+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.
+
+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.OSX64 all``
+
+This Makefile contains the following:
+
+.. 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
+
+Windows
+-------
+
+To build on Windows, you must first install Visual Studio 2019 Build Tools with
+C++ support. `This is available from Microsoft's website. <https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019>`_
+
+To build, open a Developer Command Prompt via the start menu and navigate to the
+xmosdfu folder.  The command to build is as follows:
+
+  ``nmake /f Makefile.Win32``
+
+This Makefile contains the following:
+
+.. literalinclude:: Makefile.Win32

doc/dfu/rst/dfu.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>

doc/dfu/rst/xdoc.conf

@@ -0,0 +1,3 @@
+XMOSNEWSTYLE=2
+SOURCE_INCLUDE_DIRS=../../../lib_xua/host/xmosdfu
+SPHINX_MASTER_DOC=dfu

doc/dfu/rst/xmos_dfu.rst

@@ -4,6 +4,9 @@ Using the DFU loader - macOS (via the XMOS DFU loader)
 The XMOS DFU loader is provided as source as part of the XMOS USB Audio software
 framework, see :ref:`usb_audiosec_building_xmos_dfu`.
 
+NOTE: Windows requires the installation of libusbK drivers on the DFU endpoint.
+We recommend using `Zadig <https://zadig.akeo.ie/>`_.
+
 Set up the image loader
 -----------------------
 
@@ -18,7 +21,7 @@ Download new firmware
 
 To program the new firmware run the command:
 
-   ``./xmosdfu XMOS_L2_AUDIO2_PID --download new_firmware.bin``
+   ``./bin/xmosdfu XMOS_L2_AUDIO2_PID --download new_firmware.bin``
 
 Replace ``XMOS_L2_AUDIO2_PID`` with product ID of your target device. Invoke
 ``xmosdfu`` with no arguments to get a list of all supported product IDs.
@@ -35,7 +38,7 @@ present.
 
 Run the command:
 
-  ``./xmosdfu XMOS_L2_AUDIO2_PID --upload currentfirmware.bin``
+  ``./bin/xmosdfu XMOS_L2_AUDIO2_PID --upload currentfirmware.bin``
 
 The file ``currentfirmware.bin`` contains the latest upgrade image. This file is
 an exact copy of the data from the flash and can be downloaded to the device
@@ -47,6 +50,6 @@ Reverting firmware to factory image
 To revert the device back to its factory (i.e XFLASH) installed state from the
 new firmware, run the command:
 
-  ``./xmosdfu XMOS_L2_AUDIO2_PID --revertfactory``
+  ``./bin/xmosdfu XMOS_L2_AUDIO2_PID --revertfactory``
 
 The device will now be running, and only contain the factory firmware.

doc_dfu/LICENSE.txt

@@ -1,135 +0,0 @@
-Software Release License Agreement
-
-Copyright (c) 2017-2018, 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 lib_xua software

doc_dfu/Makefile

@@ -1 +0,0 @@
-SOURCE_INCLUDE_DIRS=../host/xmosdfu

doc_dfu/building_xmos_dfu.rst

@@ -1,18 +0,0 @@
-.. _usb_audiosec_building_xmos_dfu:
-
-Building the XMOS DFU loader - macOS
-====================================
-
-The XMOS DFU loader is provided as source as part of the USB Audio
-framework, located in sc_usb_audio/module_dfu/host/xmos_dfu_osx.
-
-The loader is compiled using libusb, the code for the loader is contained in the
-file ``xmosdfu.cpp``
-
-To build the loader a Makefile is provided, which can be run as follows:
-
-  ``make -f Makefile.OSX all``
-
-This Makefile contains the following:
-
-.. literalinclude:: Makefile.OSX

examples/AN00246_xua_example/LICENSE.rst

@@ -0,0 +1,84 @@
+*******************************
+XMOS PUBLIC LICENCE: Version 1
+*******************************
+
+Subject to the conditions and limitations below, permission is hereby granted by XMOS LIMITED (“XMOS”), free of charge, to any person or entity obtaining a copy of the XMOS Software.
+
+**1. Definitions**
+
+**“Applicable Patent Rights”** means: (a) where XMOS is the grantor of the rights, (i) claims of patents that are now or in future owned by or assigned to XMOS and (ii) that cover subject matter contained in the Software, but only to the extent it is necessary to use, reproduce or distribute the Software without infringement; and (b) where you are the grantor of the rights, (i) claims of patents that are now or in future owned by or assigned to you and (ii) that cover the subject matter contained in your Derivatives, taken alone or in combination with the Software.
+
+**“Compiled Code”** means any compiled, binary, machine readable or executable version of the Source Code.
+
+**“Contributor”** means any person or entity that creates or contributes to the creation of Derivatives.
+
+**“Derivatives”** means any addition to, deletion from and/or change to the substance, structure of the Software, any previous Derivatives, the combination of the Derivatives and the Software and/or any respective portions thereof.
+
+**“Source Code”** means the human readable code that is suitable for making modifications but excluding any Compiled Code.
+
+**“Software”** means the software and associated documentation files which XMOS makes available and which contain a notice identifying the software as original XMOS software and referring to the software being subject to the terms of this XMOS Public Licence.
+
+This Licence refers to XMOS Software and does not relate to any XMOS hardware or devices which are protected by intellectual property rights (including patent and trade marks) which may be sold to you under a separate agreement.
+
+
+**2. Licence**
+
+**Permitted Uses, Conditions and Restrictions.**  Subject to the conditions below, XMOS grants you a worldwide, royalty free, non-exclusive licence, to the extent of any Patent Rights to do the following:
+
+2.1 **Unmodified Software.** You may use, copy, display, publish, distribute and make available unmodified copies of the Software:
+
+2.1.1 for personal or academic, non-commercial purposes; or
+
+2.1.2 for commercial purposes provided the Software is at all times used on a device designed, licensed or developed by XMOS and, provided that in each instance (2.1.1 and 2.1.2):
+
+(a) you must retain and reproduce in all copies of the Software the copyright and proprietary notices and disclaimers of XMOS as they appear in the Software, and keep intact all notices and disclaimers in the Software files that refer to this Licence; and
+
+(b) you must include a copy of this Licence with every copy of the Software and documentation you publish, distribute and make available and you may not offer or impose any terms on such Software that alter or restrict this Licence or the intent of such Licence, except as permitted below (Additional Terms).
+
+The licence above does not include any Compiled Code which XMOS may make available under a separate support and licence agreement.
+
+2.2 **Derivatives.** You may create and modify Derivatives and use, copy, display, publish, distribute and make available Derivatives:
+
+2.2.1 for personal or academic, non-commercial purposes; or
+
+2.2.2 for commercial purposes, provided the Derivatives are at all times used on a device designed, licensed or developed by XMOS and, provided that in each instance (2.2.1 and 2.2.2):
+
+(a) you must comply with the terms of clause 2.1 with respect to the Derivatives;
+
+(b) you must copy (to the extent it doesn’t already exist) the notice below in each file of the Derivatives, and ensure all the modified files carry prominent notices stating that you have changed the files and the date of any change; and
+
+(c) if you sublicence, distribute or otherwise make the Software and/or the Derivatives available for commercial purposes, you must provide that the Software and Derivatives are at all times used on a device designed, licensed or developed by XMOS.
+
+Without limitation to these terms and clause 3 below, the Source Code and Compiled Code to your Derivatives may at your discretion (but without obligation) be released, copied, displayed, published, distributed and made available; and if you elect to do so, it must be under the terms of this Licence including the terms of the licence at clauses 2.2.1, 2.2.2 and clause 3 below.
+
+2.3 **Distribution of Executable Versions.**  If you distribute or make available Derivatives, you must include a prominent notice in the code itself as well as in all related documentation, stating that the Source Code of the Software from which the Derivatives are based is available under the terms of this Licence, with information on how and where to obtain such Source Code.
+
+**3. Your Grant of Rights.**  In consideration and as a condition to this Licence, you grant to any person or entity receiving or distributing any Derivatives, a non-exclusive, royalty free, perpetual, irrevocable license under your Applicable Patent Rights and all other intellectual property rights owned or controlled by you, to use, copy, display, publish, distribute and make available your Derivatives of the same scope and extent as XMOS’s licence under clause 2.2 above.
+
+**4. Combined Products.**  You may create a combined product by combining Software, Derivatives and other code not covered by this Licence as a single application or product. In such instance, you must comply with the requirements of this Licence for any portion of the Software and/or Derivatives.
+
+**5. Additional Terms.**  You may choose to offer, and to charge a fee for, warranty, support, indemnity or liability obligations and/or other rights consistent with the term of this Licence (“Additional Terms”) to any legitimate recipients of the Software and/or Derivatives.  The terms on which you provide such Additional Terms are on your sole responsibility and you shall indemnify, defend and hold XMOS harmless against any claims asserted against XMOS.
+
+**6. New Versions.**  XMOS may publish revised and/or new versions of this Licence from time to time to accommodate changes to the Licence terms, new versions, updates and bug fixes of the Software.  Each version will be given a distinguishing version number.  Once Software has been published under a particular version of this Licence, you may continue to use it under the terms of that version.  You may also choose to use the latest version of the Software under any subsequent version published by XMOS.  Only XMOS shall have the right to modify these terms.
+
+**7. IPR and Ownership**
+Any rights, including all intellectual property rights and all trademarks not expressly granted herein are reserved in full by the authors or copyright holders. Any requests for additional permissions by XMOS including any rights to use XMOS trademarks, should be made (without obligation) to XMOS at **support@xmos.com**
+
+Nothing herein shall limit any rights that XMOS is otherwise entitled to under the doctrines of patent exhaustion, implied license, or legal estoppel.  Neither the name of the authors, the copyright holders or any contributors may be used to endorse or promote any Derivatives from this Software without specific written permission.  Any attempt to deal with the Software which does not comply with this Licence shall be void and shall automatically terminate any rights granted under this licence (including any licence of any intellectual property rights granted herein).
+Subject to the licences granted under this Licence any Contributor retains all rights, title and interest in and to any Derivatives made by Contributor subject to the underlying rights of XMOS in the Software.  XMOS shall retain all rights, title and interest in the Software and any Derivatives made by XMOS (“XMOS Derivatives”).  XMOS Derivatives will not automatically be subject to this Licence and XMOS shall be entitled to licence such rights on any terms (without obligation) as it sees fit.
+
+**8. Termination**
+
+8.1 This Licence will automatically terminate immediately, without notice to you, if:
+
+(a) you fail to comply with the terms of this Licence; and/or
+
+(b) you directly or indirectly commence any action for patent or intellectual property right infringement against XMOS, or any parent, group, affiliate or subsidiary of XMOS; provided XMOS did not first commence an action or patent infringement against you in that instance; and/or
+
+(c) the terms of this Licence are held by any court of competent jurisdiction to be unenforceable in whole or in part.
+
+**9. Critical Applications.**  Unless XMOS has agreed in writing with you an agreement specifically governing use of the Goods in military, aerospace, automotive or medically related functions (collectively and individually hereinafter referred to as "Special Use"), any permitted use of the Software excludes Special Use. Notwithstanding any agreement between XMOS and you for Special Use, Special Use shall be at your own risk, and you shall fully indemnify XMOS against any damages, losses, costs and claims (direct and indirect) arising out of any Special Use.
+
+**10. NO WARRANTY OR SUPPORT.**  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL XMOS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, WARRANTY, CIVIL TORT (INCLUDING NEGLIGENCE), PRODUCTS LIABILITY OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE INCLUDING GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES EVEN IF SUCH PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES AND NOT WITHSTANDING THE FAILURE OF ESSENTIAL PURPOSE.  IN SOME JURISDICTIONS PARTIES ARE UNABLE TO LIMIT LIABILTY IN THIS WAY, IF THIS APPLIES TO YOUR JURISDICTION THIS LIABILITY CLAUSE ABOVE MAY NOT APPLY.  NOTWITHSTANDING THE ABOVE, IN NO EVENT SHALL XMOS’s TOTAL LIABILITY TO YOU FOR ALL DAMAGES, LOSS OR OTHERWISE EXCEED $50.
+
+**11. Governing Law and Jurisdiction.**  This Licence constitutes the entire agreement between the parties with respect to the subject matter hereof. The Licence shall be governed by the laws of England and the conflict of laws and UN Convention on Contracts for the International Sale of Goods, shall not apply.

examples/AN00246_xua_example/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 -save-temps \
+			  -g -Wno-unused-function -Wno-timing -DXUD_SERIES_SUPPORT=XUD_X200_SERIES \
+			  -DXUD_CORE_CLOCK=600 -DUSB_TILE=tile[1] -fxscope -DUAC_FORCE_FEEDBACK_EP=0
+			  
+# 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 lib_i2c
+
+#=============================================================================
+# 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/AN00246_xua_example/README.rst

@@ -0,0 +1,32 @@
+
+Simple USB Audio Device using lib_xua
+=====================================
+
+Summary
+-------
+
+Software dependencies
+.....................
+
+For a list of direct dependencies, look for USED_MODULES in the Makefile.
+
+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/AN00246_xua_example/doc/rst/AN00246_xua_example.rst

@@ -0,0 +1,249 @@
+.. include:: ../../README.rst
+
+|newpage|
+
+Overview
+--------
+
+Introduction
+............
+
+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.
+
+
+The Makefile
+------------
+
+To start using ``lib_xua``, you need to add ``lib_xua`` to your Makefile::
+
+  USED_MODULES = .. lib_xua ...
+
+This demo also uses the XMOS USB Device library (``lib_xud``) for low-level USB connectivity.
+The Makefile also includes::
+
+  USED_MODULES = .. lib_xud ..
+
+``lib_xud`` library requires some flags for correct operation. Firstly the 
+tile on which ``lib_xud`` will be execute, 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 that defines 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 library functions are defined in ``xua.h``. This header must
+be included in your code to use the library. 
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: include "xua.h"
+   :end-on: include "xud_device.h"
+
+Allocating hardware resources
+.............................
+
+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)
+    - 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::
+
+    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: 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_usb
+
+Again, for the same reasoning as the master-clock ports, two master-clock clock-blocks are required
+- one on each tile.
+
+
+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()``).
+
+For a simple application the following endpoints are required:
+
+    - ``Control`` enpoint 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
+
+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_aud_ctl
+
+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 (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|
+
+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/AN00246_xua_example/doc/rst/xdoc.conf

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

examples/AN00246_xua_example/src/app_xua_simple.xc

@@ -1,20 +1,21 @@
-// Copyright (c) 2017-2018, XMOS Ltd, All rights reserved
+// Copyright 2017-2022 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 
 /* 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 
+ * It uses the main blocks from the lib_xua
  *
  * - 2 in/ 2 out I2S only
  * - No DFU
- * - I2S only 
+ * - I2S only
  *
  */
 
 #include <xs1.h>
 #include <platform.h>
 
-#include "xud_device.h"
 #include "xua.h"
+#include "xud_device.h"
 
 /* Port declarations. Note, the defines come from the xn file */
 buffered out port:32 p_i2s_dac[]    = {PORT_I2S_DAC0};   /* I2S Data-line(s) */
@@ -22,21 +23,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_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_bclk                = on tile[0]: XS1_CLKBLK_4;   /* Bit clock */
 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 */
@@ -52,39 +49,40 @@ 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 communcating 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
     {
-        /* Low level USB device layer core */ 
+        /* Low level USB device layer core */
         on tile[1]: XUD_Main(c_ep_out, 2, c_ep_in, 2,
-                      c_sof, epTypeTableOut, epTypeTableIn, 
-                      /* TODO rm me! */
-                      null, null, -1 , 
-                      XUD_SPEED_HS, XUD_PWR_BUS);
-        
+                      c_sof, epTypeTableOut, epTypeTableIn,
+                      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]: XUA_Buffer(c_ep_out[1], c_ep_in[1], c_sof, c_aud_ctl, p_for_mclk_count, c_aud);
+        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);
 
-        /* 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/cs4384.h

@@ -1,4 +1,5 @@
-// Copyright (c) 2017-2018, XMOS Ltd, All rights reserved
+// Copyright 2017-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 #ifndef CS4384_H_
 #define CS4384_H_
 

examples/AN00246_xua_example/src/cs5368.h

@@ -1,4 +1,5 @@
-// Copyright (c) 2017-2018, XMOS Ltd, All rights reserved
+// Copyright 2017-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 #ifndef _CS5368_H_
 #define _CS5368_H_
 

examples/AN00246_xua_example/src/hid_report_descriptor.h

@@ -0,0 +1,168 @@
+// Copyright 2021-2022 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
+#ifndef __hid_report_descriptor_h__
+#define __hid_report_descriptor_h__
+
+#include "xua_hid_report.h"
+
+#if 0
+/* Existing static report descriptor kept for reference */
+unsigned char hidReportDescriptor[] =
+{
+    0x05, 0x0c,     /* Usage Page (Consumer Device) */
+    0x09, 0x01,     /* Usage (Consumer Control) */
+    0xa1, 0x01,     /* Collection (Application) */
+    0x15, 0x00,     /* Logical Minimum (0) */
+    0x25, 0x01,     /* Logical Maximum (1) */
+    0x09, 0xb0,     /* Usage (Play) */
+    0x09, 0xb5,     /* Usage (Scan Next Track) */
+    0x09, 0xb6,     /* Usage (Scan Previous Track) */
+    0x09, 0xe9,     /* Usage (Volume Up) */
+    0x09, 0xea,     /* Usage (Volume Down) */
+    0x09, 0xe2,     /* Usage (Mute) */
+    0x75, 0x01,     /* Report Size (1) */
+    0x95, 0x06,     /* Report Count (6) */
+    0x81, 0x02,     /* Input (Data, Var, Abs) */
+    0x95, 0x02,     /* Report Count (2) */
+    0x81, 0x01,     /* Input (Cnst, Ary, Abs) */
+    0xc0            /* End collection */
+};
+#endif
+
+/*
+ * Define non-configurable items in the HID Report descriptor.
+ */
+static const USB_HID_Short_Item_t hidCollectionApplication  = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_MAIN, HID_REPORT_ITEM_TAG_COLLECTION),
+    .data = { 0x01, 0x00 } };
+static const USB_HID_Short_Item_t hidCollectionEnd          = {
+    .header = HID_REPORT_SET_HEADER(0, HID_REPORT_ITEM_TYPE_MAIN, HID_REPORT_ITEM_TAG_END_COLLECTION),
+    .data = { 0x00, 0x00 } };
+
+static const USB_HID_Short_Item_t hidInputConstArray        = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_MAIN, HID_REPORT_ITEM_TAG_INPUT),
+    .data = { 0x01, 0x00 } };
+static const USB_HID_Short_Item_t hidInputDataVar           = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_MAIN, HID_REPORT_ITEM_TAG_INPUT),
+    .data = { 0x02, 0x00 } };
+
+static const USB_HID_Short_Item_t hidLogicalMaximum0        = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_LOGICAL_MAXIMUM),
+    .data = { 0x00, 0x00 } };
+static const USB_HID_Short_Item_t hidLogicalMaximum1        = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_LOGICAL_MAXIMUM),
+    .data = { 0x01, 0x00 } };
+static const USB_HID_Short_Item_t hidLogicalMinimum0        = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_LOGICAL_MINIMUM),
+    .data = { 0x00, 0x00 } };
+
+static const USB_HID_Short_Item_t hidReportCount2           = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_REPORT_COUNT),
+    .data = { 0x02, 0x00 } };
+static const USB_HID_Short_Item_t hidReportCount6           = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_REPORT_COUNT),
+    .data = { 0x06, 0x00 } };
+static const USB_HID_Short_Item_t hidReportSize1            = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_REPORT_SIZE),
+    .data = { 0x01, 0x00 } };
+
+static const USB_HID_Short_Item_t hidUsageConsumerControl   = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+    .data = { 0x01, 0x00 } };
+
+/*
+ * Define the HID Report Descriptor Item, Usage Page, Report ID and length for each HID Report
+ * For internal purposes, a report element with ID of 0 must be included if report IDs are not being used.
+ */
+static const USB_HID_Report_Element_t hidReportPageConsumer = {
+    .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_USAGE_PAGE),
+    .item.data = { USB_HID_USAGE_PAGE_ID_CONSUMER, 0x00 },
+    .location = HID_REPORT_SET_LOC( 0, 2, 0, 0 )
+};
+
+/*
+ * Define configurable items in the HID Report descriptor.
+ */
+static USB_HID_Report_Element_t hidUsageByte0Bit5   = {
+     .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+     .item.data = { 0xE2, 0x00 },
+     .location = HID_REPORT_SET_LOC(0, 0, 0, 5)
+}; // Mute
+static USB_HID_Report_Element_t hidUsageByte0Bit4   = {
+     .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+     .item.data = { 0xEA, 0x00 },
+     .location = HID_REPORT_SET_LOC(0, 0, 0, 4)
+}; // Vol-
+static USB_HID_Report_Element_t hidUsageByte0Bit3   = {
+     .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+     .item.data = { 0xE9, 0x00 },
+     .location = HID_REPORT_SET_LOC(0, 0, 0, 3)
+}; // Vol+
+static USB_HID_Report_Element_t hidUsageByte0Bit2   = {
+     .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+     .item.data = { 0xB6, 0x00 },
+     .location = HID_REPORT_SET_LOC(0, 0, 0, 2)
+}; // Scan Prev
+static USB_HID_Report_Element_t hidUsageByte0Bit1   = {
+     .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+     .item.data = { 0xB5, 0x00 },
+     .location = HID_REPORT_SET_LOC(0, 0, 0, 1)
+}; // Scan Next
+static USB_HID_Report_Element_t hidUsageByte0Bit0   = {
+     .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+     .item.data = { 0xB0, 0x00 },
+     .location = HID_REPORT_SET_LOC(0, 0, 0, 0)
+}; // Play
+
+/*
+ * List the configurable elements in the HID Report descriptor.
+ */
+static USB_HID_Report_Element_t* const hidConfigurableElements[] = {
+    &hidUsageByte0Bit0,
+    &hidUsageByte0Bit1,
+    &hidUsageByte0Bit2,
+    &hidUsageByte0Bit3,
+    &hidUsageByte0Bit4,
+    &hidUsageByte0Bit5
+};
+
+/*
+ * List HID Reports, one per Report ID. This should be a usage page item with the relevant
+ * If not using report IDs - still have one with report ID 0
+ */
+static const USB_HID_Report_Element_t* const hidReports[] = {
+    &hidReportPageConsumer
+};
+
+/*
+ * List all items in the HID Report descriptor.
+ */
+static const USB_HID_Short_Item_t* const hidReportDescriptorItems[] = {
+    &(hidReportPageConsumer.item),
+    &hidUsageConsumerControl,
+    &hidCollectionApplication,
+        &hidLogicalMinimum0,
+        &hidLogicalMaximum1,
+        &(hidUsageByte0Bit0.item),
+        &(hidUsageByte0Bit1.item),
+        &(hidUsageByte0Bit2.item),
+        &(hidUsageByte0Bit3.item),
+        &(hidUsageByte0Bit4.item),
+        &(hidUsageByte0Bit5.item),
+        &hidReportSize1,
+        &hidReportCount6,
+        &hidInputDataVar,
+        &hidLogicalMaximum0,
+        &hidReportCount2,
+        &hidInputConstArray,
+    &hidCollectionEnd
+};
+
+/*
+ * Define the number of HID Reports
+ * Due to XC not supporting designated initializers, this constant has a hard-coded value.
+ * It must equal ( sizeof hidReports / sizeof ( USB_HID_Report_Element_t* ))
+ */
+#define HID_REPORT_COUNT ( 1 )
+
+#endif // __hid_report_descriptor_h__

examples/AN00246_xua_example/src/hwsupport.xc

@@ -1,16 +1,17 @@
-// Copyright (c) 2016-2018, XMOS Ltd, All rights reserved
+// Copyright 2016-2022 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 
 #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 +23,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)
@@ -50,7 +50,7 @@ void AudioHwConfig(unsigned samFreq, unsigned mClk, unsigned dsdMode,
     delay_microseconds(20000);
 
 	/* Take ADC out of reset */
-	gpioVal |= P_GPIO_ADC_RST_N;        
+	gpioVal |= P_GPIO_ADC_RST_N;
 	p_gpio <: gpioVal;
 
 	/* Configure ADC for I2S slave mode via I2C */
@@ -58,7 +58,7 @@ void AudioHwConfig(unsigned samFreq, unsigned mClk, unsigned dsdMode,
 	dif = 0x01;   	/* I2S */
 	mode = 0x03;    /* Slave mode all speeds */
 
-	/* Reg 0x01: (GCTL) Global Mode Control Register 
+	/* Reg 0x01: (GCTL) Global Mode Control Register
 	* Bit[7]: CP-EN: Manages control-port mode
 	* Bit[6]: CLKMODE: Setting puts part in 384x mode
 	* Bit[5:4]: MDIV[1:0]: Set to 01 for /2
@@ -67,6 +67,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
@@ -91,7 +92,7 @@ void AudioHwConfig(unsigned samFreq, unsigned mClk, unsigned dsdMode,
 	 */
 	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 +121,8 @@ void AudioHwConfig(unsigned samFreq, unsigned mClk, unsigned dsdMode,
 	 */
 	DAC_REGWRITE(CS4384_MODE_CTRL, 0b10000000);
 
+    /* Kill the i2c task */
+    i2c.shutdown();
     return;
 }
 
@@ -128,8 +131,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 --> 
@@ -74,7 +75,7 @@
     </Link>
   </Links>
   <ExternalDevices>
-    <Device NodeId="0" Tile="0" Class="SQIFlash" Name="bootFlash" Type="S25FL116K">
+    <Device NodeId="0" Tile="0" Class="SQIFlash" Name="bootFlash" Type="S25FL116K" PageSize="256" SectorSize="4096" NumPages="8192">
       <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"/>

examples/AN00246_xua_example/src/xua_conf.h

@@ -0,0 +1,27 @@
+// Copyright 2017-2022 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
+
+#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 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/AN00246_xua_example/src/xud_conf.h

@@ -1,4 +1,5 @@
-// Copyright (c) 2017-2018, XMOS Ltd, All rights reserved
+// Copyright 2017-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 
 #include "xua_conf.h"
 

examples/AN00247_xua_example_spdif_tx/LICENSE.rst

@@ -0,0 +1,84 @@
+*******************************
+XMOS PUBLIC LICENCE: Version 1
+*******************************
+
+Subject to the conditions and limitations below, permission is hereby granted by XMOS LIMITED (“XMOS”), free of charge, to any person or entity obtaining a copy of the XMOS Software.
+
+**1. Definitions**
+
+**“Applicable Patent Rights”** means: (a) where XMOS is the grantor of the rights, (i) claims of patents that are now or in future owned by or assigned to XMOS and (ii) that cover subject matter contained in the Software, but only to the extent it is necessary to use, reproduce or distribute the Software without infringement; and (b) where you are the grantor of the rights, (i) claims of patents that are now or in future owned by or assigned to you and (ii) that cover the subject matter contained in your Derivatives, taken alone or in combination with the Software.
+
+**“Compiled Code”** means any compiled, binary, machine readable or executable version of the Source Code.
+
+**“Contributor”** means any person or entity that creates or contributes to the creation of Derivatives.
+
+**“Derivatives”** means any addition to, deletion from and/or change to the substance, structure of the Software, any previous Derivatives, the combination of the Derivatives and the Software and/or any respective portions thereof.
+
+**“Source Code”** means the human readable code that is suitable for making modifications but excluding any Compiled Code.
+
+**“Software”** means the software and associated documentation files which XMOS makes available and which contain a notice identifying the software as original XMOS software and referring to the software being subject to the terms of this XMOS Public Licence.
+
+This Licence refers to XMOS Software and does not relate to any XMOS hardware or devices which are protected by intellectual property rights (including patent and trade marks) which may be sold to you under a separate agreement.
+
+
+**2. Licence**
+
+**Permitted Uses, Conditions and Restrictions.**  Subject to the conditions below, XMOS grants you a worldwide, royalty free, non-exclusive licence, to the extent of any Patent Rights to do the following:
+
+2.1 **Unmodified Software.** You may use, copy, display, publish, distribute and make available unmodified copies of the Software:
+
+2.1.1 for personal or academic, non-commercial purposes; or
+
+2.1.2 for commercial purposes provided the Software is at all times used on a device designed, licensed or developed by XMOS and, provided that in each instance (2.1.1 and 2.1.2):
+
+(a) you must retain and reproduce in all copies of the Software the copyright and proprietary notices and disclaimers of XMOS as they appear in the Software, and keep intact all notices and disclaimers in the Software files that refer to this Licence; and
+
+(b) you must include a copy of this Licence with every copy of the Software and documentation you publish, distribute and make available and you may not offer or impose any terms on such Software that alter or restrict this Licence or the intent of such Licence, except as permitted below (Additional Terms).
+
+The licence above does not include any Compiled Code which XMOS may make available under a separate support and licence agreement.
+
+2.2 **Derivatives.** You may create and modify Derivatives and use, copy, display, publish, distribute and make available Derivatives:
+
+2.2.1 for personal or academic, non-commercial purposes; or
+
+2.2.2 for commercial purposes, provided the Derivatives are at all times used on a device designed, licensed or developed by XMOS and, provided that in each instance (2.2.1 and 2.2.2):
+
+(a) you must comply with the terms of clause 2.1 with respect to the Derivatives;
+
+(b) you must copy (to the extent it doesn’t already exist) the notice below in each file of the Derivatives, and ensure all the modified files carry prominent notices stating that you have changed the files and the date of any change; and
+
+(c) if you sublicence, distribute or otherwise make the Software and/or the Derivatives available for commercial purposes, you must provide that the Software and Derivatives are at all times used on a device designed, licensed or developed by XMOS.
+
+Without limitation to these terms and clause 3 below, the Source Code and Compiled Code to your Derivatives may at your discretion (but without obligation) be released, copied, displayed, published, distributed and made available; and if you elect to do so, it must be under the terms of this Licence including the terms of the licence at clauses 2.2.1, 2.2.2 and clause 3 below.
+
+2.3 **Distribution of Executable Versions.**  If you distribute or make available Derivatives, you must include a prominent notice in the code itself as well as in all related documentation, stating that the Source Code of the Software from which the Derivatives are based is available under the terms of this Licence, with information on how and where to obtain such Source Code.
+
+**3. Your Grant of Rights.**  In consideration and as a condition to this Licence, you grant to any person or entity receiving or distributing any Derivatives, a non-exclusive, royalty free, perpetual, irrevocable license under your Applicable Patent Rights and all other intellectual property rights owned or controlled by you, to use, copy, display, publish, distribute and make available your Derivatives of the same scope and extent as XMOS’s licence under clause 2.2 above.
+
+**4. Combined Products.**  You may create a combined product by combining Software, Derivatives and other code not covered by this Licence as a single application or product. In such instance, you must comply with the requirements of this Licence for any portion of the Software and/or Derivatives.
+
+**5. Additional Terms.**  You may choose to offer, and to charge a fee for, warranty, support, indemnity or liability obligations and/or other rights consistent with the term of this Licence (“Additional Terms”) to any legitimate recipients of the Software and/or Derivatives.  The terms on which you provide such Additional Terms are on your sole responsibility and you shall indemnify, defend and hold XMOS harmless against any claims asserted against XMOS.
+
+**6. New Versions.**  XMOS may publish revised and/or new versions of this Licence from time to time to accommodate changes to the Licence terms, new versions, updates and bug fixes of the Software.  Each version will be given a distinguishing version number.  Once Software has been published under a particular version of this Licence, you may continue to use it under the terms of that version.  You may also choose to use the latest version of the Software under any subsequent version published by XMOS.  Only XMOS shall have the right to modify these terms.
+
+**7. IPR and Ownership**
+Any rights, including all intellectual property rights and all trademarks not expressly granted herein are reserved in full by the authors or copyright holders. Any requests for additional permissions by XMOS including any rights to use XMOS trademarks, should be made (without obligation) to XMOS at **support@xmos.com**
+
+Nothing herein shall limit any rights that XMOS is otherwise entitled to under the doctrines of patent exhaustion, implied license, or legal estoppel.  Neither the name of the authors, the copyright holders or any contributors may be used to endorse or promote any Derivatives from this Software without specific written permission.  Any attempt to deal with the Software which does not comply with this Licence shall be void and shall automatically terminate any rights granted under this licence (including any licence of any intellectual property rights granted herein).
+Subject to the licences granted under this Licence any Contributor retains all rights, title and interest in and to any Derivatives made by Contributor subject to the underlying rights of XMOS in the Software.  XMOS shall retain all rights, title and interest in the Software and any Derivatives made by XMOS (“XMOS Derivatives”).  XMOS Derivatives will not automatically be subject to this Licence and XMOS shall be entitled to licence such rights on any terms (without obligation) as it sees fit.
+
+**8. Termination**
+
+8.1 This Licence will automatically terminate immediately, without notice to you, if:
+
+(a) you fail to comply with the terms of this Licence; and/or
+
+(b) you directly or indirectly commence any action for patent or intellectual property right infringement against XMOS, or any parent, group, affiliate or subsidiary of XMOS; provided XMOS did not first commence an action or patent infringement against you in that instance; and/or
+
+(c) the terms of this Licence are held by any court of competent jurisdiction to be unenforceable in whole or in part.
+
+**9. Critical Applications.**  Unless XMOS has agreed in writing with you an agreement specifically governing use of the Goods in military, aerospace, automotive or medically related functions (collectively and individually hereinafter referred to as "Special Use"), any permitted use of the Software excludes Special Use. Notwithstanding any agreement between XMOS and you for Special Use, Special Use shall be at your own risk, and you shall fully indemnify XMOS against any damages, losses, costs and claims (direct and indirect) arising out of any Special Use.
+
+**10. NO WARRANTY OR SUPPORT.**  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL XMOS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, WARRANTY, CIVIL TORT (INCLUDING NEGLIGENCE), PRODUCTS LIABILITY OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE INCLUDING GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES EVEN IF SUCH PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES AND NOT WITHSTANDING THE FAILURE OF ESSENTIAL PURPOSE.  IN SOME JURISDICTIONS PARTIES ARE UNABLE TO LIMIT LIABILTY IN THIS WAY, IF THIS APPLIES TO YOUR JURISDICTION THIS LIABILITY CLAUSE ABOVE MAY NOT APPLY.  NOTWITHSTANDING THE ABOVE, IN NO EVENT SHALL XMOS’s TOTAL LIABILITY TO YOU FOR ALL DAMAGES, LOSS OR OTHERWISE EXCEED $50.
+
+**11. Governing Law and Jurisdiction.**  This Licence constitutes the entire agreement between the parties with respect to the subject matter hereof. The Licence shall be governed by the laws of England and the conflict of laws and UN Convention on Contracts for the International Sale of Goods, shall not apply.

examples/AN00247_xua_example_spdif_tx/Makefile

@@ -3,13 +3,15 @@ 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 
+XCC_FLAGS	= -fcomment-asm -Xmapper --map -Xmapper MAPFILE -O3 -report -save-temps \
+			  -g -Wno-unused-function -Wno-timing -DXUD_SERIES_SUPPORT=XUD_X200_SERIES \
+			  -DXUD_CORE_CLOCK=600 -DUSB_TILE=tile[1] -DSDA_HIGH=2 -DSCL_HIGH=1 -fxscope \
+			  -DUAC_FORCE_FEEDBACK_EP=0
 
 # 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_mic_array lib_logging lib_xua lib_device_control lib_xud module_i2c_shared module_i2c_single_port module_locks
-
+USED_MODULES = lib_xua lib_xud lib_spdif
 
 #=============================================================================
 # The following part of the Makefile includes the common build infrastructure

examples/AN00247_xua_example_spdif_tx/README.rst

@@ -0,0 +1,32 @@
+
+Using lib_xua with lib_spdif (transmit) 
+=======================================
+
+Summary
+-------
+
+Software dependencies
+.....................
+
+For a list of direct dependencies, look for USED_MODULES in the Makefile.
+
+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_xua_example_spdif_tx.rst

@@ -0,0 +1,278 @@
+.. include:: ../../README.rst
+
+|newpage|
+
+Overview
+--------
+
+Introduction
+............
+
+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 with 
+S/PDIF transmit functionality the xCORE-200 MC Audio board.
+
+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.
+
+
+The Makefile
+------------
+
+To start using ``lib_xua``, you need to add ``lib_xua`` and ``lib_spdif`` to your Makefile::
+
+  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::
+
+  USED_MODULES = .. lib_xud ..
+
+``lib_xud`` library requires some flags for correct operation. Firstly the 
+tile on which ``lib_xud`` will be execute, 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 that defines 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 library functions are defined in ``xua.h``. This header must
+be included in your code to use the library. 
+
+.. literalinclude:: app_xua_simple.xc
+   :start-on: include "xua.h"
+   :end-on: include "xud_device.h"
+
+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: /* 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_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 function in a par (``XUD_Main()``).
+
+For a simple application the following endpoints are required:
+
+    - ``Control`` enpoint 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 configued to enable S/PDIF Tx functionality. 
+
+``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
+
+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|
+
+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/AN00247_xua_example_spdif_tx/doc/rst/xdoc.conf

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

examples/AN00247_xua_example_spdif_tx/src/app_xua_simple.xc

@@ -0,0 +1,106 @@
+// Copyright 2017-2022 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
+
+/* 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, 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/hid_report_descriptor.h

@@ -0,0 +1,168 @@
+// Copyright 2021-2022 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
+#ifndef __hid_report_descriptor_h__
+#define __hid_report_descriptor_h__
+
+#include "xua_hid_report.h"
+
+#if 0
+/* Existing static report descriptor kept for reference */
+unsigned char hidReportDescriptor[] =
+{
+    0x05, 0x0c,     /* Usage Page (Consumer Device) */
+    0x09, 0x01,     /* Usage (Consumer Control) */
+    0xa1, 0x01,     /* Collection (Application) */
+    0x15, 0x00,     /* Logical Minimum (0) */
+    0x25, 0x01,     /* Logical Maximum (1) */
+    0x09, 0xb0,     /* Usage (Play) */
+    0x09, 0xb5,     /* Usage (Scan Next Track) */
+    0x09, 0xb6,     /* Usage (Scan Previous Track) */
+    0x09, 0xe9,     /* Usage (Volume Up) */
+    0x09, 0xea,     /* Usage (Volume Down) */
+    0x09, 0xe2,     /* Usage (Mute) */
+    0x75, 0x01,     /* Report Size (1) */
+    0x95, 0x06,     /* Report Count (6) */
+    0x81, 0x02,     /* Input (Data, Var, Abs) */
+    0x95, 0x02,     /* Report Count (2) */
+    0x81, 0x01,     /* Input (Cnst, Ary, Abs) */
+    0xc0            /* End collection */
+};
+#endif
+
+/*
+ * Define non-configurable items in the HID Report descriptor.
+ */
+static const USB_HID_Short_Item_t hidCollectionApplication  = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_MAIN, HID_REPORT_ITEM_TAG_COLLECTION),
+    .data = { 0x01, 0x00 } };
+static const USB_HID_Short_Item_t hidCollectionEnd          = {
+    .header = HID_REPORT_SET_HEADER(0, HID_REPORT_ITEM_TYPE_MAIN, HID_REPORT_ITEM_TAG_END_COLLECTION),
+    .data = { 0x00, 0x00 } };
+
+static const USB_HID_Short_Item_t hidInputConstArray        = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_MAIN, HID_REPORT_ITEM_TAG_INPUT),
+    .data = { 0x01, 0x00 } };
+static const USB_HID_Short_Item_t hidInputDataVar           = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_MAIN, HID_REPORT_ITEM_TAG_INPUT),
+    .data = { 0x02, 0x00 } };
+
+static const USB_HID_Short_Item_t hidLogicalMaximum0        = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_LOGICAL_MAXIMUM),
+    .data = { 0x00, 0x00 } };
+static const USB_HID_Short_Item_t hidLogicalMaximum1        = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_LOGICAL_MAXIMUM),
+    .data = { 0x01, 0x00 } };
+static const USB_HID_Short_Item_t hidLogicalMinimum0        = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_LOGICAL_MINIMUM),
+    .data = { 0x00, 0x00 } };
+
+static const USB_HID_Short_Item_t hidReportCount2           = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_REPORT_COUNT),
+    .data = { 0x02, 0x00 } };
+static const USB_HID_Short_Item_t hidReportCount6           = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_REPORT_COUNT),
+    .data = { 0x06, 0x00 } };
+static const USB_HID_Short_Item_t hidReportSize1            = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_REPORT_SIZE),
+    .data = { 0x01, 0x00 } };
+
+static const USB_HID_Short_Item_t hidUsageConsumerControl   = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+    .data = { 0x01, 0x00 } };
+
+/*
+ * Define the HID Report Descriptor Item, Usage Page, Report ID and length for each HID Report
+ * For internal purposes, a report element with ID of 0 must be included if report IDs are not being used.
+ */
+static const USB_HID_Report_Element_t hidReportPageConsumer = {
+    .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_USAGE_PAGE),
+    .item.data = { USB_HID_USAGE_PAGE_ID_CONSUMER, 0x00 },
+    .location = HID_REPORT_SET_LOC( 0, 2, 0, 0 )
+};
+
+/*
+ * Define configurable items in the HID Report descriptor.
+ */
+static USB_HID_Report_Element_t hidUsageByte0Bit5   = {
+     .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+     .item.data = { 0xE2, 0x00 },
+     .location = HID_REPORT_SET_LOC(0, 0, 0, 5)
+}; // Mute
+static USB_HID_Report_Element_t hidUsageByte0Bit4   = {
+     .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+     .item.data = { 0xEA, 0x00 },
+     .location = HID_REPORT_SET_LOC(0, 0, 0, 4)
+}; // Vol-
+static USB_HID_Report_Element_t hidUsageByte0Bit3   = {
+     .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+     .item.data = { 0xE9, 0x00 },
+     .location = HID_REPORT_SET_LOC(0, 0, 0, 3)
+}; // Vol+
+static USB_HID_Report_Element_t hidUsageByte0Bit2   = {
+     .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+     .item.data = { 0xB6, 0x00 },
+     .location = HID_REPORT_SET_LOC(0, 0, 0, 2)
+}; // Scan Prev
+static USB_HID_Report_Element_t hidUsageByte0Bit1   = {
+     .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+     .item.data = { 0xB5, 0x00 },
+     .location = HID_REPORT_SET_LOC(0, 0, 0, 1)
+}; // Scan Next
+static USB_HID_Report_Element_t hidUsageByte0Bit0   = {
+     .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+     .item.data = { 0xB0, 0x00 },
+     .location = HID_REPORT_SET_LOC(0, 0, 0, 0)
+}; // Play
+
+/*
+ * List the configurable elements in the HID Report descriptor.
+ */
+static USB_HID_Report_Element_t* const hidConfigurableElements[] = {
+    &hidUsageByte0Bit0,
+    &hidUsageByte0Bit1,
+    &hidUsageByte0Bit2,
+    &hidUsageByte0Bit3,
+    &hidUsageByte0Bit4,
+    &hidUsageByte0Bit5
+};
+
+/*
+ * List HID Reports, one per Report ID. This should be a usage page item with the relevant
+ * If not using report IDs - still have one with report ID 0
+ */
+static const USB_HID_Report_Element_t* const hidReports[] = {
+    &hidReportPageConsumer
+};
+
+/*
+ * List all items in the HID Report descriptor.
+ */
+static const USB_HID_Short_Item_t* const hidReportDescriptorItems[] = {
+    &(hidReportPageConsumer.item),
+    &hidUsageConsumerControl,
+    &hidCollectionApplication,
+        &hidLogicalMinimum0,
+        &hidLogicalMaximum1,
+        &(hidUsageByte0Bit0.item),
+        &(hidUsageByte0Bit1.item),
+        &(hidUsageByte0Bit2.item),
+        &(hidUsageByte0Bit3.item),
+        &(hidUsageByte0Bit4.item),
+        &(hidUsageByte0Bit5.item),
+        &hidReportSize1,
+        &hidReportCount6,
+        &hidInputDataVar,
+        &hidLogicalMaximum0,
+        &hidReportCount2,
+        &hidInputConstArray,
+    &hidCollectionEnd
+};
+
+/*
+ * Define the number of HID Reports
+ * Due to XC not supporting designated initializers, this constant has a hard-coded value.
+ * It must equal ( sizeof hidReports / sizeof ( USB_HID_Report_Element_t* ))
+ */
+#define HID_REPORT_COUNT ( 1 )
+
+#endif // __hid_report_descriptor_h__

examples/AN00247_xua_example_spdif_tx/src/hwsupport.xc

@@ -0,0 +1,52 @@
+// Copyright 2016-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
+
+#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 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" PageSize="256" SectorSize="4096" NumPages="8192">
+      <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,32 @@
+// Copyright 2017-2022 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
+
+#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,8 @@
+// Copyright 2017-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
+
+#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.rst

@@ -0,0 +1,84 @@
+*******************************
+XMOS PUBLIC LICENCE: Version 1
+*******************************
+
+Subject to the conditions and limitations below, permission is hereby granted by XMOS LIMITED (“XMOS”), free of charge, to any person or entity obtaining a copy of the XMOS Software.
+
+**1. Definitions**
+
+**“Applicable Patent Rights”** means: (a) where XMOS is the grantor of the rights, (i) claims of patents that are now or in future owned by or assigned to XMOS and (ii) that cover subject matter contained in the Software, but only to the extent it is necessary to use, reproduce or distribute the Software without infringement; and (b) where you are the grantor of the rights, (i) claims of patents that are now or in future owned by or assigned to you and (ii) that cover the subject matter contained in your Derivatives, taken alone or in combination with the Software.
+
+**“Compiled Code”** means any compiled, binary, machine readable or executable version of the Source Code.
+
+**“Contributor”** means any person or entity that creates or contributes to the creation of Derivatives.
+
+**“Derivatives”** means any addition to, deletion from and/or change to the substance, structure of the Software, any previous Derivatives, the combination of the Derivatives and the Software and/or any respective portions thereof.
+
+**“Source Code”** means the human readable code that is suitable for making modifications but excluding any Compiled Code.
+
+**“Software”** means the software and associated documentation files which XMOS makes available and which contain a notice identifying the software as original XMOS software and referring to the software being subject to the terms of this XMOS Public Licence.
+
+This Licence refers to XMOS Software and does not relate to any XMOS hardware or devices which are protected by intellectual property rights (including patent and trade marks) which may be sold to you under a separate agreement.
+
+
+**2. Licence**
+
+**Permitted Uses, Conditions and Restrictions.**  Subject to the conditions below, XMOS grants you a worldwide, royalty free, non-exclusive licence, to the extent of any Patent Rights to do the following:
+
+2.1 **Unmodified Software.** You may use, copy, display, publish, distribute and make available unmodified copies of the Software:
+
+2.1.1 for personal or academic, non-commercial purposes; or
+
+2.1.2 for commercial purposes provided the Software is at all times used on a device designed, licensed or developed by XMOS and, provided that in each instance (2.1.1 and 2.1.2):
+
+(a) you must retain and reproduce in all copies of the Software the copyright and proprietary notices and disclaimers of XMOS as they appear in the Software, and keep intact all notices and disclaimers in the Software files that refer to this Licence; and
+
+(b) you must include a copy of this Licence with every copy of the Software and documentation you publish, distribute and make available and you may not offer or impose any terms on such Software that alter or restrict this Licence or the intent of such Licence, except as permitted below (Additional Terms).
+
+The licence above does not include any Compiled Code which XMOS may make available under a separate support and licence agreement.
+
+2.2 **Derivatives.** You may create and modify Derivatives and use, copy, display, publish, distribute and make available Derivatives:
+
+2.2.1 for personal or academic, non-commercial purposes; or
+
+2.2.2 for commercial purposes, provided the Derivatives are at all times used on a device designed, licensed or developed by XMOS and, provided that in each instance (2.2.1 and 2.2.2):
+
+(a) you must comply with the terms of clause 2.1 with respect to the Derivatives;
+
+(b) you must copy (to the extent it doesn’t already exist) the notice below in each file of the Derivatives, and ensure all the modified files carry prominent notices stating that you have changed the files and the date of any change; and
+
+(c) if you sublicence, distribute or otherwise make the Software and/or the Derivatives available for commercial purposes, you must provide that the Software and Derivatives are at all times used on a device designed, licensed or developed by XMOS.
+
+Without limitation to these terms and clause 3 below, the Source Code and Compiled Code to your Derivatives may at your discretion (but without obligation) be released, copied, displayed, published, distributed and made available; and if you elect to do so, it must be under the terms of this Licence including the terms of the licence at clauses 2.2.1, 2.2.2 and clause 3 below.
+
+2.3 **Distribution of Executable Versions.**  If you distribute or make available Derivatives, you must include a prominent notice in the code itself as well as in all related documentation, stating that the Source Code of the Software from which the Derivatives are based is available under the terms of this Licence, with information on how and where to obtain such Source Code.
+
+**3. Your Grant of Rights.**  In consideration and as a condition to this Licence, you grant to any person or entity receiving or distributing any Derivatives, a non-exclusive, royalty free, perpetual, irrevocable license under your Applicable Patent Rights and all other intellectual property rights owned or controlled by you, to use, copy, display, publish, distribute and make available your Derivatives of the same scope and extent as XMOS’s licence under clause 2.2 above.
+
+**4. Combined Products.**  You may create a combined product by combining Software, Derivatives and other code not covered by this Licence as a single application or product. In such instance, you must comply with the requirements of this Licence for any portion of the Software and/or Derivatives.
+
+**5. Additional Terms.**  You may choose to offer, and to charge a fee for, warranty, support, indemnity or liability obligations and/or other rights consistent with the term of this Licence (“Additional Terms”) to any legitimate recipients of the Software and/or Derivatives.  The terms on which you provide such Additional Terms are on your sole responsibility and you shall indemnify, defend and hold XMOS harmless against any claims asserted against XMOS.
+
+**6. New Versions.**  XMOS may publish revised and/or new versions of this Licence from time to time to accommodate changes to the Licence terms, new versions, updates and bug fixes of the Software.  Each version will be given a distinguishing version number.  Once Software has been published under a particular version of this Licence, you may continue to use it under the terms of that version.  You may also choose to use the latest version of the Software under any subsequent version published by XMOS.  Only XMOS shall have the right to modify these terms.
+
+**7. IPR and Ownership**
+Any rights, including all intellectual property rights and all trademarks not expressly granted herein are reserved in full by the authors or copyright holders. Any requests for additional permissions by XMOS including any rights to use XMOS trademarks, should be made (without obligation) to XMOS at **support@xmos.com**
+
+Nothing herein shall limit any rights that XMOS is otherwise entitled to under the doctrines of patent exhaustion, implied license, or legal estoppel.  Neither the name of the authors, the copyright holders or any contributors may be used to endorse or promote any Derivatives from this Software without specific written permission.  Any attempt to deal with the Software which does not comply with this Licence shall be void and shall automatically terminate any rights granted under this licence (including any licence of any intellectual property rights granted herein).
+Subject to the licences granted under this Licence any Contributor retains all rights, title and interest in and to any Derivatives made by Contributor subject to the underlying rights of XMOS in the Software.  XMOS shall retain all rights, title and interest in the Software and any Derivatives made by XMOS (“XMOS Derivatives”).  XMOS Derivatives will not automatically be subject to this Licence and XMOS shall be entitled to licence such rights on any terms (without obligation) as it sees fit.
+
+**8. Termination**
+
+8.1 This Licence will automatically terminate immediately, without notice to you, if:
+
+(a) you fail to comply with the terms of this Licence; and/or
+
+(b) you directly or indirectly commence any action for patent or intellectual property right infringement against XMOS, or any parent, group, affiliate or subsidiary of XMOS; provided XMOS did not first commence an action or patent infringement against you in that instance; and/or
+
+(c) the terms of this Licence are held by any court of competent jurisdiction to be unenforceable in whole or in part.
+
+**9. Critical Applications.**  Unless XMOS has agreed in writing with you an agreement specifically governing use of the Goods in military, aerospace, automotive or medically related functions (collectively and individually hereinafter referred to as "Special Use"), any permitted use of the Software excludes Special Use. Notwithstanding any agreement between XMOS and you for Special Use, Special Use shall be at your own risk, and you shall fully indemnify XMOS against any damages, losses, costs and claims (direct and indirect) arising out of any Special Use.
+
+**10. NO WARRANTY OR SUPPORT.**  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL XMOS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, WARRANTY, CIVIL TORT (INCLUDING NEGLIGENCE), PRODUCTS LIABILITY OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE INCLUDING GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES EVEN IF SUCH PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES AND NOT WITHSTANDING THE FAILURE OF ESSENTIAL PURPOSE.  IN SOME JURISDICTIONS PARTIES ARE UNABLE TO LIMIT LIABILTY IN THIS WAY, IF THIS APPLIES TO YOUR JURISDICTION THIS LIABILITY CLAUSE ABOVE MAY NOT APPLY.  NOTWITHSTANDING THE ABOVE, IN NO EVENT SHALL XMOS’s TOTAL LIABILITY TO YOU FOR ALL DAMAGES, LOSS OR OTHERWISE EXCEED $50.
+
+**11. Governing Law and Jurisdiction.**  This Licence constitutes the entire agreement between the parties with respect to the subject matter hereof. The Licence shall be governed by the laws of England and the conflict of laws and UN Convention on Contracts for the International Sale of Goods, shall not apply.

examples/AN00248_xua_example_pdm_mics/Makefile

@@ -0,0 +1,22 @@
+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 -save-temps \
+			  -g -Wno-unused-function -Wno-timing -DXUD_SERIES_SUPPORT=XUD_X200_SERIES \
+			  -DXUD_CORE_CLOCK=600 -DUSB_TILE=tile[1] -DSDA_HIGH=2 -DSCL_HIGH=1 -fxscope \
+			  -DUAC_FORCE_FEEDBACK_EP=0
+
+# 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,35 @@
+
+Using lib_xua with lib_mic_array
+================================
+
+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.
+
+Software dependencies
+.....................
+
+For a list of direct dependencies, look for USED_MODULES in the Makefile.
+
+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_xua_example_pdm_mics.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,3 @@
+XMOSNEWSTYLE=2
+SOURCE_INCLUDE_DIRS=../../src
+SPHINX_MASTER_DOC=AN00248_xua_example_pdm_mics

examples/AN00248_xua_example_pdm_mics/src/app_xua_simple.xc

@@ -0,0 +1,121 @@
+// Copyright 2017-2022 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
+
+/* 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, 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,31 @@
+// Copyright 2017-2022 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
+
+#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/hid_report_descriptor.h

@@ -0,0 +1,168 @@
+// Copyright 2021-2022 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
+#ifndef __hid_report_descriptor_h__
+#define __hid_report_descriptor_h__
+
+#include "xua_hid_report.h"
+
+#if 0
+/* Existing static report descriptor kept for reference */
+unsigned char hidReportDescriptor[] =
+{
+    0x05, 0x0c,     /* Usage Page (Consumer Device) */
+    0x09, 0x01,     /* Usage (Consumer Control) */
+    0xa1, 0x01,     /* Collection (Application) */
+    0x15, 0x00,     /* Logical Minimum (0) */
+    0x25, 0x01,     /* Logical Maximum (1) */
+    0x09, 0xb0,     /* Usage (Play) */
+    0x09, 0xb5,     /* Usage (Scan Next Track) */
+    0x09, 0xb6,     /* Usage (Scan Previous Track) */
+    0x09, 0xe9,     /* Usage (Volume Up) */
+    0x09, 0xea,     /* Usage (Volume Down) */
+    0x09, 0xe2,     /* Usage (Mute) */
+    0x75, 0x01,     /* Report Size (1) */
+    0x95, 0x06,     /* Report Count (6) */
+    0x81, 0x02,     /* Input (Data, Var, Abs) */
+    0x95, 0x02,     /* Report Count (2) */
+    0x81, 0x01,     /* Input (Cnst, Ary, Abs) */
+    0xc0            /* End collection */
+};
+#endif
+
+/*
+ * Define non-configurable items in the HID Report descriptor.
+ */
+static const USB_HID_Short_Item_t hidCollectionApplication  = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_MAIN, HID_REPORT_ITEM_TAG_COLLECTION),
+    .data = { 0x01, 0x00 } };
+static const USB_HID_Short_Item_t hidCollectionEnd          = {
+    .header = HID_REPORT_SET_HEADER(0, HID_REPORT_ITEM_TYPE_MAIN, HID_REPORT_ITEM_TAG_END_COLLECTION),
+    .data = { 0x00, 0x00 } };
+
+static const USB_HID_Short_Item_t hidInputConstArray        = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_MAIN, HID_REPORT_ITEM_TAG_INPUT),
+    .data = { 0x01, 0x00 } };
+static const USB_HID_Short_Item_t hidInputDataVar           = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_MAIN, HID_REPORT_ITEM_TAG_INPUT),
+    .data = { 0x02, 0x00 } };
+
+static const USB_HID_Short_Item_t hidLogicalMaximum0        = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_LOGICAL_MAXIMUM),
+    .data = { 0x00, 0x00 } };
+static const USB_HID_Short_Item_t hidLogicalMaximum1        = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_LOGICAL_MAXIMUM),
+    .data = { 0x01, 0x00 } };
+static const USB_HID_Short_Item_t hidLogicalMinimum0        = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_LOGICAL_MINIMUM),
+    .data = { 0x00, 0x00 } };
+
+static const USB_HID_Short_Item_t hidReportCount2           = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_REPORT_COUNT),
+    .data = { 0x02, 0x00 } };
+static const USB_HID_Short_Item_t hidReportCount6           = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_REPORT_COUNT),
+    .data = { 0x06, 0x00 } };
+static const USB_HID_Short_Item_t hidReportSize1            = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_REPORT_SIZE),
+    .data = { 0x01, 0x00 } };
+
+static const USB_HID_Short_Item_t hidUsageConsumerControl   = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+    .data = { 0x01, 0x00 } };
+
+/*
+ * Define the HID Report Descriptor Item, Usage Page, Report ID and length for each HID Report
+ * For internal purposes, a report element with ID of 0 must be included if report IDs are not being used.
+ */
+static const USB_HID_Report_Element_t hidReportPageConsumer = {
+    .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_USAGE_PAGE),
+    .item.data = { USB_HID_USAGE_PAGE_ID_CONSUMER, 0x00 },
+    .location = HID_REPORT_SET_LOC( 0, 2, 0, 0 )
+};
+
+/*
+ * Define configurable items in the HID Report descriptor.
+ */
+static USB_HID_Report_Element_t hidUsageByte0Bit5   = {
+     .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+     .item.data = { 0xE2, 0x00 },
+     .location = HID_REPORT_SET_LOC(0, 0, 0, 5)
+}; // Mute
+static USB_HID_Report_Element_t hidUsageByte0Bit4   = {
+     .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+     .item.data = { 0xEA, 0x00 },
+     .location = HID_REPORT_SET_LOC(0, 0, 0, 4)
+}; // Vol-
+static USB_HID_Report_Element_t hidUsageByte0Bit3   = {
+     .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+     .item.data = { 0xE9, 0x00 },
+     .location = HID_REPORT_SET_LOC(0, 0, 0, 3)
+}; // Vol+
+static USB_HID_Report_Element_t hidUsageByte0Bit2   = {
+     .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+     .item.data = { 0xB6, 0x00 },
+     .location = HID_REPORT_SET_LOC(0, 0, 0, 2)
+}; // Scan Prev
+static USB_HID_Report_Element_t hidUsageByte0Bit1   = {
+     .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+     .item.data = { 0xB5, 0x00 },
+     .location = HID_REPORT_SET_LOC(0, 0, 0, 1)
+}; // Scan Next
+static USB_HID_Report_Element_t hidUsageByte0Bit0   = {
+     .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+     .item.data = { 0xB0, 0x00 },
+     .location = HID_REPORT_SET_LOC(0, 0, 0, 0)
+}; // Play
+
+/*
+ * List the configurable elements in the HID Report descriptor.
+ */
+static USB_HID_Report_Element_t* const hidConfigurableElements[] = {
+    &hidUsageByte0Bit0,
+    &hidUsageByte0Bit1,
+    &hidUsageByte0Bit2,
+    &hidUsageByte0Bit3,
+    &hidUsageByte0Bit4,
+    &hidUsageByte0Bit5
+};
+
+/*
+ * List HID Reports, one per Report ID. This should be a usage page item with the relevant
+ * If not using report IDs - still have one with report ID 0
+ */
+static const USB_HID_Report_Element_t* const hidReports[] = {
+    &hidReportPageConsumer
+};
+
+/*
+ * List all items in the HID Report descriptor.
+ */
+static const USB_HID_Short_Item_t* const hidReportDescriptorItems[] = {
+    &(hidReportPageConsumer.item),
+    &hidUsageConsumerControl,
+    &hidCollectionApplication,
+        &hidLogicalMinimum0,
+        &hidLogicalMaximum1,
+        &(hidUsageByte0Bit0.item),
+        &(hidUsageByte0Bit1.item),
+        &(hidUsageByte0Bit2.item),
+        &(hidUsageByte0Bit3.item),
+        &(hidUsageByte0Bit4.item),
+        &(hidUsageByte0Bit5.item),
+        &hidReportSize1,
+        &hidReportCount6,
+        &hidInputDataVar,
+        &hidLogicalMaximum0,
+        &hidReportCount2,
+        &hidInputConstArray,
+    &hidCollectionEnd
+};
+
+/*
+ * Define the number of HID Reports
+ * Due to XC not supporting designated initializers, this constant has a hard-coded value.
+ * It must equal ( sizeof hidReports / sizeof ( USB_HID_Report_Element_t* ))
+ */
+#define HID_REPORT_COUNT ( 1 )
+
+#endif // __hid_report_descriptor_h__

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" PageSize="256" SectorSize="4096" NumPages="8192">
+      <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,31 @@
+// Copyright 2017-2022 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
+
+#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,8 @@
+// Copyright 2017-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
+
+#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/__app_xua_simple/LICENSE.txt

@@ -1,135 +0,0 @@
-Software Release License Agreement
-
-Copyright (c) 2018, 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 lib_xua software

host/xmosdfu/Makefile.Linux32

@@ -1,2 +0,0 @@
-all:
-	g++ -m32 -Wall -g -o xmosdfu xmosdfu.cpp -Ilibusb/Linux32 -lusb-1.0

host/xmosdfu/Makefile.Linux64

@@ -1,2 +0,0 @@
-all:
-	g++ -Wall -g -o xmosdfu xmosdfu.cpp -Ilibusb/Linux32 -lusb-1.0

host/xmosdfu/Makefile.OSX32

@@ -1,2 +0,0 @@
-all:
-	g++ -g -o xmosdfu xmosdfu.cpp -Ilibusb/OSX32 libusb/OSX32/libusb-1.0.0.dylib -m32 -Wall

host/xmosdfu/Makefile.OSX64

@@ -1,2 +0,0 @@
-all:
-	g++ -g -o xmosdfu xmosdfu.cpp -Ilibusb/OSX64 libusb/OSX64/libusb-1.0.0.dylib -Wall

legacy_tests/app_test_i2s_loopback/Makefile

@@ -1,9 +1,7 @@
-# Copyright (c) 2016, XMOS Ltd, All rights reserved
 TARGET = xk-audio-216-mc.xn
-USED_MODULES = lib_xua \
-               module_i2c_shared module_i2c_single_port lib_logging 
+USED_MODULES = lib_xua lib_i2c lib_logging
 
-BUILD_FLAGS = -O0 -g -lflash -DXUD_SERIES_SUPPORT=4 -fxscope -save-temps -march=xs2a -DUSB_TILE=tile[1]
+BUILD_FLAGS = -O0 -g -lflash -DXUD_SERIES_SUPPORT=4 -DXUD_CORE_CLOCK=600 -fxscope -save-temps -march=xs2a -DUSB_TILE=tile[1]
 
 BUILD_FLAGS_i2s_master_2in_2out_48khz = $(BUILD_FLAGS) \
   -D ADAT_RX=0 -D ADAT_TX=0 -D SPDIF_RX=0 -D SPDIF_TX=0 -D MIDI=0 \

legacy_tests/app_test_i2s_loopback/debug_conf.h

@@ -1,4 +1,5 @@
-// Copyright (c) 2016-2018, XMOS Ltd, All rights reserved
+// Copyright 2016-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 #ifndef __debug_conf_h__
 #define __debug_conf_h__
 

legacy_tests/app_test_i2s_loopback/hid_report_descriptor.h

@@ -0,0 +1,167 @@
+// Copyright 2021-2022 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
+#ifndef __hid_report_descriptor_h__
+#define __hid_report_descriptor_h__
+
+#include "xua_hid_report.h"
+
+#if 0
+/* Existing static report descriptor kept for reference */
+unsigned char hidReportDescriptor[] =
+{
+    0x05, 0x0c,     /* Usage Page (Consumer Device) */
+    0x09, 0x01,     /* Usage (Consumer Control) */
+    0xa1, 0x01,     /* Collection (Application) */
+    0x15, 0x00,     /* Logical Minimum (0) */
+    0x25, 0x01,     /* Logical Maximum (1) */
+    0x09, 0xb0,     /* Usage (Play) */
+    0x09, 0xb5,     /* Usage (Scan Next Track) */
+    0x09, 0xb6,     /* Usage (Scan Previous Track) */
+    0x09, 0xe9,     /* Usage (Volume Up) */
+    0x09, 0xea,     /* Usage (Volume Down) */
+    0x09, 0xe2,     /* Usage (Mute) */
+    0x75, 0x01,     /* Report Size (1) */
+    0x95, 0x06,     /* Report Count (6) */
+    0x81, 0x02,     /* Input (Data, Var, Abs) */
+    0x95, 0x02,     /* Report Count (2) */
+    0x81, 0x01,     /* Input (Cnst, Ary, Abs) */
+    0xc0            /* End collection */
+};
+#endif
+
+/*
+ * Define non-configurable items in the HID Report descriptor.
+ */
+static const USB_HID_Short_Item_t hidCollectionApplication  = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_MAIN, HID_REPORT_ITEM_TAG_COLLECTION),
+    .data = { 0x01, 0x00 } };
+static const USB_HID_Short_Item_t hidCollectionEnd          = {
+    .header = HID_REPORT_SET_HEADER(0, HID_REPORT_ITEM_TYPE_MAIN, HID_REPORT_ITEM_TAG_END_COLLECTION),
+    .data = { 0x00, 0x00 } };
+
+static const USB_HID_Short_Item_t hidInputConstArray        = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_MAIN, HID_REPORT_ITEM_TAG_INPUT),
+    .data = { 0x01, 0x00 } };
+static const USB_HID_Short_Item_t hidInputDataVar           = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_MAIN, HID_REPORT_ITEM_TAG_INPUT),
+    .data = { 0x02, 0x00 } };
+
+static const USB_HID_Short_Item_t hidLogicalMaximum0        = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_LOGICAL_MAXIMUM),
+    .data = { 0x00, 0x00 } };
+static const USB_HID_Short_Item_t hidLogicalMaximum1        = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_LOGICAL_MAXIMUM),
+    .data = { 0x01, 0x00 } };
+static const USB_HID_Short_Item_t hidLogicalMinimum0        = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_LOGICAL_MINIMUM),
+    .data = { 0x00, 0x00 } };
+
+static const USB_HID_Short_Item_t hidReportCount2           = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_REPORT_COUNT),
+    .data = { 0x02, 0x00 } };
+static const USB_HID_Short_Item_t hidReportCount6           = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_REPORT_COUNT),
+    .data = { 0x06, 0x00 } };
+static const USB_HID_Short_Item_t hidReportSize1            = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_REPORT_SIZE),
+    .data = { 0x01, 0x00 } };
+
+static const USB_HID_Short_Item_t hidUsageConsumerControl   = {
+    .header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+    .data = { 0x01, 0x00 } };
+
+/*
+ * Define the HID Report Descriptor Item, Usage Page, Report ID and length for each HID Report
+ * For internal purposes, a report element with ID of 0 must be included if report IDs are not being used.
+ */
+static const USB_HID_Report_Element_t hidReportPageConsumer     = {
+    .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_GLOBAL, HID_REPORT_ITEM_TAG_USAGE_PAGE),
+    .item.data = { USB_HID_USAGE_PAGE_ID_CONSUMER, 0x00 },
+    .location = HID_REPORT_SET_LOC( 0, 1, 0, 0 ) };
+
+/*
+ * Define configurable items in the HID Report descriptor.
+ */
+static USB_HID_Report_Element_t hidUsageByte0Bit5   = {
+    .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+    .item.data = { 0xE2, 0x00 },
+    .location = HID_REPORT_SET_LOC( 0, 0, 0, 5 )
+}; // Mute
+static USB_HID_Report_Element_t hidUsageByte0Bit4   = {
+    .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+    .item.data = { 0xEA, 0x00 },
+    .location = HID_REPORT_SET_LOC( 0, 0, 0, 4 )
+}; // Vol-
+static USB_HID_Report_Element_t hidUsageByte0Bit3   = {
+    .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+    .item.data = { 0xE9, 0x00 },
+    .location = HID_REPORT_SET_LOC( 0, 0, 0, 3 )
+}; // Vol+
+static USB_HID_Report_Element_t hidUsageByte0Bit2   = {
+    .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+    .item.data = { 0xB6, 0x00 },
+    .location = HID_REPORT_SET_LOC( 0, 0, 0, 2 )
+}; // Scan Prev
+static USB_HID_Report_Element_t hidUsageByte0Bit1   = {
+    .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+    .item.data = { 0xB5, 0x00 },
+    .location = HID_REPORT_SET_LOC( 0, 0, 0, 1 )
+}; // Scan Next
+static USB_HID_Report_Element_t hidUsageByte0Bit0   = {
+    .item.header = HID_REPORT_SET_HEADER(1, HID_REPORT_ITEM_TYPE_LOCAL, HID_REPORT_ITEM_TAG_USAGE),
+    .item.data = { 0xB0, 0x00 },
+    .location = HID_REPORT_SET_LOC( 0, 0, 0, 0 )
+}; // Play
+
+/*
+ * List the configurable items in the HID Report descriptor.
+ */
+static USB_HID_Report_Element_t* const hidConfigurableElements[] = {
+    &hidUsageByte0Bit0,
+    &hidUsageByte0Bit1,
+    &hidUsageByte0Bit2,
+    &hidUsageByte0Bit3,
+    &hidUsageByte0Bit4,
+    &hidUsageByte0Bit5
+};
+
+/*
+ * List HID Reports, one per Report ID. This should be a usage page item with the relevant
+ * If not using report IDs - still have one with report ID 0
+ */
+static const USB_HID_Report_Element_t* const hidReports[] = {
+    &hidReportPageConsumer
+};
+
+/*
+ * List all items in the HID Report descriptor.
+ */
+static const USB_HID_Short_Item_t * const hidReportDescriptorItems[] = {
+    &(hidReportPageConsumer.item),
+    &hidUsageConsumerControl,
+    &hidCollectionApplication,
+        &hidLogicalMinimum0,
+        &hidLogicalMaximum1,
+        &(hidUsageByte0Bit0.item),
+        &(hidUsageByte0Bit1.item),
+        &(hidUsageByte0Bit2.item),
+        &(hidUsageByte0Bit3.item),
+        &(hidUsageByte0Bit4.item),
+        &(hidUsageByte0Bit5.item),
+        &hidReportSize1,
+        &hidReportCount6,
+        &hidInputDataVar,
+        &hidLogicalMaximum0,
+        &hidReportCount2,
+        &hidInputConstArray,
+    &hidCollectionEnd
+};
+
+/*
+ * Define the number of HID Reports
+ * Due to XC not supporting designated initializers, this constant has a hard-coded value.
+ * It must equal ( sizeof hidReports / sizeof ( USB_HID_Report_Element_t* ))
+ */
+#define HID_REPORT_COUNT ( 1 )
+
+#endif // __hid_report_descriptor_h__

legacy_tests/app_test_i2s_loopback/main.xc

@@ -1,4 +1,5 @@
-// Copyright (c) 2016-2018, XMOS Ltd, All rights reserved
+// Copyright 2016-2022 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 #include <platform.h>
 #include <stdlib.h>
 #include <print.h>
@@ -77,20 +78,12 @@ 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 */
 #endif
 
-/* 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;
+in port p_mclk_in                   = PORT_MCLK_IN;
 
 /* Clock-block declarations */
-clock clk_audio_bclk                = on tile[AUDIO_IO_TILE]: XS1_CLKBLK_1;   /* Bit clock */    
+clock clk_audio_bclk                = on tile[AUDIO_IO_TILE]: XS1_CLKBLK_1;   /* Bit clock */
 clock clk_audio_mclk                = on tile[AUDIO_IO_TILE]: XS1_CLKBLK_2;   /* Master clock */
 
-unsafe
-{
-    /* TODO simplify this */
-    unsafe port p_mclk_in;                           /* Audio master clock input */
-}
-
 #ifdef SIMULATION
 #define INITIAL_SKIP_FRAMES 10
 #define TOTAL_TEST_FRAMES 100
@@ -196,14 +189,14 @@ void checker(chanend c_checker, int disable)
 
 #ifdef SIMULATION
 
-out port p_mclk_gen       = on tile[AUDIO_IO_TILE] :  XS1_PORT_1A; 
+out port p_mclk_gen       = on tile[AUDIO_IO_TILE] :  XS1_PORT_1A;
 clock clk_audio_mclk_gen  = on tile[AUDIO_IO_TILE] : XS1_CLKBLK_3;
 void master_mode_clk_setup(void);
 
 #if CODEC_MASTER
-out port  p_bclk_gen      = on tile[AUDIO_IO_TILE] : XS1_PORT_1B;  
+out port  p_bclk_gen      = on tile[AUDIO_IO_TILE] : XS1_PORT_1B;
 clock clk_audio_bclk_gen  = on tile[AUDIO_IO_TILE] : XS1_CLKBLK_4;
-out port  p_lrclk_gen     = on tile[AUDIO_IO_TILE] : XS1_PORT_1C; 
+out port  p_lrclk_gen     = on tile[AUDIO_IO_TILE] : XS1_PORT_1C;
 clock clk_audio_lrclk_gen = on tile[AUDIO_IO_TILE] : XS1_CLKBLK_5;
 void slave_mode_clk_setup(const unsigned samFreq, const unsigned chans_per_frame);
 #endif
@@ -211,38 +204,35 @@ void slave_mode_clk_setup(const unsigned samFreq, const unsigned chans_per_frame
 #endif
 
 #if I2S_MODE_TDM
-const int i2s_tdm_mode = 1;
+const int i2s_tdm_mode = 8;
 #else
-const int i2s_tdm_mode = 0;
+const int i2s_tdm_mode = 2;
 #endif
 
 int main(void)
 {
-  chan c_checker;
-  chan c_out;
+    chan c_checker;
+    chan c_out;
 
-  par {
-    on tile[AUDIO_IO_TILE]: 
+    par
     {
-      unsafe
-      {
-        p_mclk_in = p_mclk_in_;
-      }
-      par 
-      {
-        XUA_AudioHub(c_out);
-        generator(c_checker, c_out);
-        checker(c_checker, 0);
+        on tile[AUDIO_IO_TILE]:
+        {
+            par
+            {
+                XUA_AudioHub(c_out, clk_audio_mclk, clk_audio_bclk, p_mclk_in, p_lrclk, p_bclk, p_i2s_dac, p_i2s_adc);
+                generator(c_checker, c_out);
+                checker(c_checker, 0);
 #ifdef SIMULATION
 #if CODEC_MASTER
-        slave_mode_clk_setup(DEFAULT_FREQ, (i2s_tdm_mode != 0) ? 8 : 2);
+                slave_mode_clk_setup(DEFAULT_FREQ, i2s_tdm_mode);
 #else
-        master_mode_clk_setup();
+                master_mode_clk_setup();
 #endif
 #endif
-      }
+            }
+        }
     }
-  }
 
-  return 0;
+    return 0;
 }

legacy_tests/app_test_i2s_loopback/simulation.xc

@@ -1,4 +1,5 @@
-// Copyright (c) 2016-2018, XMOS Ltd, All rights reserved
+// Copyright 2016-2022 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 #ifdef SIMULATION
 
 #include <platform.h>
@@ -21,7 +22,7 @@ void AudioHwInit()
 
 
 extern clock clk_audio_mclk_gen;
-extern out port p_mclk_gen; 
+extern out port p_mclk_gen;
 void master_mode_clk_setup(void)
 {
   configure_clock_rate(clk_audio_mclk_gen, 25, 1); // Slighly faster than typical MCLK of 24.576MHz
@@ -34,17 +35,17 @@ void master_mode_clk_setup(void)
 
 
 #if CODEC_MASTER
-extern out port  p_bclk_gen;  
+extern out port  p_bclk_gen;
 extern clock clk_audio_bclk_gen;
-extern out port  p_lrclk_gen; 
+extern out port  p_lrclk_gen;
 extern clock clk_audio_lrclk_gen;
 
 void slave_mode_clk_setup(const unsigned samFreq, const unsigned chans_per_frame){
   const unsigned data_bits = 32;
   const unsigned mclk_freq = 24576000;
 
-  const unsigned mclk_bclk_ratio = mclk_freq / (chans_per_frame * samFreq * data_bits); 
-  const unsigned bclk_lrclk_ratio = (chans_per_frame * data_bits); // 48.828Hz  LRCLK 
+  const unsigned mclk_bclk_ratio = mclk_freq / (chans_per_frame * samFreq * data_bits);
+  const unsigned bclk_lrclk_ratio = (chans_per_frame * data_bits); // 48.828Hz  LRCLK
 
   //bclk
   configure_clock_src_divide(clk_audio_bclk_gen, p_mclk_gen, mclk_bclk_ratio/2);

legacy_tests/app_test_i2s_loopback/usb_device.h

@@ -1,4 +1,5 @@
-// Copyright (c) 2016-2018, XMOS Ltd, All rights reserved
+// Copyright 2016-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 #ifndef __usb_device_h__
 #define __usb_device_h__
 

legacy_tests/app_test_i2s_loopback/usb_device.xc

@@ -1,4 +1,5 @@
-// Copyright (c) 2018, XMOS Ltd, All rights reserved
+// Copyright 2018-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 #if 0
 #include <xs1.h>
 #include <xccompat.h>

legacy_tests/app_test_i2s_loopback/xk_216_mc/audiohw.xc

@@ -1,4 +1,5 @@
-// Copyright (c) 2016-2018, XMOS Ltd, All rights reserved
+// Copyright 2016-2022 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 #ifdef HARDWARE
 
 #include <xs1.h>
@@ -7,7 +8,7 @@
 #include "devicedefines.h"
 #include <platform.h>
 #include "gpio_access.h"
-#include "i2c_shared.h"
+#include "i2c.h"
 #include "cs4384.h"
 #include "cs5368.h"
 #include "cs2100.h"
@@ -24,16 +25,10 @@
 
 on tile[0] : out port p_gpio = XS1_PORT_8C;
 
-#ifndef IAP
-/* If IAP not enabled, i2c ports not declared - still needs for DAC config */
-on tile [0] : struct r_i2c r_i2c = {XS1_PORT_4A};
-#else
-extern struct r_i2c r_i2c;
-#endif
+port p_i2c = on tile[0]:PORT_I2C;
 
-#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 ADC_REGWRITE(reg, val) {result = i2c.write_reg(CS5368_I2C_ADDR, reg, val);}
 
 #ifdef USE_FRACTIONAL_N
 
@@ -44,14 +39,15 @@ extern struct r_i2c r_i2c;
 #define PLL_SYNC_FREQ 300
 #endif
 
-#define CS2100_REGREAD(reg, data)  {data[0] = 0xAA; i2c_master_read_reg(CS2100_I2C_DEVICE_ADDR, reg, data, 1, r_i2c);}
-#define CS2100_REGREAD_ASSERT(reg, data, expected)  {data[0] = 0xAA; i2c_master_read_reg(CS2100_I2C_DEVICE_ADDR, reg, data, 1, r_i2c); assert(data[0] == expected);}
-#define CS2100_REGWRITE(reg, val) {data[0] = val; i2c_master_write_reg(CS2100_I2C_DEVICE_ADDR, reg, data, 1, r_i2c);}
+#define CS2100_REGREAD(reg, data) {data[0] = i2c.read_reg(CS2100_I2C_DEVICE_ADDR, reg, result);}
+#define CS2100_REGREAD_ASSERT(reg, data, expected) {data[0] = i2c.read_reg(CS2100_I2C_DEVICE_ADDR, reg, result); assert(data[0] == expected);}
+#define CS2100_REGWRITE(reg, val) {result = i2c.write_reg(CS2100_I2C_DEVICE_ADDR, reg, val);}
 
 /* Init of CS2100 */
-void PllInit(void)
+void PllInit(client interface i2c_master_if i2c)
 {
     unsigned char data[1] = {0};
+    i2c_regop_res_t result;
 
 #if XCORE_200_MC_AUDIO_HW_VERSION < 2
     /* Enable init */
@@ -72,12 +68,15 @@ void PllInit(void)
     CS2100_REGREAD_ASSERT(CS2100_GLOBAL_CONFIG, data, 0x01);
     CS2100_REGREAD_ASSERT(CS2100_FUNC_CONFIG_1, data, 0x08);
     CS2100_REGREAD_ASSERT(CS2100_FUNC_CONFIG_2, data, 0x00);
+
+    i2c.shutdown();
 }
 
 /* Setup PLL multiplier */
-void PllMult(unsigned output, unsigned ref)
+void PllMult(unsigned output, unsigned ref, client interface i2c_master_if i2c)
 {
     unsigned char data[1] = {0};
+    i2c_regop_res_t result;
 
     /* PLL expects 12:20 format, convert output and ref to 12:20 */
     /* Shift up the dividend by 12 to retain format... */
@@ -119,9 +118,6 @@ void AudioHwInit(chanend ?c_codec)
     start_clock(clk_pll_sync);
 #endif
 
-    /* Init the i2c module */
-    i2c_shared_master_init(r_i2c);
-
     /* Assert reset to ADC and DAC */
     set_gpio(P_GPIO_DAC_RST_N, 0);
     set_gpio(P_GPIO_ADC_RST_N, 0);
@@ -142,7 +138,12 @@ void AudioHwInit(chanend ?c_codec)
     set_gpio(P_GPIO_PLL_SEL, 1);
 
      /* Initialise external PLL */
-    PllInit();
+    i2c_master_if i2c[1];
+    par
+    {
+        i2c_master_single_port(i2c, 1, p_i2c, 10, 0, 1, 0);
+        PllInit(i2c[0]);
+    }
 #endif
 
 #ifdef IAP
@@ -154,10 +155,11 @@ void AudioHwInit(chanend ?c_codec)
 /* Configures the external audio hardware for the required sample frequency.
  * See gpio.h for I2C helper functions and gpio access
  */
-void AudioHwConfig(unsigned samFreq, unsigned mClk, chanend ?c_codec, unsigned dsdMode,
-    unsigned sampRes_DAC, unsigned sampRes_ADC)
+void AudioHwConfig2(unsigned samFreq, unsigned mClk, chanend ?c_codec, unsigned dsdMode,
+    unsigned sampRes_DAC, unsigned sampRes_ADC, client interface i2c_master_if i2c)
 {
-	unsigned char data[1] = {0};
+    unsigned char data[1] = {0};
+    i2c_regop_res_t result;
 
     /* Put ADC and DAC into reset */
 	set_gpio(P_GPIO_ADC_RST_N, 0);
@@ -166,7 +168,7 @@ void AudioHwConfig(unsigned samFreq, unsigned mClk, chanend ?c_codec, unsigned d
     /* Set master clock select appropriately */
 #if defined(USE_FRACTIONAL_N)
     /* Configure external fractional-n clock multiplier for 300Hz -> mClkFreq */
-    PllMult(mClk, PLL_SYNC_FREQ);
+    PllMult(mClk, PLL_SYNC_FREQ, i2c);
 #endif
     /* Allow some time for mclk to lock and MCLK to stabilise - this is important to avoid glitches at start of stream */
     {
@@ -364,8 +366,20 @@ void AudioHwConfig(unsigned samFreq, unsigned mClk, chanend ?c_codec, unsigned d
         DAC_REGWRITE(CS4384_MODE_CTRL, 0b10000000);
     }
 #endif
+
+    i2c.shutdown();
     return;
 }
-//:
+
+void AudioHwConfig(unsigned samFreq, unsigned mClk, chanend ?c_codec, 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, c_codec, dsdMode, sampRes_DAC, sampRes_ADC, i2c[0]);
+    }
+}
 
 #endif

legacy_tests/app_test_i2s_loopback/xk_216_mc/cs2100.h

@@ -1,4 +1,5 @@
-// Copyright (c) 2018, XMOS Ltd, All rights reserved
+// Copyright 2018-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 #define CS2100_I2C_DEVICE_ADDR      (0x9c>>1)
 
 #define CS2100_DEVICE_CONTROL       0x02

legacy_tests/app_test_i2s_loopback/xk_216_mc/cs4384.h

@@ -1,4 +1,5 @@
-// Copyright (c) 2017-2018, XMOS Ltd, All rights reserved
+// Copyright 2017-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 #ifndef CS4384_H_
 #define CS4384_H_
 

legacy_tests/app_test_i2s_loopback/xk_216_mc/cs5368.h

@@ -1,4 +1,5 @@
-// Copyright (c) 2017-2018, XMOS Ltd, All rights reserved
+// Copyright 2017-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 #ifndef _CS5368_H_
 #define _CS5368_H_
 

legacy_tests/app_test_i2s_loopback/xk_216_mc/gpio_access.c

@@ -1,4 +1,5 @@
-// Copyright (c) 2016-2018, XMOS Ltd, All rights reserved
+// Copyright 2016-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 #ifdef HARDWARE
 #include <xs1.h>
 #include "gpio_access.h"

legacy_tests/app_test_i2s_loopback/xk_216_mc/gpio_access.h

@@ -1,4 +1,5 @@
-// Copyright (c) 2016-2018, XMOS Ltd, All rights reserved
+// Copyright 2016-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 #ifndef __gpio_access_h__
 #define __gpio_access_h__
 

legacy_tests/app_test_i2s_loopback/xk_216_mc/xk-audio-216-mc.xn

@@ -83,10 +83,12 @@
     </Link>
   </Links>
   <ExternalDevices>
-    <Device NodeId="0" Tile="0" Class="SQIFlash" Name="bootFlash" Type="S25FL116K">
+    <Device NodeId="0" Tile="0" Class="SQIFlash" Name="bootFlash" Type="S25FL116K" PageSize="256" SectorSize="4096" NumPages="8192">
       <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"/>
+      <Attribute Name="QE_REGISTER" Value="flash_qe_location_status_reg_0"/>
+      <Attribute Name="QE_BIT" Value="flash_qe_bit_6"/>
     </Device>
   </ExternalDevices>
   <JTAGChain>

legacy_tests/app_test_i2s_loopback/xua_conf.h

@@ -1,9 +1,10 @@
-// Copyright (c) 2016-2018, XMOS Ltd, All rights reserved
+// Copyright 2016-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 #ifndef __custom_defines_h__
 #define __custom_defines_h__
 
 #define EXCLUDE_USB_AUDIO_MAIN
-#define NUM_PDM_MICS 0
+#define XUA_NUM_PDM_MICS 0
 #define XUD_TILE 1
 #define AUDIO_IO_TILE 0
 #define MIXER 0
@@ -22,5 +23,7 @@
 #define AUDIO_CLASS_FALLBACK 0
 #define BCD_DEVICE 0x1234
 #define XUA_DFU_EN          0
+#define MIC_DUAL_ENABLED 1        //Use single thread, dual PDM mic
+#define XUA_MIC_FRAME_SIZE 240
 
 #endif // __custom_defines_h__

legacy_tests/runtests.py

@@ -1,4 +1,6 @@
 #!/usr/bin/env python2.7
+# Copyright 2018-2021 XMOS LIMITED.
+# This Software is subject to the terms of the XMOS Public Licence: Version 1.
 import xmostest
 import os.path
 

legacy_tests/test_i2s_loopback.py

@@ -1,11 +1,13 @@
 #!/usr/bin/env python
+# Copyright 2018-2021 XMOS LIMITED.
+# This Software is subject to the terms of the XMOS Public Licence: Version 1.
 import xmostest
 
 def runtest_one_config(env, format, i2s_role, num_chans_in, num_chans_out, sample_rate):
     testlevel = 'smoke'
     resources = xmostest.request_resource('xsim')
 
-    binary = 'i2s_loopback/bin/{env}_{format}_{i2s_role}_{num_chans_in}in_{num_chans_out}out_{sample_rate}/i2s_loopback_{env}_{format}_{i2s_role}_{num_chans_in}in_{num_chans_out}out_{sample_rate}.xe'.format(env=env, format=format, i2s_role=i2s_role, num_chans_in=num_chans_in, num_chans_out=num_chans_out, sample_rate=sample_rate)
+    binary = 'app_test_i2s_loopback/bin/{env}_{format}_{i2s_role}_{num_chans_in}in_{num_chans_out}out_{sample_rate}/app_test_i2s_loopback_{env}_{format}_{i2s_role}_{num_chans_in}in_{num_chans_out}out_{sample_rate}.xe'.format(env=env, format=format, i2s_role=i2s_role, num_chans_in=num_chans_in, num_chans_out=num_chans_out, sample_rate=sample_rate)
     tester = xmostest.ComparisonTester(open('pass.expect'),
                                        'lib_xua',
                                        'i2s_loopback_sim_tests',

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/LICENSE.rst

@@ -0,0 +1,84 @@
+*******************************
+XMOS PUBLIC LICENCE: Version 1
+*******************************
+
+Subject to the conditions and limitations below, permission is hereby granted by XMOS LIMITED (“XMOS”), free of charge, to any person or entity obtaining a copy of the XMOS Software.
+
+**1. Definitions**
+
+**“Applicable Patent Rights”** means: (a) where XMOS is the grantor of the rights, (i) claims of patents that are now or in future owned by or assigned to XMOS and (ii) that cover subject matter contained in the Software, but only to the extent it is necessary to use, reproduce or distribute the Software without infringement; and (b) where you are the grantor of the rights, (i) claims of patents that are now or in future owned by or assigned to you and (ii) that cover the subject matter contained in your Derivatives, taken alone or in combination with the Software.
+
+**“Compiled Code”** means any compiled, binary, machine readable or executable version of the Source Code.
+
+**“Contributor”** means any person or entity that creates or contributes to the creation of Derivatives.
+
+**“Derivatives”** means any addition to, deletion from and/or change to the substance, structure of the Software, any previous Derivatives, the combination of the Derivatives and the Software and/or any respective portions thereof.
+
+**“Source Code”** means the human readable code that is suitable for making modifications but excluding any Compiled Code.
+
+**“Software”** means the software and associated documentation files which XMOS makes available and which contain a notice identifying the software as original XMOS software and referring to the software being subject to the terms of this XMOS Public Licence.
+
+This Licence refers to XMOS Software and does not relate to any XMOS hardware or devices which are protected by intellectual property rights (including patent and trade marks) which may be sold to you under a separate agreement.
+
+
+**2. Licence**
+
+**Permitted Uses, Conditions and Restrictions.**  Subject to the conditions below, XMOS grants you a worldwide, royalty free, non-exclusive licence, to the extent of any Patent Rights to do the following:
+
+2.1 **Unmodified Software.** You may use, copy, display, publish, distribute and make available unmodified copies of the Software:
+
+2.1.1 for personal or academic, non-commercial purposes; or
+
+2.1.2 for commercial purposes provided the Software is at all times used on a device designed, licensed or developed by XMOS and, provided that in each instance (2.1.1 and 2.1.2):
+
+(a) you must retain and reproduce in all copies of the Software the copyright and proprietary notices and disclaimers of XMOS as they appear in the Software, and keep intact all notices and disclaimers in the Software files that refer to this Licence; and
+
+(b) you must include a copy of this Licence with every copy of the Software and documentation you publish, distribute and make available and you may not offer or impose any terms on such Software that alter or restrict this Licence or the intent of such Licence, except as permitted below (Additional Terms).
+
+The licence above does not include any Compiled Code which XMOS may make available under a separate support and licence agreement.
+
+2.2 **Derivatives.** You may create and modify Derivatives and use, copy, display, publish, distribute and make available Derivatives:
+
+2.2.1 for personal or academic, non-commercial purposes; or
+
+2.2.2 for commercial purposes, provided the Derivatives are at all times used on a device designed, licensed or developed by XMOS and, provided that in each instance (2.2.1 and 2.2.2):
+
+(a) you must comply with the terms of clause 2.1 with respect to the Derivatives;
+
+(b) you must copy (to the extent it doesn’t already exist) the notice below in each file of the Derivatives, and ensure all the modified files carry prominent notices stating that you have changed the files and the date of any change; and
+
+(c) if you sublicence, distribute or otherwise make the Software and/or the Derivatives available for commercial purposes, you must provide that the Software and Derivatives are at all times used on a device designed, licensed or developed by XMOS.
+
+Without limitation to these terms and clause 3 below, the Source Code and Compiled Code to your Derivatives may at your discretion (but without obligation) be released, copied, displayed, published, distributed and made available; and if you elect to do so, it must be under the terms of this Licence including the terms of the licence at clauses 2.2.1, 2.2.2 and clause 3 below.
+
+2.3 **Distribution of Executable Versions.**  If you distribute or make available Derivatives, you must include a prominent notice in the code itself as well as in all related documentation, stating that the Source Code of the Software from which the Derivatives are based is available under the terms of this Licence, with information on how and where to obtain such Source Code.
+
+**3. Your Grant of Rights.**  In consideration and as a condition to this Licence, you grant to any person or entity receiving or distributing any Derivatives, a non-exclusive, royalty free, perpetual, irrevocable license under your Applicable Patent Rights and all other intellectual property rights owned or controlled by you, to use, copy, display, publish, distribute and make available your Derivatives of the same scope and extent as XMOS’s licence under clause 2.2 above.
+
+**4. Combined Products.**  You may create a combined product by combining Software, Derivatives and other code not covered by this Licence as a single application or product. In such instance, you must comply with the requirements of this Licence for any portion of the Software and/or Derivatives.
+
+**5. Additional Terms.**  You may choose to offer, and to charge a fee for, warranty, support, indemnity or liability obligations and/or other rights consistent with the term of this Licence (“Additional Terms”) to any legitimate recipients of the Software and/or Derivatives.  The terms on which you provide such Additional Terms are on your sole responsibility and you shall indemnify, defend and hold XMOS harmless against any claims asserted against XMOS.
+
+**6. New Versions.**  XMOS may publish revised and/or new versions of this Licence from time to time to accommodate changes to the Licence terms, new versions, updates and bug fixes of the Software.  Each version will be given a distinguishing version number.  Once Software has been published under a particular version of this Licence, you may continue to use it under the terms of that version.  You may also choose to use the latest version of the Software under any subsequent version published by XMOS.  Only XMOS shall have the right to modify these terms.
+
+**7. IPR and Ownership**
+Any rights, including all intellectual property rights and all trademarks not expressly granted herein are reserved in full by the authors or copyright holders. Any requests for additional permissions by XMOS including any rights to use XMOS trademarks, should be made (without obligation) to XMOS at **support@xmos.com**
+
+Nothing herein shall limit any rights that XMOS is otherwise entitled to under the doctrines of patent exhaustion, implied license, or legal estoppel.  Neither the name of the authors, the copyright holders or any contributors may be used to endorse or promote any Derivatives from this Software without specific written permission.  Any attempt to deal with the Software which does not comply with this Licence shall be void and shall automatically terminate any rights granted under this licence (including any licence of any intellectual property rights granted herein).
+Subject to the licences granted under this Licence any Contributor retains all rights, title and interest in and to any Derivatives made by Contributor subject to the underlying rights of XMOS in the Software.  XMOS shall retain all rights, title and interest in the Software and any Derivatives made by XMOS (“XMOS Derivatives”).  XMOS Derivatives will not automatically be subject to this Licence and XMOS shall be entitled to licence such rights on any terms (without obligation) as it sees fit.
+
+**8. Termination**
+
+8.1 This Licence will automatically terminate immediately, without notice to you, if:
+
+(a) you fail to comply with the terms of this Licence; and/or
+
+(b) you directly or indirectly commence any action for patent or intellectual property right infringement against XMOS, or any parent, group, affiliate or subsidiary of XMOS; provided XMOS did not first commence an action or patent infringement against you in that instance; and/or
+
+(c) the terms of this Licence are held by any court of competent jurisdiction to be unenforceable in whole or in part.
+
+**9. Critical Applications.**  Unless XMOS has agreed in writing with you an agreement specifically governing use of the Goods in military, aerospace, automotive or medically related functions (collectively and individually hereinafter referred to as "Special Use"), any permitted use of the Software excludes Special Use. Notwithstanding any agreement between XMOS and you for Special Use, Special Use shall be at your own risk, and you shall fully indemnify XMOS against any damages, losses, costs and claims (direct and indirect) arising out of any Special Use.
+
+**10. NO WARRANTY OR SUPPORT.**  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL XMOS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, WARRANTY, CIVIL TORT (INCLUDING NEGLIGENCE), PRODUCTS LIABILITY OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE INCLUDING GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES EVEN IF SUCH PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES AND NOT WITHSTANDING THE FAILURE OF ESSENTIAL PURPOSE.  IN SOME JURISDICTIONS PARTIES ARE UNABLE TO LIMIT LIABILTY IN THIS WAY, IF THIS APPLIES TO YOUR JURISDICTION THIS LIABILITY CLAUSE ABOVE MAY NOT APPLY.  NOTWITHSTANDING THE ABOVE, IN NO EVENT SHALL XMOS’s TOTAL LIABILITY TO YOU FOR ALL DAMAGES, LOSS OR OTHERWISE EXCEED $50.
+
+**11. Governing Law and Jurisdiction.**  This Licence constitutes the entire agreement between the parties with respect to the subject matter hereof. The Licence shall be governed by the laws of England and the conflict of laws and UN Convention on Contracts for the International Sale of Goods, shall not apply.

lib_xua/LICENSE.txt

@@ -1,135 +0,0 @@
-Software Release License Agreement
-
-Copyright (c) 2017-2018, 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 lib_xua software

lib_xua/api/xua.h

@@ -1,4 +1,5 @@
-// Copyright (c) 2017-2018, XMOS Ltd, All rights reserved
+// Copyright 2017-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 
 #ifndef __XUA_H__
 #define __XUA_H__
@@ -6,13 +7,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

@@ -1,12 +1,14 @@
-// Copyright (c) 2011-2018, XMOS Ltd, All rights reserved
+// Copyright 2011-2022 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 #ifndef __XUA_AUDIOHUB_H__
 #define __XUA_AUDIOHUB_H__
 
 #if __XC__
 
 #include "xccompat.h"
+#include "xs1.h"
 
-#ifndef NO_USB
+#if XUA_USB_EN
 #include "dfu_interface.h"
 #endif
 
@@ -15,24 +17,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,5 @@
-// Copyright (c) 2011-2018, XMOS Ltd, All rights reserved
+// Copyright 2011-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 #ifndef __XUA_BUFFER_H__
 #define __XUA_BUFFER_H__
 
@@ -51,14 +52,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 +91,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,5 @@
-// Copyright (c) 2011-2018, XMOS Ltd, All rights reserved
+// Copyright 2011-2022 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 /*
  * @brief       Defines relating to device configuration and customisation of lib_xua
  * @author      Ross Owen, XMOS Limited
@@ -56,6 +57,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)
  */
@@ -75,7 +83,7 @@
 /**
  * @brief Number of DSD output channels. Default: 0 (disabled)
  */
-#if defined(DSD_CHANS_DAC)
+#if defined(DSD_CHANS_DAC) && (DSD_CHANS_DAC != 0)
     #if defined(NATIVE_DSD) && (NATIVE_DSD == 0)
         #undef NATIVE_DSD
     #else
@@ -235,10 +243,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 +251,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 +261,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 +275,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 +358,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 +365,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 +384,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 +395,7 @@
 #endif
 #endif
 
-#ifdef ADAT_RX
+#if ADAT_RX
 
 /* Setup input stream formats for ADAT */
 #if(MAX_FREQ > 96000)
@@ -431,10 +433,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 +443,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 +508,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
@@ -519,21 +527,21 @@
  * @brief Device firmware version number in Binary Coded Decimal format: 0xJJMN where JJ: major, M: minor, N: sub-minor version number.
  */
 #ifndef BCD_DEVICE_J
-#define BCD_DEVICE_J             (0)
+#define BCD_DEVICE_J             (1)
 #endif
 
 /**
  * @brief Device firmware version number in Binary Coded Decimal format: 0xJJMN where JJ: major, M: minor, N: sub-minor version number.
  */
 #ifndef BCD_DEVICE_M
-#define BCD_DEVICE_M             (1)
+#define BCD_DEVICE_M             (2)
 #endif
 
 /**
  * @brief Device firmware version number in Binary Coded Decimal format: 0xJJMN where JJ: major, M: minor, N: sub-minor version number.
  */
 #ifndef BCD_DEVICE_N
-#define BCD_DEVICE_N             (1)       
+#define BCD_DEVICE_N             (0)
 #endif
 
 /**
@@ -1132,38 +1140,15 @@
 #endif
 #endif
 
-/* IAP */
-#if defined(IAP) && (IAP == 0)
-#undef IAP
+/* Always enable explicit feedback EP, even when input stream is present */
+#ifndef UAC_FORCE_FEEDBACK_EP
+#define UAC_FORCE_FEEDBACK_EP       (1)
 #endif
 
-/* IAP Interrupt endpoint */
-#if defined(IAP_INT_EP) && (IAP_INT_EP == 0)
-#undef IAP_INT_EP
+#if (defined(UAC_FORCE_FEEDBACK_EP) && UAC_FORCE_FEEDBACK_EP == 0)
+#undef UAC_FORCE_FEEDBACK_EP
 #endif
 
-/* IAP EA Native Transport */
-#if defined(IAP_EA_NATIVE_TRANS) && (IAP_EA_NATIVE_TRANS == 0)
-#undef IAP_EA_NATIVE_TRANS
-#endif
-
-#if defined(IAP_EA_NATIVE_TRANS) || defined(__DOXYGEN__)
-/**
- * @brief Number of supported EA Native Interface Alternative settings.
- *
- * Only 1 supported
- */
-#ifndef IAP_EA_NATIVE_TRANS_ALT_COUNT
-    #define IAP_EA_NATIVE_TRANS_ALT_COUNT 1
-#endif
-
-#if (IAP_EA_NATIVE_TRANS_ALT_COUNT > 1)
-    /* Only 1 supported */
-    #error
-#endif
-#endif
-
-
 #ifndef __ASSEMBLER__
 /* Endpoint addresses enums */
 enum USBEndpointNumber_In
@@ -1173,13 +1158,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
@@ -1216,7 +1201,7 @@ enum USBEndpointNumber_Out
 #endif
 
 #ifndef XUA_ENDPOINT_COUNT_CUSTOM_IN
-#define XUA_ENDPOINT_COUNT_CUSTOM_IN   0 
+#define XUA_ENDPOINT_COUNT_CUSTOM_IN   0
 #endif
 
 #define ENDPOINT_COUNT_IN  (XUA_ENDPOINT_COUNT_IN + XUA_ENDPOINT_COUNT_CUSTOM_IN)
@@ -1232,10 +1217,6 @@ enum USBEndpointNumber_Out
 
 #define MAX_VOL                  (0x20000000)
 
-#if defined(SU1_ADC_ENABLE) && (SU1_ADC_ENABLE == 0)
-#undef SU1_ADC_ENABLE
-#endif
-
 #if defined(LEVEL_METER_LEDS) && !defined(LEVEL_UPDATE_RATE)
 #define LEVEL_UPDATE_RATE   400000
 #endif
@@ -1251,9 +1232,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 +1425,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 +1442,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

@@ -1,4 +1,5 @@
-// Copyright (c) 2017-2018, XMOS Ltd, All rights reserved
+// Copyright 2017-2022 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 #ifndef __XUA_CONF_FULL_H__
 #define __XUA_CONF_FULL_H__
 

lib_xua/api/xua_endpoint0.h

@@ -1,4 +1,5 @@
-// Copyright (c) 2011-2018, XMOS Ltd, All rights reserved
+// Copyright 2011-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 
 #ifndef _XUA_ENDPOINT0_H_
 #define _XUA_ENDPOINT0_H_
@@ -14,7 +15,10 @@
  *  \param c_ep0_out Chanend connected to the XUD_Manager() out endpoint array
  *  \param c_ep0_in Chanend connected to the XUD_Manager() in endpoint array
  *  \param c_audioCtrl Chanend connected to the decouple thread for control
- *                     audio (sample rate changes etc.)
+ *                     audio (sample rate changes etc.). Note when nulled, the
+ *                    audio device only supports single sample rate/format and
+ *                    DFU is not supported either since this channel is used
+ *                    to carry messages about format, rate and DFU state
  *  \param c_mix_ctl Optional chanend to be connected to the mixer thread if
  *                   present
  *  \param c_clk_ctl Optional chanend to be connected to the clockgen thread if
@@ -24,9 +28,109 @@
  *  \param c_EANativeTransport_ctrl Optional chanend to be connected to EA Native
  *                                  endpoint manager if present
  */
-void XUA_Endpoint0(chanend c_ep0_out, chanend c_ep0_in, chanend c_audioCtrl,
+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,16 @@
-// Copyright (c) 2015-2018, XMOS Ltd, All rights reserved
+// Copyright 2015-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
 
+#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 +21,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 +31,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 +42,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,19 @@
+// Copyright 2017-2021 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
+
+#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|
+