From 6ee02cbfe2c475fac3e14259972dddec6070d07a Mon Sep 17 00:00:00 2001 From: xross Date: Thu, 29 Mar 2018 17:52:24 +0100 Subject: [PATCH] Application note tidy and build fixes --- examples/AN00246_xua_example/doc/AN00246.rst | 240 ------------------ .../AN00246_xua_example/doc/rst/AN00246.rst | 67 +++-- .../AN00246_xua_example/src/app_xua_simple.xc | 2 +- examples/AN00246_xua_example/src/xua_conf.h | 34 ++- .../doc/rst/AN00247.rst | 8 +- 5 files changed, 65 insertions(+), 286 deletions(-) delete mode 100644 examples/AN00246_xua_example/doc/AN00246.rst 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 7cf7df51..9627120a 100644 --- a/examples/AN00246_xua_example/doc/rst/AN00246.rst +++ b/examples/AN00246_xua_example/doc/rst/AN00246.rst @@ -8,26 +8,16 @@ 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 on the xCORE-200 MC Audio board. -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`` to your Makefile:: +To start using ``lib_xua``, you need to add ``lib_xua`` to your Makefile:: USED_MODULES = .. lib_xua ... @@ -65,7 +55,7 @@ be included in your code to use the library. Allocating hardware resources ............................. -A most basic implementation of a USB Audio device (i.e. simple stereo input and output via I2S) +A 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) @@ -76,20 +66,34 @@ using ``lib_xua`` requires the follow pins: .. note:: - ANOO246 assumes xCORE is I2S bus master + This application note 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 + :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 on 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. + Other declarations .................. @@ -106,21 +110,21 @@ 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 first be declared: .. literalinclude:: app_xua_simple.xc :start-on: /* Channels for lib_xud - :end-on: /* chan c_aud_ctl + :end-on: chan c_aud_ctl -The rest of the ``main()`` function starts all the tasks in parallel +The rest of the ``main()`` function starts all of the tasks in parallel using the xC ``par`` construct: .. literalinclude:: app_xua_simple.xc @@ -133,6 +137,25 @@ 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. For this simple application the contents +of this file might look something like the following: + +.. literalinclude:: xua_conf.h + :start-on: // Copyright + :end-on: #endif + +Some items have sensible default values, items like strings and sample rates for example. However, some items are specific to a hardware +implentation e.g. master clock frequencies and must be defined. Please see the ``lib_xua`` library documentation for full details. + |appendix| |newpage| diff --git a/examples/AN00246_xua_example/src/app_xua_simple.xc b/examples/AN00246_xua_example/src/app_xua_simple.xc index d9bf6ea7..e53f0778 100644 --- a/examples/AN00246_xua_example/src/app_xua_simple.xc +++ b/examples/AN00246_xua_example/src/app_xua_simple.xc @@ -80,7 +80,7 @@ int main() } /* AudioHub/IO core does most of the audio IO i.e. I2S (also serves as a hub for all audio) */ - on tile[0]: XUA_AudioHub(c_aud, clk_audio_mclk, clk_audio_bclk, p_mclk_in, p_lrclk, p_bclk); + on tile[0]: XUA_AudioHub(c_aud, clk_audio_mclk, clk_audio_bclk, p_mclk_in, p_lrclk, p_bclk, p_i2s_dac, p_i2s_adc); } return 0; diff --git a/examples/AN00246_xua_example/src/xua_conf.h b/examples/AN00246_xua_example/src/xua_conf.h index cfeb229e..d879e272 100644 --- a/examples/AN00246_xua_example/src/xua_conf.h +++ b/examples/AN00246_xua_example/src/xua_conf.h @@ -3,27 +3,23 @@ #ifndef _XUA_CONF_H_ #define _XUA_CONF_H_ -#define NUM_USB_CHAN_OUT 2 -#define NUM_USB_CHAN_IN 2 -#define I2S_CHANS_DAC 2 -#define I2S_CHANS_ADC 2 -#define MCLK_441 (512 * 44100) -#define MCLK_48 (512 * 48000) -#define MIN_FREQ 48000 -#define MAX_FREQ 48000 +#define NUM_USB_CHAN_OUT 2 /* Number of channels from host to device */ +#define NUM_USB_CHAN_IN 2 /* Number of channels from device to host */ +#define I2S_CHANS_DAC 2 /* Number of I2S channels out of xCORE */ +#define I2S_CHANS_ADC 2 /* Number of I2S channels in to xCORE */ +#define MCLK_441 (512 * 44100) /* 44.1kHz family master clock frequency */ +#define MCLK_48 (512 * 48000) /* 48kHz family master clock frequency */ +#define MIN_FREQ 48000 /* Minimum sample rate */ +#define MAX_FREQ 48000 /* Maximum sample rate */ #define EXCLUDE_USB_AUDIO_MAIN -#define SPDIF_TX_INDEX 0 -#define VENDOR_STR "XMOS" -#define VENDOR_ID 0x20B1 -#define PRODUCT_STR_A2 "XUA Example" -#define PRODUCT_STR_A1 "XUA Example" -#define PID_AUDIO_1 1 -#define PID_AUDIO_2 2 -#define AUDIO_CLASS 2 -#define AUDIO_CLASS_FALLBACK 0 -#define BCD_DEVICE 0x1234 -#define XUA_DFU_EN 0 +#define VENDOR_STR "XMOS" +#define VENDOR_ID 0x20B1 +#define PRODUCT_STR_A2 "XUA Example" +#define PRODUCT_STR_A1 "XUA Example" +#define PID_AUDIO_1 1 +#define PID_AUDIO_2 2 +#define XUA_DFU_EN 0 /* Disable DFU (for simplicity of example */ #endif 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 03072a28..e0929818 100644 --- a/examples/AN00247_xua_example_spdif_tx/doc/rst/AN00247.rst +++ b/examples/AN00247_xua_example_spdif_tx/doc/rst/AN00247.rst @@ -21,7 +21,7 @@ note. The Makefile ------------ -To start using the lib_xua, you need to add ``lib_xua`` and ``lib_spdif`` to your Makefile:: +To start using ``lib_xua``, you need to add ``lib_xua`` and ``lib_spdif`` to your Makefile:: USED_MODULES = .. lib_xua lib_spdif ... @@ -83,7 +83,7 @@ port for the master clock input signal. ``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. +clock is required since USB and S/PDIF do not reside of the same tiles on the example hardware. These ports are declared as follows: @@ -142,13 +142,13 @@ 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 firs be declared: +These must first be declared: .. literalinclude:: app_xua_simple.xc :start-on: /* Channels for lib_xud :end-on: chan c_spdif_tx -The rest of the ``main()`` function starts all the tasks in parallel +The rest of the ``main()`` function starts all of the tasks in parallel using the xC ``par`` construct: .. literalinclude:: app_xua_simple.xc