Updates to AN00247

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

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

examples/AN00247_xua_example_spdif_tx/doc/AN00246.rst

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

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``
+On an xCORE the pins are controlled by ``ports``. The application therefore declares a 
-for this purpose:
+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|

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) */