.. include:: ../../README.rst

|newpage|

Overview
--------

Introduction
............

The XMOS USB Audio (XUA) library provides an implemention of USB Audio Class 2.0 

This application note demonstrates the implementation of a basic USB Audio Device on 
the xCORE-200 MC Audio board.

Block diagram
.............

.. figure:: images/block_diagram.*
   :width: 80%

   Application block diagram

How to use lib_xua
------------------

The Makefile
............

To start using the 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 most basic implementation of a USB Audio device (i.e. simple stereo input and output via I2S)
using ``lib_xua`` requires the follow pins:

    - I2S Bit Clock (from xCORE to DAC)
    - I2S L/R clock (from xCORE to DAC)
    - I2S Data line (from xCORE to DAC)
    - I2S Data line (from ADC to xCORE)
    - Audio Master clock (from clock source to xCORE)

.. note::

    ANOO246 assumes xCORE is I2S bus master

On an xCORE the pins are controlled by ``ports``. The application therefore declares various ``ports``
for this purpose:

.. literalinclude:: app_xua_simple.xc
   :start-on: /* Port declaration
   :end-on: /* Clock-block

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

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 be declared":

.. literalinclude:: app_xua_simple.xc
   :start-on: /* Channels for lib_xud
   :end-on: /* chan c_aud_ctl

The rest of the ``main()`` function starts all the tasks in parallel
using the xC ``par`` construct:

.. literalinclude:: app_xua_simple.xc
   :start-on: par
   :end-before: return 0

This code starts the low-level USB task, an Endpoint 0 task, an Audio buffering task and a task to handle 
the audio I/O (i.e. I2S signalling).

Configuration 
.............

|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|
