forked from PAWPAW-Mirror/lib_xua
AN00246: Fix xdoc build
This commit is contained in:
Larry Snizek
2
examples/AN00246_xua_example/doc/.gitignore
vendored
Normal file
2
examples/AN00246_xua_example/doc/.gitignore
vendored
Normal file
@@ -0,0 +1,2 @@
|
||||
rst/_build
|
||||
pdf
|
||||
@@ -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 <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
|
||||
.............
|
||||
|
||||
``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|
|
||||
@@ -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|
|
||||
|
||||
|
||||
Reference in New Issue
Block a user