From b7f9dd5781340cdd27abce354fac01046c065e07 Mon Sep 17 00:00:00 2001 From: Ross Owen Date: Tue, 9 Aug 2022 11:25:03 +0100 Subject: [PATCH] Update AN00246_xua_example.rst --- .../doc/rst/AN00246_xua_example.rst | 54 ++++++++----------- 1 file changed, 22 insertions(+), 32 deletions(-) diff --git a/examples/AN00246_xua_example/doc/rst/AN00246_xua_example.rst b/examples/AN00246_xua_example/doc/rst/AN00246_xua_example.rst index 682c7f00..a3fda049 100644 --- a/examples/AN00246_xua_example/doc/rst/AN00246_xua_example.rst +++ b/examples/AN00246_xua_example/doc/rst/AN00246_xua_example.rst @@ -48,7 +48,7 @@ be included in your code to use the library. :start-on: include "xua.h" :end-on: include "xud_device.h" -Allocating hardware resources +Allocating Hardware Resources ............................. A basic implementation of a USB Audio device (i.e. simple stereo output via I2S) @@ -63,7 +63,7 @@ using ``lib_xua`` requires the follow pins: This application note assumes xCORE is I2S bus master -On an xCORE the pins are controlled by ``ports``. The application therefore declares various ``ports`` +In the xCORE architecture the I/O pins are controlled and accessed by ``ports``. The application therefore declares various ``ports`` for this purpose: .. literalinclude:: app_xua_simple.xc @@ -71,8 +71,8 @@ for this purpose: :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. +the ``lib_xua`` library documentation for further details. The additional input port for the master +clock is required since USB and S/PDIF do not reside of the same tiles on the xCORE.ai MC Audio Board. These ports are declared as follows: @@ -90,7 +90,7 @@ Again, for the same reasoning as the master-clock ports, two master-clock clock- - one on each tile. -Other declarations +Other Declarations .................. ``lib_xua`` currently requires the manual declaration of tables for the endpoint types for @@ -107,12 +107,12 @@ These are declared as follows: :start-on: /* Endpoint type tables :end-on: XUD_EpType epTypeTableIn -The application main() function +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. +Various channels are required in order to allow the required tasks to communicate. These must first be declared: .. literalinclude:: app_xua_simple.xc @@ -129,6 +129,9 @@ using the xC ``par`` construct: 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). +It also runs a small function ``ctrlPort()`` that simply writes some values to an I/O port to configure some external +hardware (it enables analogue power supplies and correctly routes the master clock) and then closes. + Configuration ............. @@ -157,10 +160,10 @@ implentation e.g. master clock frequencies and must be defined. Please see the Demo Hardware Setup ------------------- -To run the demo, use a USB cable to connect the on-board xTAG debug adapter (marked DEBUG) to your development computer. -Use another USB cable to connect the USB receptacle marked USB DEVICE to the device you wish to play audio from. +To run the demo, use a USB cable to connect the on-board xTAG debug adapter (marked ``DEBUG``) to your development computer. +Use another USB cable to connect the USB receptacle marked ``USB DEVICE`` to the device you wish to play audio from. -Plug a device capable of receiving analogue audio (i.e. a amplified speaker) to the 3.5mm jack marked OUT 1/2. +Plug a device capable of receiving analogue audio (i.e. an amplified speaker) to the 3.5mm jack marked ``OUT 1/2``. .. figure:: images/hw_setup.* :width: 80% @@ -169,40 +172,27 @@ Plug a device capable of receiving analogue audio (i.e. a amplified speaker) to |newpage| -Launching the demo application +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.ai -MC Audio board. +Once the demo example has been built from the command line using ``xmake`` +it can be executed on the xCORE.ai 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 +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 + xrun ./bin/app_xua_simple.xe Once this command has executed the application will be running on the xCORE.ai 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.ai MC Audio board. - -Running the application +Running the Application ....................... Once running the device will be detected as a USB Audio device - note, Windows operating @@ -233,11 +223,11 @@ References |newpage| -Full source code listing +Full Source Code Listing ------------------------ -Source code for main.xc -....................... +Source Code for app_xua_simple.xc +................................. .. literalinclude:: app_xua_simple.xc :largelisting: