diff --git a/examples/AN00246_xua_example/doc/rst/AN00246.rst b/examples/AN00246_xua_example/doc/rst/AN00246.rst index 1c5b9ab9..7cf7df51 100644 --- a/examples/AN00246_xua_example/doc/rst/AN00246.rst +++ b/examples/AN00246_xua_example/doc/rst/AN00246.rst @@ -21,9 +21,6 @@ Block diagram 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 ------------------ diff --git a/examples/AN00247_xua_example_spdif_tx/LICENSE.txt b/examples/AN00247_xua_example_spdif_tx/LICENSE.txt new file mode 100644 index 00000000..844e2bcc --- /dev/null +++ b/examples/AN00247_xua_example_spdif_tx/LICENSE.txt @@ -0,0 +1,135 @@ +Software Release License Agreement + +Copyright (c) 2018, XMOS, All rights reserved. + +BY ACCESSING, USING, INSTALLING OR DOWNLOADING THE XMOS SOFTWARE, YOU AGREE TO BE BOUND BY THE FOLLOWING TERMS. IF YOU DO NOT AGREE TO THESE, DO NOT ATTEMPT TO DOWNLOAD, ACCESS OR USE THE XMOS Software. + +Parties: + +(1) XMOS Limited, incorporated and registered in England and Wales with company number 5494985 whose registered office is 107 Cheapside, London, EC2V 6DN (XMOS). + +(2) An individual or legal entity exercising permissions granted by this License (Customer). + +If you are entering into this Agreement on behalf of another legal entity such as a company, partnership, university, college etc. (for example, as an employee, student or consultant), you warrant that you have authority to bind that entity. + +1. Definitions + +"License" means this Software License and any schedules or annexes to it. + +"License Fee" means the fee for the XMOS Software as detailed in any schedules or annexes to this Software License + +"Licensee Modifications" means all developments and modifications of the XMOS Software developed independently by the Customer. + +"XMOS Modifications" means all developments and modifications of the XMOS Software developed or co-developed by XMOS. + +"XMOS Hardware" means any XMOS hardware devices supplied by XMOS from time to time and/or the particular XMOS devices detailed in any schedules or annexes to this Software License. + +"XMOS Software" comprises the XMOS owned circuit designs, schematics, source code, object code, reference designs, (including related programmer comments and documentation, if any), error corrections, improvements, modifications (including XMOS Modifications) and updates. + +The headings in this License do not affect its interpretation. Save where the context otherwise requires, references to clauses and schedules are to clauses and schedules of this License. + +Unless the context otherwise requires: + +- references to XMOS and the Customer include their permitted successors and assigns; +- references to statutory provisions include those statutory provisions as amended or re-enacted; and +- references to any gender include all genders. + +Words in the singular include the plural and in the plural include the singular. + +2. License + +XMOS grants the Customer a non-exclusive license to use, develop, modify and distribute the XMOS Software with, or for the purpose of being used with, XMOS Hardware. + +Open Source Software (OSS) must be used and dealt with in accordance with any license terms under which OSS is distributed. + +3. Consideration + +In consideration of the mutual obligations contained in this License, the parties agree to its terms. + +4. Term + +Subject to clause 12 below, this License shall be perpetual. + +5. Restrictions on Use + +The Customer will adhere to all applicable import and export laws and regulations of the country in which it resides and of the United States and United Kingdom, without limitation. The Customer agrees that it is its responsibility to obtain copies of and to familiarise itself fully with these laws and regulations to avoid violation. + +6. Modifications + +The Customer will own all intellectual property rights in the Licensee Modifications but will undertake to provide XMOS with any fixes made to correct any bugs found in the XMOS Software on a non-exclusive, perpetual and royalty free license basis. + +XMOS will own all intellectual property rights in the XMOS Modifications. +The Customer may only use the Licensee Modifications and XMOS Modifications on, or in relation to, XMOS Hardware. + +7. Support + +Support of the XMOS Software may be provided by XMOS pursuant to a separate support agreement. + +8. Warranty and Disclaimer + +The XMOS Software is provided "AS IS" without a warranty of any kind. XMOS and its licensors' entire liability and Customer's exclusive remedy under this warranty to be determined in XMOS's sole and absolute discretion, will be either (a) the corrections of defects in media or replacement of the media, or (b) the refund of the license fee paid (if any). + +Whilst XMOS gives the Customer the ability to load their own software and applications onto XMOS devices, the security of such software and applications when on the XMOS devices is the Customer's own responsibility and any breach of security shall not be deemed a defect or failure of the hardware. XMOS shall have no liability whatsoever in relation to any costs, damages or other losses Customer may incur as a result of any breaches of security in relation to your software or applications. + +XMOS AND ITS LICENSORS DISCLAIM ALL OTHER WARRANTIES, EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY/ SATISFACTORY QUALITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT EXCEPT TO THE EXTENT THAT THESE DISCLAIMERS ARE HELD TO BE LEGALLY INVALID UNDER APPLICABLE LAW. + +9. High Risk Activities + +The XMOS Software is not designed or intended for use in conjunction with on-line control equipment in hazardous environments requiring fail-safe performance, including without limitation the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, life support machines, or weapons systems (collectively "High Risk Activities") in which the failure of the XMOS Software could lead directly to death, personal injury, or severe physical or environmental damage. XMOS and its licensors specifically disclaim any express or implied warranties relating to use of the XMOS Software in connection with High Risk Activities. + +10. Liability + +TO THE EXTENT NOT PROHIBITED BY APPLICABLE LAW, NEITHER XMOS NOR ITS LICENSORS SHALL BE LIABLE FOR ANY LOST REVENUE, BUSINESS, PROFIT, CONTRACTS OR DATA, ADMINISTRATIVE OR OVERHEAD EXPENSES, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES HOWEVER CAUSED AND REGARDLESS OF THEORY OF LIABILITY ARISING OUT OF THIS LICENSE, EVEN IF XMOS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. In no event shall XMOS's liability to the Customer whether in contract, tort (including negligence), or otherwise exceed the License Fee. + +Customer agrees to indemnify, hold harmless, and defend XMOS and its licensors from and against any claims or lawsuits, including attorneys' fees and any other liabilities, demands, proceedings, damages, losses, costs, expenses fines and charges which are made or brought against or incurred by XMOS as a result of your use or distribution of the Licensee Modifications or your use or distribution of XMOS Software, or any development of it, other than in accordance with the terms of this License. + +11. Ownership + +The copyrights and all other intellectual and industrial property rights for the protection of information with respect to the XMOS Software (including the methods and techniques on which they are based) are retained by XMOS and/or its licensors. Nothing in this Agreement serves to transfer such rights. Customer may not sell, mortgage, underlet, sublease, sublicense, lend or transfer possession of the XMOS Software in any way whatsoever to any third party who is not bound by this Agreement. + +12. Termination + +Either party may terminate this License at any time on written notice to the other if the other: + +- is in material or persistent breach of any of the terms of this License and either that breach is incapable of remedy, or the other party fails to remedy that breach within 30 days after receiving written notice requiring it to remedy that breach; or + +- is unable to pay its debts (within the meaning of section 123 of the Insolvency Act 1986), or becomes insolvent, or is subject to an order or a resolution for its liquidation, administration, winding-up or dissolution (otherwise than for the purposes of a solvent amalgamation or reconstruction), or has an administrative or other receiver, manager, trustee, liquidator, administrator or similar officer appointed over all or any substantial part of its assets, or enters into or proposes any composition or arrangement with its creditors generally, or is subject to any analogous event or proceeding in any applicable jurisdiction. + +Termination by either party in accordance with the rights contained in clause 12 shall be without prejudice to any other rights or remedies of that party accrued prior to termination. + +On termination for any reason: + +- all rights granted to the Customer under this License shall cease; +- the Customer shall cease all activities authorised by this License; +- the Customer shall immediately pay any sums due to XMOS under this License; and +- the Customer shall immediately destroy or return to the XMOS (at the XMOS's option) all copies of the XMOS Software then in its possession, custody or control and, in the case of destruction, certify to XMOS that it has done so. + +Clauses 5, 8, 9, 10 and 11 shall survive any effective termination of this Agreement. + +13. Third party rights + +No term of this License is intended to confer a benefit on, or to be enforceable by, any person who is not a party to this license. + +14. Confidentiality and publicity + +Each party shall, during the term of this License and thereafter, keep confidential all, and shall not use for its own purposes nor without the prior written consent of the other disclose to any third party any, information of a confidential nature (including, without limitation, trade secrets and information of commercial value) which may become known to such party from the other party and which relates to the other party, unless such information is public knowledge or already known to such party at the time of disclosure, or subsequently becomes public knowledge other than by breach of this license, or subsequently comes lawfully into the possession of such party from a third party. + +The terms of this license are confidential and may not be disclosed by the Customer without the prior written consent of XMOS. +The provisions of clause 14 shall remain in full force and effect notwithstanding termination of this license for any reason. + +15. Entire agreement + +This License and the documents annexed as appendices to this License or otherwise referred to herein contain the whole agreement between the parties relating to the subject matter hereof and supersede all prior agreements, arrangements and understandings between the parties relating to that subject matter. + +16. Assignment + +The Customer shall not assign this License or any of the rights granted under it without XMOS's prior written consent. + +17. Governing law and jurisdiction + +This License shall be governed by and construed in accordance with English law and each party hereby submits to the non-exclusive jurisdiction of the English courts. + +This License has been entered into on the date stated at the beginning of it. + +Schedule +XMOS lib_xua software diff --git a/examples/AN00247_xua_example_spdif_tx/Makefile b/examples/AN00247_xua_example_spdif_tx/Makefile new file mode 100644 index 00000000..a6733f6d --- /dev/null +++ b/examples/AN00247_xua_example_spdif_tx/Makefile @@ -0,0 +1,21 @@ +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 -fxscope + +# 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 + +#============================================================================= +# The following part of the Makefile includes the common build infrastructure +# for compiling XMOS applications. You should not need to edit below here. + +XMOS_MAKE_PATH ?= ../.. +include $(XMOS_MAKE_PATH)/xcommon/module_xcommon/build/Makefile.common + diff --git a/examples/AN00247_xua_example_spdif_tx/README.rst b/examples/AN00247_xua_example_spdif_tx/README.rst new file mode 100644 index 00000000..ef159ebf --- /dev/null +++ b/examples/AN00247_xua_example_spdif_tx/README.rst @@ -0,0 +1,34 @@ + +Simple USB Audio Device using lib_xua +===================================== + +.. 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/AN00247_xua_example_spdif_tx/doc/AN00246.rst b/examples/AN00247_xua_example_spdif_tx/doc/AN00246.rst new file mode 100644 index 00000000..89267983 --- /dev/null +++ b/examples/AN00247_xua_example_spdif_tx/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/AN00247_xua_example_spdif_tx/doc/rst/AN00247.rst b/examples/AN00247_xua_example_spdif_tx/doc/rst/AN00247.rst new file mode 100644 index 00000000..721103b9 --- /dev/null +++ b/examples/AN00247_xua_example_spdif_tx/doc/rst/AN00247.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 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 + +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:: + + USED_MODULES = .. lib_xua lib_spdif ... + +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" + +The application uses the S/PDIF transmitter from ``lib_spdif``. This header +must be inluced in your code to the library. + +.. literalinclude:: app_xua_simple.xc + :start-on: /* From lib_spdif + :end-on: include "spdif.h" + +Allocating hardware resources for lib_xua +......................................... + +A most basic implementation of a USB Audio device with no 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: + +.. literalinclude:: app_xua_simple.xc + :start-on: /* Lib_xua 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 + +Allocating hardware resources for lib_spdif +........................................... + +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 + +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()``). + +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). In addition the ``spdif_tx()`` task is also run. + +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/AN00247_xua_example_spdif_tx/doc/rst/images/hw_setup.jpg b/examples/AN00247_xua_example_spdif_tx/doc/rst/images/hw_setup.jpg new file mode 100644 index 00000000..8998805d Binary files /dev/null and b/examples/AN00247_xua_example_spdif_tx/doc/rst/images/hw_setup.jpg differ diff --git a/examples/AN00247_xua_example_spdif_tx/doc/rst/xdoc.conf b/examples/AN00247_xua_example_spdif_tx/doc/rst/xdoc.conf new file mode 100644 index 00000000..37460abf --- /dev/null +++ b/examples/AN00247_xua_example_spdif_tx/doc/rst/xdoc.conf @@ -0,0 +1,2 @@ +XMOSNEWSTYLE=1 +SOURCE_INCLUDE_DIRS=../../src \ No newline at end of file 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 new file mode 100644 index 00000000..9e5b1215 --- /dev/null +++ b/examples/AN00247_xua_example_spdif_tx/src/app_xua_simple.xc @@ -0,0 +1,103 @@ +// Copyright (c) 2017-2018, XMOS Ltd, All rights reserved + +/* A very simple *example* of a USB audio application (and as such is un-verified for production) + * + * It uses the main blocks from the lib_xua + * + * - S/PDIF output only + * - No DFU + * + */ + +#include +#include + +#include "xua.h" +#include "xud_device.h" + +/* From lib_spdif */ +#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 */ + +/* 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 */ + +/* Resources for USB feedback */ +in port p_for_mclk_count = PORT_MCLK_COUNT; /* Extra port for counting master clock ticks */ +in port p_mclk_in_usb = PORT_MCLK_IN_USB; /* Extra master clock input for the USB tile */ + +/* Clock-block declarations */ +clock clk_audio_mclk = on tile[0]: XS1_CLKBLK_5; /* Master clock */ +clock clk_audio_mclk_usb = on tile[1]: XS1_CLKBLK_1; /* Master clock for USB tile */ + +/* Endpoint type tables - informs XUD what the transfer types for each Endpoint in use and also + * if the endpoint wishes to be informed of USB bus resets */ +XUD_EpType epTypeTableOut[] = {XUD_EPTYPE_CTL | XUD_STATUS_ENABLE, XUD_EPTYPE_ISO}; +XUD_EpType epTypeTableIn[] = {XUD_EPTYPE_CTL | XUD_STATUS_ENABLE, XUD_EPTYPE_ISO}; + +int main() +{ + /* Channels for lib_xud */ + chan c_ep_out[2]; + chan c_ep_in[2]; + + /* Channel for communicating SOF notifications from XUD to the Buffering cores */ + chan c_sof; + + /* Channel for audio data between buffering cores and AudioHub/IO core */ + chan c_aud; + + /* Channel for communicating control messages from EP0 to the rest of the device (via the buffering cores) */ + chan c_aud_ctl; + + /* Channel for communication between AudioHub and S/PDIF transmitter */ + chan c_spdif_tx; + + par + { + /* Low level USB device layer core */ + on tile[1]: XUD_Main(c_ep_out, 2, c_ep_in, 2, c_sof, epTypeTableOut, epTypeTableIn, null, null, -1, XUD_SPEED_HS, XUD_PWR_SELF); + + /* Endpoint 0 core from lib_xua */ + /* Note, since we are not using many features we pass in null for quite a few params.. */ + on tile[1]: XUA_Endpoint0(c_ep_out[0], c_ep_in[0], c_aud_ctl, null, null, null, null); + + /* Buffering cores - handles audio data to/from EP's and gives/gets data to/from the audio I/O core */ + /* Note, this spawns two cores */ + on tile[1]: { + + /* Connect master-clock clock-block to clock-block pin */ + set_clock_src(clk_audio_mclk_usb, p_mclk_in_usb); /* Clock clock-block from mclk pin */ + set_port_clock(p_for_mclk_count, clk_audio_mclk_usb); /* Clock the "count" port from the clock block */ + start_clock(clk_audio_mclk_usb); /* Set the clock off running */ + + XUA_Buffer(c_ep_out[1], c_ep_in[1], c_sof, c_aud_ctl, p_for_mclk_count, c_aud); + } + + /* AudioHub() (I2S) and S/SPDIF Tx are on the same tile */ + 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); + + par + { + while(1) + { + /* Run the S/PDIF transmitter task */ + spdif_tx(p_spdif_tx2, c_spdif_tx); + } + + /* AudioHub/IO core does most of the audio IO i.e. I2S (also serves as a hub for all audio) */ + /* Note, since we are not using I2S we pass in null for LR and Bit clock ports and the I2S dataline ports */ + XUA_AudioHub(c_aud, clk_audio_mclk, null, p_mclk_in, null, null, null, null, c_spdif_tx); + } + } + } + + return 0; +} + + diff --git a/examples/AN00247_xua_example_spdif_tx/src/cs4384.h b/examples/AN00247_xua_example_spdif_tx/src/cs4384.h new file mode 100644 index 00000000..98defbe3 --- /dev/null +++ b/examples/AN00247_xua_example_spdif_tx/src/cs4384.h @@ -0,0 +1,32 @@ +// Copyright (c) 2017-2018, XMOS Ltd, All rights reserved +#ifndef CS4384_H_ +#define CS4384_H_ + +//Address on I2C bus +#define CS4384_I2C_ADDR (0x18) + +//Register Addresess +#define CS4384_CHIP_REV 0x01 +#define CS4384_MODE_CTRL 0x02 +#define CS4384_PCM_CTRL 0x03 +#define CS4384_DSD_CTRL 0x04 +#define CS4384_FLT_CTRL 0x05 +#define CS4384_INV_CTRL 0x06 +#define CS4384_GRP_CTRL 0x07 +#define CS4384_RMP_MUTE 0x08 +#define CS4384_MUTE_CTRL 0x09 +#define CS4384_MIX_PR1 0x0a +#define CS4384_VOL_A1 0x0b +#define CS4384_VOL_B1 0x0c +#define CS4384_MIX_PR2 0x0d +#define CS4384_VOL_A2 0x0e +#define CS4384_VOL_B2 0x0f +#define CS4384_MIX_PR3 0x10 +#define CS4384_VOL_A3 0x11 +#define CS4384_VOL_B3 0x12 +#define CS4384_MIX_PR4 0x13 +#define CS4384_VOL_A4 0x14 +#define CS4384_VOL_B4 0x15 +#define CS4384_CM_MODE 0x16 + +#endif /* CS4384_H_ */ diff --git a/examples/AN00247_xua_example_spdif_tx/src/cs5368.h b/examples/AN00247_xua_example_spdif_tx/src/cs5368.h new file mode 100644 index 00000000..945ae536 --- /dev/null +++ b/examples/AN00247_xua_example_spdif_tx/src/cs5368.h @@ -0,0 +1,18 @@ +// Copyright (c) 2017-2018, XMOS Ltd, All rights reserved +#ifndef _CS5368_H_ +#define _CS5368_H_ + +//Address on I2C bus +#define CS5368_I2C_ADDR (0x4C) + +//Register Addresess +#define CS5368_CHIP_REV 0x00 +#define CS5368_GCTL_MDE 0x01 +#define CS5368_OVFL_ST 0x02 +#define CS5368_OVFL_MSK 0x03 +#define CS5368_HPF_CTRL 0x04 +#define CS5368_PWR_DN 0x06 +#define CS5368_MUTE_CTRL 0x08 +#define CS5368_SDO_EN 0x0a + +#endif /* _CS5368_H_ */ diff --git a/examples/AN00247_xua_example_spdif_tx/src/hwsupport.xc b/examples/AN00247_xua_example_spdif_tx/src/hwsupport.xc new file mode 100644 index 00000000..ad53b961 --- /dev/null +++ b/examples/AN00247_xua_example_spdif_tx/src/hwsupport.xc @@ -0,0 +1,135 @@ +// Copyright (c) 2016-2018, XMOS Ltd, All rights reserved + +#include +#include + +#include "xua.h" +#include "i2c_shared.h" + +#include "cs5368.h" +#include "cs4384.h" + +on tile [0] : struct r_i2c r_i2c = {XS1_PORT_4A}; + + +/* General output port bit definitions */ +#define P_GPIO_DSD_MODE (1 << 0) /* DSD mode select 0 = 8i/8o I2S, 1 = 8o DSD*/ +#define P_GPIO_DAC_RST_N (1 << 1) +#define P_GPIO_USB_SEL0 (1 << 2) +#define P_GPIO_USB_SEL1 (1 << 3) +#define P_GPIO_VBUS_EN (1 << 4) +#define P_GPIO_PLL_SEL (1 << 5) /* 1 = CS2100, 0 = Phaselink clock source */ +#define P_GPIO_ADC_RST_N (1 << 6) +#define P_GPIO_MCLK_FSEL (1 << 7) /* Select frequency on Phaselink clock. 0 = 24.576MHz for 48k, 1 = 22.5792MHz for 44.1k.*/ + +#define DAC_REGWRITE(reg, val) {data[0] = val; i2c_shared_master_write_reg(r_i2c, CS4384_I2C_ADDR, reg, data, 1);} +#define DAC_REGREAD(reg, val) {i2c_shared_master_read_reg(r_i2c, CS4384_I2C_ADDR, reg, val, 1);} +#define ADC_REGWRITE(reg, val) {data[0] = val; i2c_shared_master_write_reg(r_i2c, CS5368_I2C_ADDR, reg, data, 1);} + +out port p_gpio = on tile[0]:XS1_PORT_8C; + +void AudioHwConfig(unsigned samFreq, unsigned mClk, unsigned dsdMode, + unsigned sampRes_DAC, unsigned sampRes_ADC) +{ + unsigned char data[1] = {0}; + unsigned char gpioVal = 0; + + /* Set master clock select appropriately and put ADC and DAC into reset */ + if (mClk == MCLK_441) + { + gpioVal = P_GPIO_USB_SEL0 | P_GPIO_USB_SEL1; + } + else + { + gpioVal = P_GPIO_USB_SEL0 | P_GPIO_USB_SEL1 | P_GPIO_MCLK_FSEL; + } + + p_gpio <: gpioVal; + + /* Allow MCLK to settle */ + delay_microseconds(20000); + + /* Take ADC out of reset */ + gpioVal |= P_GPIO_ADC_RST_N; + p_gpio <: gpioVal; + + /* Configure ADC for I2S slave mode via I2C */ + unsigned dif = 0, mode = 0; + dif = 0x01; /* I2S */ + mode = 0x03; /* Slave mode all speeds */ + + /* Reg 0x01: (GCTL) Global Mode Control Register + * Bit[7]: CP-EN: Manages control-port mode + * Bit[6]: CLKMODE: Setting puts part in 384x mode + * Bit[5:4]: MDIV[1:0]: Set to 01 for /2 + * Bit[3:2]: DIF[1:0]: Data Format: 0x01 for I2S, 0x02 for TDM + * Bit[1:0]: MODE[1:0]: Mode: 0x11 for slave mode + */ + ADC_REGWRITE(CS5368_GCTL_MDE, 0b10010000 | (dif << 2) | mode); + + /* Reg 0x06: (PDN) Power Down Register */ + /* Bit[7:6]: Reserved + * Bit[5]: PDN-BG: When set, this bit powers-own the bandgap reference + * Bit[4]: PDM-OSC: Controls power to internal oscillator core + * Bit[3:0]: PDN: When any bit is set all clocks going to that channel pair are turned off + */ + ADC_REGWRITE(CS5368_PWR_DN, 0b00000000); + + /* Configure DAC with PCM values. Note 2 writes to mode control to enable/disable freeze/power down */ + /* Take DAC out of reset */ + gpioVal |= P_GPIO_DAC_RST_N; + p_gpio <: gpioVal; + + delay_microseconds(500); + + /* Mode Control 1 (Address: 0x02) */ + /* bit[7] : Control Port Enable (CPEN) : Set to 1 for enable + * bit[6] : Freeze controls (FREEZE) : Set to 1 for freeze + * bit[5] : PCM/DSD Selection (DSD/PCM) : Set to 0 for PCM + * bit[4:1] : DAC Pair Disable (DACx_DIS) : All Dac Pairs enabled + * bit[0] : Power Down (PDN) : Powered down + */ + DAC_REGWRITE(CS4384_MODE_CTRL, 0b11000001); + + /* PCM Control (Address: 0x03) */ + /* bit[7:4] : Digital Interface Format (DIF) : 0b0001 for I2S up to 24bit + * bit[3:2] : Reserved + * bit[1:0] : Functional Mode (FM) : 0x00 - single-speed mode (4-50kHz) + * : 0x01 - double-speed mode (50-100kHz) + * : 0x10 - quad-speed mode (100-200kHz) + * : 0x11 - auto-speed detect (32 to 200kHz) + * (note, some Mclk/SR ratios not supported in auto) + * + */ + unsigned char regVal = 0; + if(samFreq < 50000) + regVal = 0b00010100; + else if(samFreq < 100000) + regVal = 0b00010101; + else //if(samFreq < 200000) + regVal = 0b00010110; + + DAC_REGWRITE(CS4384_PCM_CTRL, regVal); + + /* Mode Control 1 (Address: 0x02) */ + /* bit[7] : Control Port Enable (CPEN) : Set to 1 for enable + * bit[6] : Freeze controls (FREEZE) : Set to 0 for freeze + * bit[5] : PCM/DSD Selection (DSD/PCM) : Set to 0 for PCM + * bit[4:1] : DAC Pair Disable (DACx_DIS) : All Dac Pairs enabled + * bit[0] : Power Down (PDN) : Not powered down + */ + DAC_REGWRITE(CS4384_MODE_CTRL, 0b10000000); + + return; +} + +void AudioHwInit() +{ + /* Set USB Mux to micro-b */ + /* ADC and DAC in reset */ + p_gpio <: P_GPIO_USB_SEL0 | P_GPIO_USB_SEL1; + + /* Init the i2c module */ + i2c_shared_master_init(r_i2c); +} + diff --git a/examples/AN00247_xua_example_spdif_tx/src/xk-audio-216-mc.xn b/examples/AN00247_xua_example_spdif_tx/src/xk-audio-216-mc.xn new file mode 100644 index 00000000..c2e90f16 --- /dev/null +++ b/examples/AN00247_xua_example_spdif_tx/src/xk-audio-216-mc.xn @@ -0,0 +1,88 @@ + + + Board + XS2 MC Audio + + tileref tile[2] + tileref usb_tile + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + --> + --> + + + + + + + + + + --> + --> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/examples/AN00247_xua_example_spdif_tx/src/xua_conf.h b/examples/AN00247_xua_example_spdif_tx/src/xua_conf.h new file mode 100644 index 00000000..d83f5a2e --- /dev/null +++ b/examples/AN00247_xua_example_spdif_tx/src/xua_conf.h @@ -0,0 +1,30 @@ +// Copyright (c) 2017-2018, XMOS Ltd, All rights reserved + +#ifndef _XUA_CONF_H_ +#define _XUA_CONF_H_ + +#define NUM_USB_CHAN_OUT 2 +#define NUM_USB_CHAN_IN 0 +#define I2S_CHANS_DAC 0 +#define I2S_CHANS_ADC 0 +#define MCLK_441 (512 * 44100) +#define MCLK_48 (512 * 48000) +#define MIN_FREQ 48000 +#define MAX_FREQ 48000 + +#define EXCLUDE_USB_AUDIO_MAIN + +#define XUA_SPDIF_TX_EN 1 +#define SPDIF_TX_INDEX 0 +#define VENDOR_STR "XMOS" +#define VENDOR_ID 0x20B1 +#define PRODUCT_STR_A2 "XUA SPDIF Example" +#define PRODUCT_STR_A1 "XUA SPDIF 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 + +#endif diff --git a/examples/AN00247_xua_example_spdif_tx/src/xud_conf.h b/examples/AN00247_xua_example_spdif_tx/src/xud_conf.h new file mode 100644 index 00000000..c14d64a8 --- /dev/null +++ b/examples/AN00247_xua_example_spdif_tx/src/xud_conf.h @@ -0,0 +1,7 @@ +// Copyright (c) 2017-2018, XMOS Ltd, All rights reserved + +#include "xua_conf.h" + +/* TODO */ +#define XUD_UAC_NUM_USB_CHAN_OUT NUM_USB_CHAN_OUT +#define XUD_UAC_NUM_USB_CHAN_IN NUM_USB_CHAN_IN