Updates to AN00247

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|