diff --git a/examples/AN00246_xua_example/Makefile b/examples/AN00246_xua_example/Makefile index 2c747be0..052dcdd3 100644 --- a/examples/AN00246_xua_example/Makefile +++ b/examples/AN00246_xua_example/Makefile @@ -3,13 +3,14 @@ APP_NAME = app_xua_simple TARGET = xk-audio-216-mc.xn # The flags passed to xcc when building the application -XCC_FLAGS = -fcomment-asm -Xmapper --map -Xmapper MAPFILE -O3 -report -fsubword-select -save-temps -g -Wno-unused-function -Wno-timing -DXUD_SERIES_SUPPORT=XUD_X200_SERIES -DUSB_TILE=tile[1] -DSDA_HIGH=2 -DSCL_HIGH=1 +XCC_FLAGS = -fcomment-asm -Xmapper --map -Xmapper MAPFILE -O3 -report -fsubword-select -save-temps \ + -g -Wno-unused-function -Wno-timing -DXUD_SERIES_SUPPORT=XUD_X200_SERIES -DUSB_TILE=tile[1] \ + -DSDA_HIGH=2 -DSCL_HIGH=1 # 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_mic_array lib_logging lib_xua lib_device_control lib_xud module_i2c_shared module_i2c_single_port module_locks - +USED_MODULES = lib_xua lib_device_control lib_xud module_i2c_shared module_i2c_single_port module_locks #============================================================================= # The following part of the Makefile includes the common build infrastructure diff --git a/examples/AN00246_xua_example/README.rst b/examples/AN00246_xua_example/README.rst new file mode 100644 index 00000000..125adb13 --- /dev/null +++ b/examples/AN00246_xua_example/README.rst @@ -0,0 +1,34 @@ + +How to use the lib_xua_library +=============================== + +.. version:: 0.1.0 + +Summary +------- + +Required tools and libraries +............................ + +.. appdeps:: + +Required hardware +................. + +The example code provided with the application has been implemented +and tested on the xCORE-200 Multi-channel Audio Board + +Prerequisites +............. + + * This document assumes familiarity with the XMOS xCORE architecture, + the XMOS tool chain and the xC language. Documentation related to these + aspects which are not specific to this application note are linked to in + the references appendix. + + * For a description of XMOS related terms found in this document + please see the XMOS Glossary [#]_. + +.. [#] http://www.xmos.com/published/glossary + + diff --git a/examples/AN00246_xua_example/doc/AN00246.rst b/examples/AN00246_xua_example/doc/AN00246.rst new file mode 100644 index 00000000..89267983 --- /dev/null +++ b/examples/AN00246_xua_example/doc/AN00246.rst @@ -0,0 +1,240 @@ +.. 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 new file mode 100644 index 00000000..1c5b9ab9 --- /dev/null +++ b/examples/AN00246_xua_example/doc/rst/AN00246.rst @@ -0,0 +1,229 @@ +.. 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 +............. + +|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/images/hw_setup.jpg b/examples/AN00246_xua_example/doc/rst/images/hw_setup.jpg new file mode 100644 index 00000000..8998805d Binary files /dev/null and b/examples/AN00246_xua_example/doc/rst/images/hw_setup.jpg differ diff --git a/examples/AN00246_xua_example/doc/rst/xdoc.conf b/examples/AN00246_xua_example/doc/rst/xdoc.conf new file mode 100644 index 00000000..37460abf --- /dev/null +++ b/examples/AN00246_xua_example/doc/rst/xdoc.conf @@ -0,0 +1,2 @@ +XMOSNEWSTYLE=1 +SOURCE_INCLUDE_DIRS=../../src \ No newline at end of file diff --git a/examples/AN00246_xua_example/src/app_xua_simple.xc b/examples/AN00246_xua_example/src/app_xua_simple.xc index 86476ea7..cfcb122c 100644 --- a/examples/AN00246_xua_example/src/app_xua_simple.xc +++ b/examples/AN00246_xua_example/src/app_xua_simple.xc @@ -13,8 +13,8 @@ #include #include -#include "xud_device.h" #include "xua.h" +#include "xud_device.h" /* Port declarations. Note, the defines come from the xn file */ buffered out port:32 p_i2s_dac[] = {PORT_I2S_DAC0}; /* I2S Data-line(s) */ @@ -24,12 +24,12 @@ buffered out port:32 p_bclk = PORT_I2S_BCLK; /* I2S L/R-clock */ /* Note, declared unsafe as sometimes we want to share this port e.g. PDM mics and I2S use same master clock IO */ -port p_mclk_in_ = PORT_MCLK_IN; +port p_mclk_in_ = PORT_MCLK_IN; unsafe { /* TODO simplify this */ - unsafe port p_mclk_in; /* Audio master clock input */ + unsafe port p_mclk_in; /* Audio master clock input */ } in port p_for_mclk_count = PORT_MCLK_COUNT; /* Extra port for counting master clock ticks */ @@ -55,7 +55,7 @@ int main() /* Channel for audio data between buffering cores and audio IO core */ chan c_aud; - /* Channel for communcating control messages from EP0 to the rest of the device (via the buffering cores */ + /* Channel for communicating control messages from EP0 to the rest of the device (via the buffering cores */ chan c_aud_ctl; par @@ -63,7 +63,6 @@ int main() /* Low level USB device layer core */ on tile[1]: XUD_Main(c_ep_out, 2, c_ep_in, 2, c_sof, epTypeTableOut, epTypeTableIn, - /* TODO rm me! */ null, null, -1 , XUD_SPEED_HS, XUD_PWR_BUS); diff --git a/examples/AN00246_xua_example/src/xua_conf.h b/examples/AN00246_xua_example/src/xua_conf.h index 7d684fcf..63120c11 100644 --- a/examples/AN00246_xua_example/src/xua_conf.h +++ b/examples/AN00246_xua_example/src/xua_conf.h @@ -10,10 +10,6 @@ #define MAX_FREQ 48000 #define EXCLUDE_USB_AUDIO_MAIN -#define NUM_PDM_MICS 0 -#define XUD_TILE 1 -#define AUDIO_IO_TILE 0 -#define MIXER 0 #define SPDIF_TX_INDEX 0 #define VENDOR_STR "XMOS" @@ -26,6 +22,3 @@ #define AUDIO_CLASS_FALLBACK 0 #define BCD_DEVICE 0x1234 #define XUA_DFU_EN 0 - -/* TODO */ -#define XUA_DFU XUA_DFU_EN