diff --git a/examples/AN00246_xua_example/doc/.gitignore b/examples/AN00246_xua_example/doc/.gitignore new file mode 100644 index 00000000..9ac96638 --- /dev/null +++ b/examples/AN00246_xua_example/doc/.gitignore @@ -0,0 +1,2 @@ +rst/_build +pdf diff --git a/examples/AN00246_xua_example/doc/AN00246.rst b/examples/AN00246_xua_example/doc/AN00246.rst deleted file mode 100644 index 89267983..00000000 --- a/examples/AN00246_xua_example/doc/AN00246.rst +++ /dev/null @@ -1,240 +0,0 @@ -.. 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 - -The application uses a single logical core which runs the application and makes -calls to the |I2C| master library functions as required. - -How to use lib_xua ------------------- - -The Makefile -............ - -To start using the lib_xua, you need to add ``lib_xua`` to your Makefile:: - - 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 - :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 -............. - -``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. - -|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| diff --git a/examples/AN00246_xua_example/doc/rst/AN00246.rst b/examples/AN00246_xua_example/doc/rst/AN00246.rst index 1c5b9ab9..79f46436 100644 --- a/examples/AN00246_xua_example/doc/rst/AN00246.rst +++ b/examples/AN00246_xua_example/doc/rst/AN00246.rst @@ -1,4 +1,5 @@ .. include:: ../../README.rst +.. |I2C| replace:: I\ :sup:`2`\ C |newpage| @@ -136,6 +137,17 @@ 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. + |appendix| |newpage|