Merge pull request #409 from xross/develop

Prep for 2.4.0 release

CHANGELOG.rst

@@ -1,12 +1,13 @@
 lib_xud change log
 ==================
 
-UNRELEASED
-----------
+2.4.0
+-----
 
   * CHANGE:   Documentation updates
   * CHANGE:   Examples now build using xcommon-cmake build system (was xcommon)
-  * CHANGE:   AN00129 is now the main library usage example - renamed app_hid_mouse
+  * CHANGE:   AN00129 is now the main library usage example - renamed
+    app_hid_mouse
   * REMOVED:  AN00124 - now maintained as a separate application note
   * REMOVED:  AN00125 - now maintained as a separate application note
   * REMOVED:  AN00126 - now maintained as a separate application note

Jenkinsfile

@@ -34,10 +34,14 @@ pipeline {
       defaultValue: 'v6.1.2',
       description: 'The xmosdoc version'
     )
+    string(
+      name: 'INFR_APPS_VERSION',
+      defaultValue: 'v2.0.1',
+      description: 'The infr_apps version'
+    )
   }
 
   stages {
-
     stage('Build examples') {
       steps {
         println "Stage running on ${env.NODE_NAME}"
@@ -56,11 +60,11 @@ pipeline {
 
     stage('Library checks') {
       steps {
-        runLibraryChecks("${WORKSPACE}/${REPO}", "v2.0.1")
+        runLibraryChecks("${WORKSPACE}/${REPO}", "${params.INFR_APPS_VERSION}")
       }
     }
 
-    stage('Documentation: Library') {
+    stage('Documentation') {
       steps {
         dir("${REPO}") {
           buildDocs()

README.rst

@@ -5,7 +5,7 @@ lib_xud: USB Device Library
 ###########################
 
 :vendor: XMOS
-:version: 2.3.2
+:version: 2.4.0
 :scope: General Use
 :description: USB device library
 :category: General Purpose
@@ -21,8 +21,6 @@ defined, industry-standard, USB library that allows you to control an USB bus vi
 
 The library provides functionality to act as a USB *device* only.
 
-Note, at points lib_xud will run in "fast mode" this is a requirement to meet timing.
-
 ********
 Features
 ********

doc/rst/advanced_usage.rst

@@ -4,7 +4,7 @@
 .. _sec_advanced_usage:
 
 **************
-Advanced Usage
+Advanced usage
 **************
 
 Advanced usage is termed to mean the implementation of multiple endpoints in a single task as well
@@ -27,7 +27,7 @@ General operation is as follows:
     * A``select`` statement is used, along with a ``select handler`` to wait for, and capture,
       send/receive notifications from the ``XUD_Main`` task
 
-Function Details
+Function details
 ================
 
 The available ``XUD_SetReady_`` functions for the asynchronous API are listed below.

doc/rst/basic_usage.rst

@@ -3,16 +3,16 @@
 .. _sec_basic_usage:
 
 ***********
-Basic Usage
+Basic usage
 ***********
 
-Basic use is termed to mean each endpoint runs in its own dedicated core.
-Multiple endpoints in a single core are possible, please see :ref:`sec_advanced_usage`.
+Basic use is termed to mean each endpoint runs in its own dedicated thread.
+Multiple endpoints in a single thread are possible, please see :ref:`sec_advanced_usage`.
 
-Operation is synchronous in nature: The endpoint tasks make calls to blocking functions and wait
+Operation is synchronous in nature: The endpoint tasks make calls to blocking functions and waits
 for the transfer to complete before proceeding.
 
-XUD IO Task
+XUD IO task
 ===========
 
 ``XUD_Main()`` is the main task that interfaces with the USB transceiver.
@@ -25,7 +25,7 @@ bus-powered device).
 
 .. doxygenfunction:: XUD_Main
 
-Endpoint Type Tables
+Endpoint type tables
 --------------------
 
 The endpoint type tables are arrays of type ``XUD_EpType`` and are used to inform ``lib_xud``
@@ -68,7 +68,70 @@ configuration the `VBUS` input to the device/PHY need not be present.
 ``XUD_PWR_BUS`` can be used in order to run on a self-powered board without provision for `VBUS`
 wiring to the PHY/device, but this is not advised and is not USB specification compliant.
 
-Data Transfer
+VBUS monitoring
+===============
+
+For self-powered devices it is important that ``lib_xud`` is aware of the `VBUS` state.
+This allows the device to disconnect its pull-up resistors from D+/D- and ensure the device does not
+have any voltage on the D+/D- pins when `VBUS` is not present. Compliance testing specifically
+checks for this in the `USB Back Voltage` test.
+
+.. warning::
+
+    Failure to conform to this requirement will lead to an uncompliant device and likely lead to
+    interoperability issues.
+
+USB-enabled `xcore-200` series devices have a dedicated `VBUS` pin which should be wired up as
+per the data-sheet recommendations including over-voltage protection.
+
+For increasing flexibility, `xcore.ai` series devices do not have a dedicated `VBUS` pin.
+A generic IO port/pin should be used for this purpose (with appropriate external circuitry - see
+data-sheet recommendations).
+
+``lib_xud`` makes a call to a function ``XUD_HAL_GetVBusState()`` that which should be implemented
+to match the target hardware. For example::
+
+    on tile[XUD_TILE]: in port p_vbus = XS1_PORT_1P;
+
+    unsigned int XUD_HAL_GetVBusState(void)
+    {
+        unsigned vBus;
+        p_vbus :> vBus;
+        return vBus;
+    }
+
+The function should return 1 if `VBUS` is present, otherwise 0. In the case of the example
+above, the validity of `VBUS` is directly represented by the value on port 1P, however, this
+may not be the case for all hardware implementations, it could be inverted or even require a read
+from an external IO expander, for example.
+
+.. note::
+
+   `VBUS` need not be connected if the device is wholly powered by USB i.e. a bus powered device.
+
+USB_TILE define
+===============
+
+In order that ``lib_xua`` may instantiate resources on the correct tile (typically ports) it
+requires a ``USB_TILE`` define to be set. The default value for the define is ``tile[0]`` so a
+developer only needs to set this if ``XUD_Main()`` is executing on a tile other than 0.
+
+There are two ways of setting this define, either in the application `CMakeLists.txt` for example::
+
+    set(APP_COMPILER_FLAGS -DXUD_TILE=tile[0])
+
+Or, following `XMOS` software library convention, providing a `xud_conf.h` file in the application
+codebase. This header file will be automatically detected by the build system and used by
+``lib_xud``. Example content for this header file is as follows::
+
+    #indef _XUD_CONF_H_
+    #define _XUD_CONF_H_
+
+    #define XUD_TILE tile[0]
+
+    #endif
+
+Data transfer
 =============
 
 Communication state between an endpoint client task and the XUD IO task is encapsulated in an
@@ -128,21 +191,22 @@ descriptors must be sent in typically 64 byte transactions.
 
 .. doxygenfunction:: XUD_DoSetRequestStatus
 
-Data Transfer Example
+Data transfer example
 =====================
 
 A simple endpoint task is shown below demonstrating basic data transfer to the host.
 
 .. literalinclude:: basic_usage_data_example_xc
 
-Status Reporting
+
+Status reporting
 ================
 
 An endpoint can register for "status reporting" such that bus state can be known. This is achieved
 by ORing ``XUD_STATUS_ENABLE`` into the relevant endpoint in the endpoint type table.
 
-This means that endpoints are notified of USB bus resets (and bus-speed changes). The ``lib_xud``
-access functions discussed previously (``XUD_GetBuffer``, ``XUD_SetBuffer``, etc) return
+This means that endpoints are notified of USB bus resets (and therefore bus-speed changes). The
+``lib_xud`` access functions discussed previously (``XUD_GetBuffer``, ``XUD_SetBuffer``, etc) return
 ``XUD_RES_RST`` if a USB bus reset is detected.
 
 This reset notification is important if an endpoint task is expecting alternating IN and OUT
@@ -153,7 +217,7 @@ initial OUT after a re-plug, whilst the endpoint task would hang trying to send
 The endpoint needs to know of the bus reset in order to reset its state machine.
 
 .. note::
-   Endpoint 0 **requires** this functionality to be enabled  since it deals with bi-directional
+   Endpoint 0 *requires* this functionality to be enabled  since it deals with bi-directional
    control transfers
 
 This functionality is also important for high-speed devices, since it is not guaranteed that a host
@@ -172,15 +236,15 @@ function. This will return the current bus speed as a ``XUD_BusSpeed_t`` with th
 
 .. _sec_status_reporting:
 
-Status Reporting Example
+Status reporting example
 ========================
 
 A simple endpoint task is shown below demonstrating basic data transfer to the host and bus status
 inspection.
 
 .. literalinclude:: basic_usage_status_example_xc
 
-SOF Channel
+SOF channel
 ===========
 
 An application can pass an optional channel-end to the ``c_sof`` parameter of ``XUD_Main()``.
@@ -200,8 +264,8 @@ Halting
 
 The USB specification requires the ability for an endpoint to send a `STALL` response to the host if
 an endpoint is halted, or if control pipe request is not supported. ``lib_xud`` provides
-various functions to support this.  In some cases it is easier to use the ``XUD_ep`` whilst in other
-cases it is easier to use the endpoint address.
+various functions to support this.  In some cases it is convenient to use the ``XUD_ep`` whilst in
+other cases it is easier to use the endpoint address. Functions to use either are provided.
 
 ``XUD_SetStall()``
 ------------------
@@ -225,7 +289,7 @@ cases it is easier to use the endpoint address.
 
 .. _sec_test_modes:
 
-USB Test Modes
+USB test modes
 ==============
 
 ``lib_xud`` supports the required test modes for USB Compliance testing.

doc/rst/example.rst

@@ -1,10 +1,13 @@
+
+|newpage|
+
 .. _sec_example:
 
 *******************
-Example Application
+Example application
 *******************
 
-This section contains a full worked example of implementing a USB mouse device compliant to the
+This section contains a fully worked example of implementing a USB mouse device compliant to the
 `Human Interface Device (HID) Class <https://usb.org/document-library/device-class-definition-hid-111>`_
 mouse device.
 
@@ -25,7 +28,7 @@ The full source for this application is provided along side the ``lib_xud`` soft
     The example code provides implementations in C and XC. This section concentrates on the XC
     version.
 
-Required Hardware
+Required hardware
 =================
 
 This application note is designed to run on `XMOS xcore-200` or `xcore.ai` series devices.
@@ -57,7 +60,7 @@ Since this example does not require `SOF` notifications ``null`` is passed into
 parameter. ``XUD_SPEED_HS`` is passed for the ``desiredSpeed`` parameter such that the device
 attempts to run as a high-speed device.
 
-HID Endpoint Task
+HID endpoint task
 =================
 
 This function responds to the HID requests - it moves the mouse cursor in square by moving 40
@@ -77,7 +80,7 @@ in the ``hid_mouse()`` function.
 Should processing take longer that the host IN polls, the ``XUD_Main()`` task will simply `NAK` the
 host. The ``XUD_SetBuffer()`` function will return when the packet transmission is complete.
 
-Device Descriptors
+Device descriptors
 ==================
 
 The ``USB_StandardRequests()`` function expects descriptors to be declared as arrays of characters.

doc/rst/intro.rst

@@ -7,10 +7,13 @@ USB 2.0 devices on the `XMOS xcore` architecture.
 
 This document describes the structure of the library, its basic use and resources required.
 
-This document assumes familiarity with the `XMOS xcore` architecture, the Universal Serial Bus 2.0
-Specification (and related specifications), the `XMOS` XTC tool chain and `XC` language.
+This document assumes familiarity with the `XMOS` `xcore` architecture, the Universal Serial Bus 2.0
+Specification (and related specifications), the `XMOS` XTC tool chain and XC language.
 
-This library is for use with `xcore-200` (XS2 architecture) series or `xcore.ai` (XS3 architecture)
-series devices only, previous generations of `xcore` devices (i.e. XS1 architecture) are not
+This library is for use with `xcore-200` series (XS2 architecture) or `xcore.ai` series (XS3
+architecture) devices only, previous generations of `xcore` devices (i.e. XS1 architecture) are not
 supported.
 
+``lib_xud`` is intended to be used with the `XCommon CMake <https://www.xmos.com/file/xcommon-cmake-documentation/?version=latest>`_
+, the `XMOS` application build and dependency management system.
+

doc/rst/overview.rst

@@ -5,8 +5,8 @@ Overview
 ********
 
 `xcore.ai` devices and selected `xcore-200` devices include an integrated USB transceiver.
-The XUD library allows the implementation of both full-speed and high-speed USB 2.0 devices on
-these devices.  ``lib_xud`` provides an identical API for all devices.
+``lib_xud`` allows the implementation of both full-speed and high-speed USB 2.0 devices on
+these devices.  The library provides an identical API for all devices.
 
 The library performs all of the low-level I/O operations required to meet the USB 2.0 specification.
 This processing goes up to and includes the transaction level. It removes all low-level timing

doc/rst/programming.rst

@@ -1,11 +1,12 @@
 
+|newpage|
 .. _sec_programming:
 
 *****************
-Programming Guide
+Programming guide
 *****************
 
-This section provides information on how to create an basic application using the ``lib_xud``.
+This section provides information on how to create an basic application using ``lib_xud``.
 
 Includes
 ========
@@ -63,19 +64,19 @@ application specific endpoint tasks, for example::
 (either endpoint 0 or an application specific endpoint). Application specific endpoints are
 connected using channel ends so the IN and OUT channel arrays need to be extended for each endpoint.
 
-Endpoint Addresses
+Endpoint addresses
 ==================
 
 Endpoint 0 uses index 0 of both the endpoint type table and the channel array. The address of other
 endpoints must also correspond to their index in the endpoint table and the channel array.
 
-Sending and Receiving Data
+Sending and receiving data
 ==========================
 
 An application specific endpoint can send data using ``XUD_SetBuffer()`` and receive data using
 ``XUD_GetBuffer()`` etc as described in :ref:`sec_basic_usage`.
 
-Endpoint 0 Implementation
+Endpoint 0 implementation
 =========================
 
 It is necessary to create an implementation for endpoint 0 which takes two channels, one for IN and
@@ -144,7 +145,7 @@ in full-speed mode and vice versa.
     On bus reset the ``XUD_ResetEndpoint()`` function returns the negotiated USB speed (i.e. full
     or high speed).
 
-Device Descriptors
+Device descriptors
 ==================
 
 Every USB device must provide a set of descriptors. They are used to identify the USB device’s