Added start of AN00248

examples/AN00248_xua_example_pdm_mics/doc/rst/AN00248.rst

@@ -0,0 +1,279 @@
+.. 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 than recording 
+from PDM microphones (i.e. no I2S and the on board DAC is not configured. 
+
+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`` 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 also includes::
+
+  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 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
+-------------------
+
+S/PDIF Tx functionality must be  ``lib_xua`` 
+
+``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 funtionality ``XUA_SPDIF_TX_EN`` must be set to a non-zero value.
+
+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/AN00248_xua_example_pdm_mics/doc/rst/xdoc.conf

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