diff --git a/examples/AN00247_xua_example_spdif_tx/LICENSE.txt b/examples/AN00247_xua_example_spdif_tx/LICENSE.txt index 844e2bcc..236b6d1a 100644 --- a/examples/AN00247_xua_example_spdif_tx/LICENSE.txt +++ b/examples/AN00247_xua_example_spdif_tx/LICENSE.txt @@ -132,4 +132,4 @@ This License shall be governed by and construed in accordance with English law a This License has been entered into on the date stated at the beginning of it. Schedule -XMOS lib_xua software +XMOS application note AN00247 software diff --git a/examples/AN00247_xua_example_spdif_tx/Makefile b/examples/AN00247_xua_example_spdif_tx/Makefile index a6733f6d..cedcb1c7 100644 --- a/examples/AN00247_xua_example_spdif_tx/Makefile +++ b/examples/AN00247_xua_example_spdif_tx/Makefile @@ -10,7 +10,7 @@ XCC_FLAGS = -fcomment-asm -Xmapper --map -Xmapper MAPFILE -O3 -report -fsubword- # 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_spdif 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 diff --git a/examples/AN00247_xua_example_spdif_tx/doc/AN00246.rst b/examples/AN00247_xua_example_spdif_tx/doc/AN00246.rst deleted file mode 100644 index 89267983..00000000 --- a/examples/AN00247_xua_example_spdif_tx/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/AN00247_xua_example_spdif_tx/doc/rst/AN00247.rst b/examples/AN00247_xua_example_spdif_tx/doc/rst/AN00247.rst index 50cd9292..03072a28 100644 --- a/examples/AN00247_xua_example_spdif_tx/doc/rst/AN00247.rst +++ b/examples/AN00247_xua_example_spdif_tx/doc/rst/AN00247.rst @@ -8,28 +8,18 @@ Overview Introduction ............ -The XMOS USB Audio (XUA) library provides an implemention of USB Audio Class 2.0. +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 +note. -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`` and ``lib_spdif`` to your Makefile:: @@ -50,7 +40,7 @@ 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: @@ -67,32 +57,49 @@ be included in your code to use the library. :end-on: include "xud_device.h" The application uses the S/PDIF transmitter from ``lib_spdif``. This header -must be inluced in your code to the library. +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 most basic implementation of a USB Audio device with no I2S functionalilty. +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 various ``ports`` -for this purpose: +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: /* Clock-block + :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 with 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 + :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 ........................................... @@ -101,15 +108,21 @@ 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 + :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 -This port must be clocked from the audio master clock. 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()``). +``lib_xud`` and the calling the main XUD function in a par (``XUD_Main()``). For a simple application the following endpoints are required: @@ -120,19 +133,20 @@ These are declared as follows: .. literalinclude:: app_xua_simple.xc :start-on: /* Endpoint type tables - :end-on: /* XUD_EpType epTypeTableIn + :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": +These must firs be declared: .. literalinclude:: app_xua_simple.xc :start-on: /* Channels for lib_xud - :end-on: /* chan c_aud_ctl + :end-on: chan c_spdif_tx The rest of the ``main()`` function starts all the tasks in parallel using the xC ``par`` construct: @@ -145,8 +159,8 @@ This code starts the low-level USB task, an Endpoint 0 task, an Audio buffering 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. -Configuration -............. +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| diff --git a/examples/AN00247_xua_example_spdif_tx/src/app_xua_simple.xc b/examples/AN00247_xua_example_spdif_tx/src/app_xua_simple.xc index 0f237761..17723ded 100644 --- a/examples/AN00247_xua_example_spdif_tx/src/app_xua_simple.xc +++ b/examples/AN00247_xua_example_spdif_tx/src/app_xua_simple.xc @@ -19,7 +19,9 @@ #include "spdif.h" /* Lib_spdif port declarations. Note, the defines come from the xn file */ -buffered out port:32 p_spdif_tx2 = PORT_SPDIF_OUT; /* SPDIF transmit port */ +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 */ @@ -80,14 +82,14 @@ int main() 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_tx2, clk_audio_mclk, p_mclk_in, 7); + 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_tx2, c_spdif_tx); + 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) */