- Documentation tweaks

- Temp disable checks due to issue with changelog checker

Jenkinsfile

@@ -167,7 +167,8 @@ pipeline {
               steps {
                 withTools("${env.TOOLS_VERSION}") {
                   warnError("libchecks") {
-                    runSwrefChecks("${WORKSPACE}/${REPO}", "${params.INFR_APPS_VERSION}")
+                    // Temp disable checks due to issue with changelog checker
+                    //runSwrefChecks("${WORKSPACE}/${REPO}", "${params.INFR_APPS_VERSION}")
                   } // warnError("libchecks")
                 } // withTools("${env.TOOLS_VERSION}")
               } // steps

README.rst

@@ -25,49 +25,60 @@ The complete source code, together with the free XMOS XTC development tools and
 multi-core micro-controller devices, allow the developer to select the exact mix of interfaces
 and processing required.
 
-The XMOS USB Audio solution is deployed as a framework (see `lib_xua <https://www.xmos.com/file/lib_xua>`__) with reference design
-applications extending and customising this framework. These reference designs have particular
-qualified feature sets and an accompanying reference hardware platform.
+The XMOS USB Audio solution is deployed as a framework (see `lib_xua <https://www.xmos.com/file/lib_xua>`__)
+with reference design applications extending and customising this framework.
+These reference designs have particular qualified feature sets and an accompanying reference
+hardware platform.
 
-Please note, Alpha and Beta releases may not accurately reflect the final release and documentation may not be complete.
-These early releases are not suitable for a production context, and are provided for evaluation purposes only. See 'Release Quality & QA'.
+Please note, Alpha and Beta releases may not accurately reflect the final release and documentation
+may not be complete.
+These early releases are not suitable for a production context, and are provided for evaluation
+purposes only. See 'Release Quality & QA'.
 
-Please see CHANGELOG.rst for detailed change listing.
+Refere to CHANGELOG.rst for detailed change listing.
 
 For full software documentation please see the USB Audio User Guide document.
 
-This release is built and tested using version 15.3.0 of the XMOS tool set.  Build or functionality issues could be experienced with any other version.
+This release is built and tested using version 15.3.0 of the XMOS tool set.
+Build or functionality issues could be experienced with any other version.
 
-This repository contains applications (or instances) of the XMOS USB Audio Reference Design framework.  These applications
-typically relate to a specific hardware platform.  This repository contains the following:
+This repository contains applications (or instances) of the XMOS USB Audio Reference Design framework.
+These applications typically relate to a specific hardware platform.
+This repository contains the following:
 
-+--------------------------+--------------------------+------------------------------------------------------------+
-|    App Name              |     Relevant Board(s)    | Description                                                |
-+==========================+==========================+============================================================+
-| app_usb_aud_xk_216_mc    | xk-audio-216-mc          | xcore-200 Multi-channel Audio Board                        |
-+--------------------------+--------------------------+------------------------------------------------------------+
-| app_usb_aud_xk_316_mc    | xk-audio-316-mc          | xcore.ai Multi-channel Audio Board                         |
-+--------------------------+--------------------------+------------------------------------------------------------+
-| app_usb_aud_xk_evk_xu316 | xk-evk-xu316             | xcore.ai Explorer Board                                    |
-+--------------------------+--------------------------+------------------------------------------------------------+
++--------------------------+--------------------------+--------------------------------------------+
+|    App Name              |     Relevant Board(s)    | Description                                |
++==========================+==========================+============================================+
+| app_usb_aud_xk_216_mc    | xk-audio-216-mc          | xcore-200 Multi-channel Audio Board        |
++--------------------------+--------------------------+--------------------------------------------+
+| app_usb_aud_xk_316_mc    | xk-audio-316-mc          | xcore.ai Multi-channel Audio Board         |
++--------------------------+--------------------------+--------------------------------------------+
+| app_usb_aud_xk_evk_xu316 | xk-evk-xu316             | xcore.ai Evaluation Kit                    |
++--------------------------+--------------------------+--------------------------------------------+
 
 Please refer to individual README files in these apps for more detailed information.
 
-Each application contains a "core" folder, this folder contains items that are required to use and run the USB Audio application framework.
+Each application contains a "core" folder, this folder contains items that are required to use and
+run the USB Audio application framework.
 Mandatory files per application include:
 
 - An XN file describing the board including required port defines.
 - xua_conf.h header file containing configuration items such as channel count, strings etc.
 
-Each application also contains an "extensions" folder which includes board specific extensions such as CODEC configuration etc.
+Each application also contains an "extensions" folder which includes board specific extensions such
+as CODEC configuration etc.
 
-Additionally some options are contained in Makefiles for building multiple configurations of an application. For example an application may provide configurations with and without MIDI enabled.  See the USB Audio Software User Guide for full details.
+Additionally some options are contained in application `CMakeLists.txt` files for building multiple
+configurations of an application.
+For example an application may provide configurations with and without MIDI enabled.
+See the USB Audio Software User Guide for full details.
 
 ********
 Features
 ********
 
-Key features of the various applications in this repository are listed below.  Please refer to the application README the specific feature set supported by that application.
+Key features of the various applications in this repository are listed below.
+Refer to the application README the specific feature set supported by that application.
 
 - USB Audio Class 1.0/2.0 Compliant
 
@@ -97,7 +108,8 @@ Key features of the various applications in this repository are listed below.  P
 
 - Simple playback controls via Human Interface Device (HID)
 
-Note, not all features may be supported at all sample frequencies, simultaneously or on all devices.  Some features also require specific host driver support.
+Note, not all features may be supported at all sample frequencies, simultaneously or on all devices.
+Some features also require specific host driver support.
 
 Release quality & QA
 ====================
@@ -140,7 +152,8 @@ Release quality & QA
 Known issues
 ************
 
-General known issues with this release are listed below.  For board/application specific known issues please see README in relevant app directory
+General known issues with this release are listed below.
+For board/application specific known issues please see README in relevant app directory
 
 - (xmos/sw_usb_audio#54) When DFU flash access fails the xcore sends NAKs to the USB host forever, rather than a STALL
 
@@ -217,10 +230,10 @@ Required libraries (dependencies)
 Related application notes
 *************************
 
- * AN02019: Using Device Firmware Upgrade (DFU) for USB Audio
- * AN00136: Example USB Vendor Specific Device
- * AN02026: Blocked DSP inside USB Audio
- * AN01009: Optimizing USB Audio for stereo output, battery powered devices
+ * `AN02019: Using Device Firmware Upgrade (DFU) for USB Audio <https://www.xmos.com/file/an02019>`_
+ * `AN00136: Example USB Vendor Specific Device <https://www.xmos.com/file/an00136>`_
+ * `AN02026: Blocked DSP inside USB Audio <https://www.xmos.com/file/an02026>`_
+ * `AN01009: Optimizing USB Audio for stereo output, battery powered device <https://www.xmos.com/file/an01009>`_
 
 *******
 Support

app_usb_aud_xk_216_mc/README.rst

@@ -1,9 +1,8 @@
-XMOS xCORE-200 USB Audio
+XMOS xcore-200 USB Audio
 ========================
 
-:maintainer: Ross Owen
 :scope: Example
-:description: USB Audio application for xCORE-200 MC Audio
+:description: USB Audio application for xcore-200 MC Audio
 :keywords: USB, UAC
 :boards: XCORE-200 MC AUDIO (rev 2.0)
 
@@ -15,13 +14,14 @@ The firmware provides a high-speed USB Audio device designed to be compliant to
 Key Features
 ............
 
-The app_usb_aud_xk_216_mc application is designed to run on the xCORE 200 MC Audio Board in. It uses the XMOS USB Audio framework to implement a USB Audio device with the following key features:
+The app_usb_aud_xk_216_mc application is designed to run on the xcore-200 MC Audio Board in.
+It uses the XMOS USB Audio framework to implement a USB Audio device with the following key features:
 
 - USB Audio Class 2.0 Compliant
 
 - Fully Asynchronous operation
 
-- 4 channels analogue input and 4 channels analogue output (Via I2S to 2 x Stereo CODECs)
+- 4 channels analogue input and 4 channels analogue output (Via I²S to 2 x Stereo CODECs)
 
 - S/PDIF output (via COAX connector)
 

app_usb_aud_xk_316_mc/README.rst

@@ -2,26 +2,27 @@ XMOS xcore.ai USB Audio
 =======================
 
 :scope: Example
-:description: USB Audio application for xCORE-AI MC Audio
+:description: USB Audio application for xcore.ai MC Audio
 :keywords: USB, UAC
 :boards: XK-AUDIO-316-MC
 
 Overview
 ........
 
-The firmware provides a high-speed USB Audio device designed to be compliant to version 2.0 of the USB Audio Class Specification based on the xcore.ai device.
-
+The firmware provides a high-speed USB Audio device designed to be compliant to version 2.0 of the
+USB Audio Class Specification based on the xcore.ai device.
 
 Key Features
 ............
 
-The app_usb_aud_xk_316_mc application is designed to run on the xcore.ai Multichannel Audio Board. It uses the XMOS USB Audio framework to implement a USB Audio device with the following key features:
+The app_usb_aud_xk_316_mc application is designed to run on the xcore.ai Multichannel Audio Board.
+It uses the XMOS USB Audio framework to implement a USB Audio device with the following key features:
 
 - USB Audio Class 1.0/2.0 Compliant
 
 - Fully Asynchronous operation
 
-- 8 channels analogue input and 8 channels analogue output (Via I2S to 4 x Stereo DACs and 2 x Quad-channel ADCs)
+- 8 channels analogue input and 8 channels analogue output (Via I²S to 4 x Stereo DACs and 2 x Quad-channel ADCs)
 
 - S/PDIF output (via COAX connector)
 

app_usb_aud_xk_evk_xu316/README.rst

@@ -1,24 +1,26 @@
 XMOS xcore.ai USB Audio
 =======================
 
-:maintainer: Ross Owen
 :scope: Example
-:description: USB Audio application for xCORE.ai eXplorer board
+:description: USB Audio application for xcore.ai evaluation kit
 :keywords: USB, UAC
 :boards: XK-EVK-XU316 (rev 2.0)
 
 Overview
 ........
 
-The firmware provides a high-speed USB Audio device designed to be compliant to version 2.0 of the USB Audio Class Specification based on the XMOS xCORE.ai device.
-
-Note, this project only functions on revision 2 of the XK-EVK-XU316 board. Early versions of the hardware require modifications to both the hardware and software to operate correctly. 
+The firmware provides a high-speed USB Audio device designed to be compliant to version 2.0 of the
+USB Audio Class Specification based on the XMOS xcore.ai device.
 
+Note, this project only functions on revision 2 of the XK-EVK-XU316 board.
+Early versions of the hardware require modifications to both the hardware and software to operate
+correctly.
 
 Key Features
 ............
 
-The app_usb_aud_xk_evk_xu316 application is designed to run on the xCORE.ai eXplorer board. It uses the XMOS USB Audio framework to implement a USB Audio device with the following key features:
+The app_usb_aud_xk_evk_xu316 application is designed to run on the xcore-200 Evaluation Kit.
+It uses the XMOS USB Audio framework to implement a USB Audio device with the following key features:
 
 - USB Audio Class 2.0 Compliant
 

doc/rst/api_user_functions.rst

@@ -2,12 +2,12 @@ User function definitions
 =========================
 
 The following functions can be optionally defined by an application to override default (empty)
-implementation in ``lib_xua``.
+implementations in ``lib_xua``.
 
 External audio hardware configuration
 -------------------------------------
 
-The functions should be implemented to configure external audio hardware.
+The functions listed below should be implemented to configure external audio hardware.
 
 .. doxygenfunction:: AudioHwInit
 .. doxygenfunction:: AudioHwConfig
@@ -18,7 +18,7 @@ The functions should be implemented to configure external audio hardware.
 Audio streaming notification
 ----------------------------
 
-They functions can be useful for mute lines, indication LEDs etc.
+The functions listed below can be useful for mute lines, indication LEDs etc.
 
 .. doxygenfunction:: UserAudioStreamStart
 .. doxygenfunction:: UserAudioStreamStop

doc/rst/api_xua_conf.rst

@@ -4,8 +4,8 @@
 Configuration defines
 =====================
 
-An application using the USB audio framework provided by ``lib_xua``  needs to have defines set
-for configuration. Defaults for these defines are found in ``lib_xua`` in ``xua_conf_default.h``.
+An application using the USB audio framework provided by ``lib_xua``  needs to be configured via
+defines. Defaults for these defines are found in ``lib_xua`` in ``xua_conf_default.h``.
 
 An application should override these defines in an optional ``xua_conf.h`` file or in the
 ``CMakeLists.txt`` for the relevant build configuration.

doc/rst/app_216_mc.rst

@@ -9,7 +9,7 @@ hardware described in :ref:`usb_audio_hardware_platforms` and is implemented on
 series dual tile device. The related code can be found in ``app_usb_aud_xk_216_mc``.
 
 The design supports upto 8 channels of analogue audio input/output at sample-rates up to 192kHz
-(assuming the use of I2S). This can be further increased by utilising TDM. It also supports S/PDIF,
+(assuming the use of I²S). This can be further increased by utilising TDM. It also supports S/PDIF,
 ADAT and MIDI input and output as well as the mixing functionalty of ``lib_xua``.
 
 The design uses the following tasks:
@@ -27,7 +27,7 @@ The design uses the following tasks:
  * MIDI
 
 The software layout of the USB Audio 2.0 Reference Design running on the
-`xCORE.ai` device is shown in :numref:`usb_audio_x200_threads`.
+`xcore.ai` device is shown in :numref:`usb_audio_x200_threads`.
 
 Each circle depicts a task running in a single core concurrently with the other tasks. The
 lines show the communication between each task.
@@ -166,7 +166,7 @@ The build configuration naming scheme employed in the CMakeLists.txt is shown in
    * - USB Sync Mode
      - async: A
      - sync: S
-   * - I2S Role
+   * - I²S Role
      - slave: S
      - master: M
    * - Input
@@ -195,7 +195,7 @@ The build configuration naming scheme employed in the CMakeLists.txt is shown in
      - disabled: x
 
 e.g. A build configuration named `2AMi10o10xsxxxx` would signify: Audio class 2.0 running in
-asynchronous mode. The `xcore` is I2S master.
+asynchronous mode. The `xcore` is I²S master.
 Input and output enabled (10 channels each), no MIDI, S/PDIF input, no S/PDIF output, no ADAT or DSD.
 
 In addition to this some terms may be appended onto a build configuration name to signify additional

doc/rst/app_316_mc.rst

@@ -51,7 +51,7 @@ Clocking and clock selection
 As well as the secondary (application) PLL of the `xcore.ai` device the board includes two options for master clock generation:
 
     * A Cirrus Logic CS2100 fractional-N clock multiplier allowing the master clock to be generated from a
-      `xcore` derived reference.
+      `xcore` derived reference clock.
     * A Skyworks Si5351A-B-GT CMOS clock generator.
 
 The master clock source is chosen by driving two control signals as shown below:
@@ -116,7 +116,7 @@ analogue input. Configuration of both the DAC and the ADC takes place over I²C.
 Configuring audio hardware
 --------------------------
 
-All of the external audio hardware is configured using `lib_board_support <http://www.xmos.com/file/`.
+All of the external audio hardware is configured using `lib_board_support <https://www.xmos.com/file/lib_board_support>`_.
 
 .. note::
 
@@ -186,7 +186,7 @@ The build configuration naming scheme employed in the CMakeLists.txt is shown in
    * - USB Sync Mode
      - async: A
      - sync: S
-   * - I2S Role
+   * - I²S Role
      - slave: S
      - master: M
    * - Input
@@ -214,8 +214,11 @@ The build configuration naming scheme employed in the CMakeLists.txt is shown in
      - enabled: d
      - disabled: x
 
-e.g. A build configuration named `2AMi10o10xsxxxx` would signify: Audio Class 2.0 running in asynchronous mode.
-The `xcore` is I²S master. Input and output enabled (10 channels each), no MIDI, S/PDIF input, no S/PDIF output, no ADAT or DSD.
+e.g. A build configuration named `2AMi10o10xsxxxx` would signify: Audio Class 2.0 running in
+asynchronous mode.
+The `xcore` is I²S master. Input and output enabled (10 channels each), no MIDI, S/PDIF input, no
+S/PDIF output, no ADAT or DSD.
 
-In addition to this some terms may be appended onto a build configuration name to signify additional options. For
-example, `tdm` may be appended to the build configuration name to indicate the I²S mode employed.
+In addition to this some terms may be appended onto a build configuration name to signify additional
+options.
+For example, `tdm` may be appended to the build configuration name to indicate the I²S mode employed.

doc/rst/apps.rst

@@ -16,7 +16,7 @@ The applications contained in this repo use ``lib_xua`` in a "code-less" manner.
 the ``main()`` function from ``lib_xua`` and customise the code-base as required using build time defines and by
 providing implementations to the various required functions in order to support their hardware.
 
-Please see `lib_xua` <https://www.xmos.com/file/lib_xua>`_ documentation for full details.
+Refer to `lib_xua` <https://www.xmos.com/file/lib_xua>`_ documentation for full details.
 
 .. toctree::
 

doc/rst/drivers.rst

@@ -27,7 +27,7 @@ Third party Windows drivers
 ===========================
 
 For some products it may be desirable to use a third-party driver for Windows.
-A number reasons exist as to why this may be desirable:
+A number of reasons exist as to why this may be desirable:
 
     - In order to support UAC 2.0 on Windows versions earlier than 10
     - The built-in Windows support is typically designed for consumer audio devices, not for professional audio devices

doc/rst/prog_build_configs.rst

@@ -35,7 +35,7 @@ The output displayed on stdout for the ``cmake`` command will contain the list o
     -- 2AMi2o2xxxxxx
 
 The ``cmake`` command generates the `Makefile` for compiling the different build configurations.
-The Makefile is created in the ``build`` directory.
+The `Makefile` is created in the ``build`` directory.
 
 The next step is to run the ``xmake`` command which executes the commands in the Makefile to build the executables corresponding to
 the build configs. To build all supported configurations for a given application, from the application directory (e.g. ``app_usb_aud_xk_audio_316_mc``),
@@ -124,7 +124,7 @@ See comments in the application `CMakeLists.txt` for details.
 Quality & testing
 =================
 
-It is not possible for all build option permutations to be exhaustively tested. The `XMOS USB Audio
+It is not practical for all build option permutations to be exhaustively tested. The `XMOS USB Audio
 Reference Design` software therefore defines three levels of quality:
 
     * **Fully Tested** - the configuration is fully supported. A product based on it can be immediately put into to a