XMOS USB Device Library

https://github.com/xmos/lib_xud
Admin
A library providing USB device functionality for XMOS microcontrollers.
Tokens:31,204
Snippets:89
Trust Score:9
Update:1 year ago
Show doc for...
Tokens:
Raw
### main() function - main.xc

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/example.rst

Initializes the XUD device, sets up endpoint 0 and the HID endpoint task, and starts the XUD main loop. It configures the device to attempt high-speed operation.

```XC
int main() {
    xud_device_t *xud_dev;
    xud_endpoint_t *ep0;
    xud_endpoint_t *hid_ep;
    int ret;

    // Initialize XUD device
    xud_dev = xud_device_init(XUD_SPEED_HS, NULL);
    if (!xud_dev) {
        return 1;
    }

    // Endpoint 0 setup
    ep0 = xud_endpoint_alloc(XUD_EP_0, XUD_DIR_BOTH, XUD_TYPE_CONTROL, XUD_EP_MAX_PKT_SIZE_EP0);
    if (!ep0) {
        return 1;
    }

    // HID endpoint setup
    hid_ep = xud_endpoint_alloc(XUD_EP_1, XUD_DIR_IN, XUD_TYPE_BULK, XUD_EP_MAX_PKT_SIZE_BULK_HS);
    if (!hid_ep) {
        return 1;
    }

    // Register HID endpoint with its descriptor table
    ret = xud_hid_register_endpoint(xud_dev, hid_ep, hid_report_table, hid_report_table_size, hid_mouse_report_id);
    if (ret < 0) {
        return 1;
    }

    // Start XUD main loop
    xud_main(xud_dev, NULL, NULL);

    return 0;
}
```

--------------------------------

### lib_xud Main Application Structure

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/programming.rst

Outlines the main function structure for a lib_xud application. It includes channel allocation, initialization via XUD_Main, and starting the Endpoint 0 task.

```C
int main ()
{
    chan c_ep_out[XUD_EP_COUNT_OUT], c_ep_in[XUD_EP_COUNT_IN];
    par
    {
        XUD_Main(c_ep_out , XUD_EP_COUNT_OUT ,
                 c_ep_in , XUD_EP_COUNT_IN ,
                 null , epTypeTableOut , epTypeTableIn ,
                 null , null , null , XUD_SPEED_HS , null);

        Endpoint0(c_ep_out[0], c_ep_in[0]);

        // Application specific endpoints
        ...
    }
}
return 0;
```

--------------------------------

### lib_xud Endpoint 0 Initialization and Main Loop

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/programming.rst

Demonstrates the initialization of endpoint 0 channels using XUD_InitEp and the main processing loop. This loop handles USB setup packets, standard requests, and bus resets.

```C
void Endpoint0(chanend chan_ep0_out , chanend chan_ep0_in , chanend ?c_usb_test)
{
    XUD_ep ep0_out = XUD_InitEp(chan_ep0_out);
    XUD_ep ep0_in = XUD_InitEp(chan_ep0_in);

    while (1)
    {
        /* Returns XUD_RES_OKAY on success, XUD_RES_RST for USB reset */
        XUD_Result_t result = USB_GetSetupPacket(ep0_out , ep0_in , sp);

        if(result == XUD_RES_OKAY)
        {
            switch(sp.bmRequestType.Type)
            {
                case BM_REQTYPE_TYPE_CLASS:
                    switch(sp.bmRequestType.Receipient)
                    {
                        case BM_REQTYPE_RECIP_INTER:
                            // Optional class specific requests
                            break;

                        ...
                    }

                    break;
                ...
            }

            result = USB_StandardRequests(ep0_out , devDesc , devDescLen , ...);
        }

        if(result == XUD_RES_RST)
            usbBusSpeed = XUD_ResetEndpoint(ep0_out , ep0_in);
    }
}
```

--------------------------------

### Setup Environment for Lib_xud

Source: https://github.com/xmos/lib_xud/blob/develop/tests/README.rst

Commands to set up the development environment. This involves sourcing a setup script and building/installing project dependencies.

```shell
source ./SetupEnv
```

```perl
./Build.pl build install
```

--------------------------------

### Descriptor Structures and Setup Buffer

Source: https://github.com/xmos/lib_xud/blob/develop/CHANGELOG.rst

Introduces new descriptor structures and a utility function for creating setup buffers, enhancing USB class support, particularly for Audio Class.

```APIDOC
Descriptor Structures:
  Description: Various descriptor structures added, particularly for Audio Class.
  Notes: Enhances USB class compliance and functionality.
```

```APIDOC
ComposeSetupBuffer():
  Parameters:
    - Input: USB_Setup_Packet_t
  Description: Creates a buffer from a USB_Setup_Packet_t.
  Notes: Facilitates easier setup packet handling.
```

--------------------------------

### Configuration Descriptor (C)

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/example.rst

The configuration descriptor defines a device's features and abilities, including interface and endpoint descriptors. This snippet shows an example configuration descriptor.

```c
#include "usb_types.h"

const uint8_t cfgDesc[] = {
    // Configuration descriptor structure...
};

```

--------------------------------

### Declarations - main.xc

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/example.rst

Includes the necessary header files and defines endpoint type tables for the USB HID mouse application.

```XC
#include <xud_device.h>
#include <xud_hid.h>
#include <xud_cdc.h>
#include <xud_vendor.h>
#include <xud_class.h>
#include <xud_debug.h>

#include "hid_descs.h"

#define EP_TYPE_TABLE_SIZE 1

static const unsigned char epTypeTableIn[EP_TYPE_TABLE_SIZE] = { XUD_EP_TYPE_BULK };
```

--------------------------------

### XUD Configuration Header

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/basic_usage.rst

Example content for the `xud_conf.h` file, which is automatically detected by the build system to configure lib_xud. This file allows customization of USB tile selection.

```C
#ifndef _XUD_CONF_H_
#define _XUD_CONF_H_

#define USB_TILE tile[1]

#endif
```

--------------------------------

### XUD Build System and Example Changes

Source: https://github.com/xmos/lib_xud/blob/develop/CHANGELOG.rst

Updates related to the build system and example applications for lib_xud.

```APIDOC
Build System:
  - Examples now build using xcommon-cmake (previously xcommon).
  - Added support for XCommon CMake build system.

Example Applications:
  - AN00129 is now the main library usage example, renamed from app_hid_mouse.
  - Several application notes (AN00124, AN00125, AN00126, AN00127, AN00131, AN00132, AN00135, AN00136) have been removed and are maintained separately.
```

--------------------------------

### USB_GetSetupPacket() Helper Function

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/control_eps.rst

A helper function that calls the low-level XUD function XUD_GetSetupBuffer() to retrieve an 8-byte Setup packet. It then parses this packet into a USB_SetupPacket_t structure for further inspection by the endpoint 0 handler.

```C
/*
 * USB_GetSetupPacket()
 * 
 * Description:
 *   Retrieves and parses a USB setup packet.
 * 
 * Parameters:
 *   setup_packet: Pointer to a USB_SetupPacket_t structure to be populated.
 * 
 * Returns:
 *   XUD_RES_OKAY on success, XUD_RES_ERR on failure.
 */
// XUD_GetSetupBuffer() is called internally to get the raw packet.
// The function populates the provided USB_SetupPacket_t structure.
// See Universal Serial Bus 2.0 specification for Setup packet structure details.
```

--------------------------------

### String Descriptors (C)

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/example.rst

An array of strings referenced by other descriptors. Index 0 must contain the Language ID Descriptor. This snippet shows the string table for the HID mouse example.

```c
#include "usb_types.h"

const uint8_t *stringDescriptors[] = {
    // Language ID Descriptor
    // Manufacturer String
    // Product String
    // Serial Number String
};

```

--------------------------------

### Install Pytest for Testing

Source: https://github.com/xmos/lib_xud/blob/develop/tests/README.rst

Installs the pytest framework, which is used for running automated tests. This is a prerequisite for executing the test suite.

```python
pip install pytest
```

--------------------------------

### Endpoint 0 Task and HID Requests Handling (C)

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/example.rst

The complete code listing for the main endpoint 0 task, including the handling of HID interface class requests. This demonstrates the integration of custom request handling with standard USB functions.

```c
// Main endpoint 0 task
void Endpoint0() {
    // ... implementation ...
}

// Skeleton function for HID interface class requests
// Handles any outstanding HID requests.
// Returns XUD_RES_ERR if the request is not handled.
int HidInterfaceClassRequests() {
    // ... implementation ...
    return XUD_RES_ERR; // Example return if not handled
}

```

--------------------------------

### Device descriptor - hid_descs.h

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/example.rst

Defines the USB device descriptor, providing essential information about the device to the host during enumeration, including USB version, vendor ID, and class information.

```XC
static const unsigned char devDesc[] = {
    0x12, /* bLength */
    0x01, /* bDescriptorType */
    0x10, 0x01, /* bcdUSB */
    0x00, /* bDeviceClass */
    0x00, /* bDeviceSubClass */
    0x00, /* bDeviceProtocol */
    XUD_EP_MAX_PKT_SIZE_EP0, /* bMaxPacketSize0 */
    0x00, 0x12, /* idVendor */
    0x00, 0x00, /* idProduct */
    0x00, 0x01, /* bcdDevice */
    0x01, /* iManufacturer */
    0x02, /* iProduct */
    0x03, /* iSerialNumber */
    0x01  /* bNumConfigurations */
};
```

--------------------------------

### Configure lib_xud Project Build

Source: https://github.com/xmos/lib_xud/blob/develop/examples/CMakeLists.txt

Sets up the CMake build environment for the lib_xud project. It specifies the minimum required CMake version, includes common CMake modules from an environment path, defines the project name, and adds subdirectories for building specific examples like the HID mouse application.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)
project(lib_xud_examples)

# Main example
add_subdirectory(app_hid_mouse)
```

--------------------------------

### lib_xud Project CMakeLists.txt Setup

Source: https://github.com/xmos/lib_xud/blob/develop/examples/app_hid_mouse/CMakeLists.txt

This CMakeLists.txt file configures the build for the lib_xud project. It specifies the minimum CMake version, includes common XMOS modules, defines the project name, target hardware, compiler flags for C and XC, source files, dependencies, and registers the application using XMOS-specific macros.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)
project(app_hid_mouse)

set(APP_HW_TARGET XK-EVK-XU316)

set(APP_INCLUDES src)

# Setup two build configurations, one called "c", the other "xc"
set(APP_COMPILER_FLAGS_c -g -O3 -report -fxscope)
set(APP_COMPILER_FLAGS_xc -g -O3 -report -fxscope)

# Setup different source files for the two build configurations
set(SOURCE_FILES_c src/main.c)
set(SOURCE_FILES_xc src/main.xc)

set (APP_DEPENDENT_MODULES    "lib_xud")

set(XMOS_SANDBOX_DIR ${CMAKE_CURRENT_LIST_DIR}/../../..)

XMOS_REGISTER_APP()
```

--------------------------------

### Asynchronous High Bandwidth ISO Transfer Example

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/high_bandwidth_endpoints.rst

Demonstrates initiating and polling high bandwidth isochronous transfers asynchronously using lib_xud functions. It shows setting up IN and OUT endpoints, preparing buffers, and handling transfer completion events.

```c
#include "xud.h"

void ExampleEndpoint(chanend c_ep_out, chanend c_ep_in)
{
    unsigned char rxBuffer[3 * XUD_USB_ISO_EP_MAX_TXN_SIZE];
    const int IN_TRANSFER_SIZE = XUD_USB_ISO_EP_MAX_TXN_SIZE + 100; /* Example size to demostrate transfer spanning 2 transactions*/
    unsigned char txBuffer[IN_TRANSFER_SIZE];
    for(int i = 0; i < IN_TRANSFER_SIZE; i++)
    {
        txBuffer[i] = i % 256; // Example data to send
    }

    int length, result;

    XUD_ep ep_out = XUD_InitEp(c_ep_out);
    XUD_ep ep_in = XUD_InitEp(c_ep_in);

    /* Mark OUT endpoint as ready to receive */
    XUD_SetReady_Out(ep_out, rxBuffer);

    /* Mark IN endpoint as ready to send */
    XUD_SetReady_In(ep_in, txBuffer, sizeof(txBuffer));

    while(1)
    {
        select
        {
            case XUD_GetData_Select(c_ep_out, ep_out, length, result):
                if(result != XUD_RES_WAIT)
                {
                    /* Process received packet */
                    for(int i = 0; i < length; i++)
                    {
                        // Process packet...
                    }
                    /* Mark EP as ready again */
                    XUD_SetReady_Out(ep_out, rxBuffer);
                }
                break;

            case XUD_SetData_Select(c_ep_in, ep_in, result):
                if (result != XUD_RES_WAIT)
                {
                    // Handle IN transfer completion
                }
                break;
        }
    }
}
```

--------------------------------

### HID endpoint task - main.xc

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/example.rst

Handles HID reports for the mouse, moving the cursor in a square pattern. It performs IN transactions and does not check for status data.

```XC
void hid_mouse(xud_endpoint_t *ep, void *arg) {
    static int count = 0;
    static int state = 0;
    static unsigned char mouse_report[4] = { 0x01, 0x00, 0x00, 0x00 }; // Report ID, Button, X, Y

    count++;

    if (count >= 100) {
        count = 0;
        switch (state) {
            case 0: // Move right
                mouse_report[2] = 40;
                mouse_report[3] = 0;
                state = 1;
                break;
            case 1: // Move down
                mouse_report[2] = 0;
                mouse_report[3] = 40;
                state = 2;
                break;
            case 2: // Move left
                mouse_report[2] = -40;
                mouse_report[3] = 0;
                state = 3;
                break;
            case 3: // Move up
                mouse_report[2] = 0;
                mouse_report[3] = -40;
                state = 0;
                break;
        }

        // Send the mouse report
        xud_endpoint_write(ep, mouse_report, sizeof(mouse_report));
    }
}
```

--------------------------------

### HID Class Specific Requests (APIDOC)

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/example.rst

Handles application and class-specific USB requests beyond standard enumeration. For HID devices like mice, mandatory requests include GET_DESCRIPTOR (for HID and REPORT descriptors) and GET_REPORT. The HID report descriptor informs the host about the content of HID reports.

```APIDOC
USB HID Class Specific Requests:

1. GET_DESCRIPTOR:
   - HID: Return the HID descriptor.
   - REPORT: Return the HID report descriptor.

2. GET_REPORT:
   - Return the HID report data.

Implementation Notes:
- These requests should be handled before calling USB_StandardRequests().
- The programmer can choose to fully handle a request or partially handle it and then call USB_StandardRequests().
- If a request is not handled by the application, it may result in a STALL response to the host.

Related Functions:
- USB_StandardRequests(): Handles standard USB requests.
- HidInterfaceClassRequests(): Skeleton function to deal with outstanding HID requests.

Error Conditions:
- XUD_RES_ERR: Returned by HidInterfaceClassRequests() if the HID request is not handled.

Resources:
- HID Class Specification and related documentation for full request details.
- USB HID Descriptor Tool for building HID report descriptors.
```

--------------------------------

### lib_xud Data Transfer Functions

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/basic_usage.rst

Functions for initializing endpoints and managing data buffers for USB communication. Includes functions for setting, getting, and managing data packets, including maximum packet size handling and request processing. These functions abstract low-level complications like Packet ID toggling.

```APIDOC
XUD_InitEp(chanend ep_chan)
  - Initializes an endpoint by taking the endpoint channel as an argument.
  - Parameters:
    - ep_chan: The endpoint channel connected to the XUD library.

XUD_SetBuffer(XUD_ep ep, void *data, int len)
  - Sends data to the host. This function implements low-level shared memory/channel communication.
  - Parameters:
    - ep: The opaque endpoint type representing the communication state.
    - data: Pointer to the data buffer to send.
    - len: The length of the data buffer.
  - Returns: Status indicating success or failure.

XUD_GetBuffer(XUD_ep ep, void *data, int len)
  - Receives data from the host. This function implements low-level shared memory/channel communication.
  - Parameters:
    - ep: The opaque endpoint type representing the communication state.
    - data: Pointer to the buffer where received data will be stored.
    - len: The maximum length of data to receive.
  - Returns: Status indicating success or failure, and the amount of data received.

XUD_GetSetupBuffer(XUD_ep ep, void *data, int len)
  - Receives USB setup data from the host. This function implements low-level shared memory/channel communication.
  - Parameters:
    - ep: The opaque endpoint type representing the communication state.
    - data: Pointer to the buffer where setup data will be stored.
    - len: The maximum length of setup data to receive.
  - Returns: Status indicating success or failure, and the amount of setup data received.

XUD_SetBuffer_EpMax(XUD_ep ep, void *data, int len)
  - Similar to XUD_SetBuffer but breaks data into packets of a fixed maximum size (e.g., 64 bytes).
  - Useful for control transfers with large descriptors.
  - Parameters:
    - ep: The opaque endpoint type representing the communication state.
    - data: Pointer to the data buffer to send.
    - len: The length of the data buffer.
  - Returns: Status indicating success or failure.

XUD_DoGetRequest(XUD_ep ep, void *data, int len)
  - Handles GET requests from the host.
  - Parameters:
    - ep: The opaque endpoint type representing the communication state.
    - data: Pointer to the buffer for the GET request data.
    - len: The length of the data buffer.
  - Returns: Status indicating success or failure.

XUD_DoSetRequestStatus(XUD_ep ep, void *data, int len)
  - Handles SET request status from the host.
  - Parameters:
    - ep: The opaque endpoint type representing the communication state.
    - data: Pointer to the buffer for the SET request status data.
    - len: The length of the data buffer.
  - Returns: Status indicating success or failure.
```

--------------------------------

### lib_xud Endpoint Type Table Declaration

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/programming.rst

Declares arrays for IN and OUT endpoint types, including control and bulk endpoints. XUD_STATUS_ENABLE is used to signal bus resets to endpoints.

```C
/* Endpoint type tables */
XUD_EpType epTypeTableOut[] = {XUD_EPTYPE_CTL | XUD_STATUS_ENABLE};
XUD_EpType epTypeTableIn[] = {XUD_EPTYPE_CTL | XUD_STATUS_ENABLE , XUD_EPTYPE_BUL};
```

--------------------------------

### Launch Application with xrun

Source: https://github.com/xmos/lib_xud/blob/develop/examples/app_hid_mouse/doc/rst/AN00129.rst

Downloads and executes the compiled application binary (.xe file) on the xcore device using the xrun tool. This command initiates the HID mouse functionality on the host machine.

```shell
xrun app_hid_mouse.xe
```

--------------------------------

### Build Application with xmake

Source: https://github.com/xmos/lib_xud/blob/develop/examples/app_hid_mouse/doc/rst/AN00129.rst

Builds the application binary (.xe file) using the xmake command. The compiled output, including the executable, is placed in the 'bin' directory within the build output.

```shell
xmake -C build
```

--------------------------------

### Development Python Dependencies

Source: https://github.com/xmos/lib_xud/blob/develop/tests/requirements.txt

Details Python packages installed in editable mode, typically pointing to local development paths. This is used when the project depends on other Python code under active development.

```python-requirements
-e ./../../test_support
```

--------------------------------

### Configure Build with CMake

Source: https://github.com/xmos/lib_xud/blob/develop/examples/app_hid_mouse/doc/rst/AN00129.rst

Configures the application build using xcommon-cmake. This step ensures all necessary dependencies are downloaded and the build system is set up correctly for the target environment.

```shell
cd AN00129_hid_class
cmake -G "Unix Makefiles" -B build
```

--------------------------------

### USB_TILE Define for Resource Placement

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/basic_usage.rst

A compiler define required by `lib_xud` to instantiate resources, typically ports, on the correct tile. The default value is `tile[0]`, but it must be set if `XUD_Main()` executes on a different tile.

```APIDOC
USB_TILE define
  - Required by `lib_xud` to instantiate resources on the correct tile.
  - Typically used for port instantiation.
  - Default value: `tile[0]`.
  - Set this define if `XUD_Main()` executes on a tile other than 0.

Example CMakeLists.txt setting:
  set(APP_COMPILER_FLAGS -DUSB_TILE=tile[1])
```

--------------------------------

### Timing Analysis Script Usage

Source: https://github.com/xmos/lib_xud/blob/develop/tests/xta-xud/README.rst

Demonstrates how to execute the timing analysis script (xta.py) against a compiled binary file. The script analyzes the timing behavior of lib_xud by examining specific labels within the binary.

```bash
python3 xta.py ../../examples/app_hid_mouse/bin/xc/app_hid_mouse_xc.xe
```

--------------------------------

### XUD_Main Task Initialization

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/basic_usage.rst

The main task that interfaces with the USB transceiver, handling connection, handshaking, bus states, and packet passing. It should be called from the top-level `par` statement in `main()` to meet USB specification timing requirements.

```APIDOC
XUD_Main()
  - The main task that interfaces with the USB transceiver.
  - Performs connection and handshaking on the USB bus as well as other bus-states such as suspend and resume.
  - Handles passing packets to/from the various endpoints.
  - Should be called directly from the top-level `par` statement in `main()` to ensure the XUD library is ready within the 100ms allowed by the USB specification.
```

--------------------------------

### Include lib_xud Header File

Source: https://github.com/xmos/lib_xud/blob/develop/examples/app_hid_mouse/doc/rst/AN00129.rst

Demonstrates how to include the main header file for the lib_xud library in your C/C++ source code. This provides access to the library's functions and definitions.

```c
#include "xud_device.h"
```

--------------------------------

### USB_StandardRequests() Function

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/control_eps.rst

Provides a minimum implementation for mandatory USB Standard Device Requests required for device enumeration and configuration. It inspects a USB_SetupPacket_t structure and handles common requests like GET_DESCRIPTOR, SET_ADDRESS, and SET_CONFIGURATION.

```APIDOC
USB_StandardRequests(USB_SetupPacket_t *setup_packet, const uint8_t *device_descriptor, const uint8_t *configuration_descriptor, const char **string_table, uint32_t bus_speed)

  Description:
    Handles standard USB requests for device enumeration and configuration.
    It inspects the provided setup_packet and uses descriptor arrays and string tables to respond.
    It can form Device Qualifier and Other Speed Configuration descriptors based on bus-speed.

  Parameters:
    setup_packet: Pointer to the parsed USB_SetupPacket_t structure.
    device_descriptor: Pointer to the device descriptor array.
    configuration_descriptor: Pointer to the configuration descriptor array.
    string_table: Pointer to an array of strings for device strings.
    bus_speed: The current bus speed of the USB device.

  Returns:
    XUD_RES_OKAY if the request was handled successfully.
    XUD_RES_ERR if the request was not handled or an error occurred.
    The function may stall endpoints using XUD_SetStall_Out() and XUD_SetStall_In() for unhandled requests.

  Handled Standard Device Requests:
    - SET_ADDRESS: Sets the device address using XUD_SetDevAddr().
    - SET_CONFIGURATION: Updates a global variable with the configuration value.
    - GET_STATUS: Returns device status, including bus-powered information derived from the configuration descriptor.
    - GET_CONFIGURATION: Returns the last set configuration value.
    - GET_DESCRIPTOR: Returns requested descriptors (DEVICE, CONFIGURATION, DEVICE_QUALIFIER, OTHER_SPEED_CONFIGURATION, STRING).
      Descriptor content may vary based on the current bus speed.

  Handled Test Mode Requests:
    - SET_FEATURE:
      - TEST_J
      - TEST_K
      - TEST_SE0_NAK
      - TEST_PACKET
    These requests set the correct test mode in XUD.

  Limitations:
    This function provides a bare-minimum implementation. It does not have knowledge of specific device classes and may require overriding for specialized functionality (e.g., SET_INTERFACE for audio streaming).

  Related Functions:
    - XUD_SetStall_Out(): Stalls the OUT endpoint.
    - XUD_SetStall_In(): Stalls the IN endpoint.
    - XUD_SetDevAddr(): Sets the device address in the XUD controller.
```

--------------------------------

### XUD Device Support and Optimizations

Source: https://github.com/xmos/lib_xud/blob/develop/CHANGELOG.rst

Information on supported devices, optimizations for specific hardware, and resolution of device-specific issues.

```APIDOC
Device Support:
  - Initial support for XS3A based devices added.
  - Removed support for XS1-G, and XS1-L (including U series) based devices.

Optimizations:
  - Optimized port timings for XS3A to use non-inverted clock.
  - Instruction-level (speed) optimizations applied.
  - Various optimizations to aid corner-case timings on XS3 based devices.

Device-Specific Fixes:
  - RX_RISE_DELAY adjusted for XS2A based devices to resolve intermittent transmit timing issues.
  - XS3A based devices not responding to IN packets in SE0_NAK test mode fixed.
  - Intermittent enumeration issues at full-speed on XS3A based devices resolved.
```

--------------------------------

### lib_xud Build Configuration Defines

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/options.rst

Defines that configure the behavior of the lib_xud library during the build process. These options allow customization of features like oscillator frequency, suspend behavior, and USB transaction sizes.

```c
#define XUD_OSC_MHZ
// Configures the oscillator frequency in MHz.
```

```c
#define XUD_SUSPEND_PHY
// Enables or configures PHY suspend functionality.
```

```c
#define XUD_USB_ISO_MAX_TXNS_PER_MICROFRAME
// Sets the maximum number of transactions per microframe for USB Isochronous endpoints.
```

```c
#define XUD_USB_ISO_EP_MAX_TXN_SIZE
// Defines the maximum transaction size for USB Isochronous endpoints.
```

--------------------------------

### USB HID Configuration Descriptor

Source: https://github.com/xmos/lib_xud/blob/develop/examples/app_hid_mouse/doc/rst/AN00129.rst

Defines the USB configuration descriptor for a HID class device. This descriptor is read by the host and includes the bulk USB endpoint description for HID mouse reporting.

```xc
/* Configuration Descriptor
 * This descriptor is read by the host when the device enumerates.
 */
const unsigned char cfgDesc[] = {
    /* Configuration Descriptor */
    0x09, /* bLength */
    0x02, /* bDescriptorType */
    0x29, 0x00, /* wTotalLength */
    0x01, /* bNumInterfaces */
    0x01, /* bConfigurationValue */
    0x00, /* iConfiguration */
    0x80, /* bmAttributes (Bus Powered) */
    0x32, /* bMaxPower (100mA) */

    /* Interface Descriptor */
    0x09, /* bLength */
    0x04, /* bDescriptorType */
    0x00, /* bInterfaceNumber */
    0x00, /* bAlternateSetting */
    0x01, /* bNumEndpoints */
    0x03, /* bInterfaceClass (HID) */
    0x01, /* bInterfaceSubClass (Boot Interface) */
    0x01, /* bInterfaceProtocol (Mouse) */
    0x00, /* iInterface */

    /* HID Descriptor */
    0x09, /* bLength */
    0x21, /* bDescriptorType (HID) */
    0x11, 0x01, /* bcdHID (1.11) */
    0x00, /* bCountryCode */
    0x01, /* bNumDescriptors */
    0x22, /* bDescriptorType (Report) */
    0x34, 0x00, /* wDescriptorLength (52 bytes) */

    /* Endpoint Descriptor */
    0x07, /* bLength */
    0x05, /* bDescriptorType */
    0x81, /* bEndpointAddress (IN endpoint 1) */
    0x03, /* bmAttributes (Interrupt Transfer) */
    0x08, 0x00, /* wMaxPacketSize (8 bytes) */
    0x0a, /* bInterval (10ms) */
};
```

--------------------------------

### Code Labeling Conventions for Analysis

Source: https://github.com/xmos/lib_xud/blob/develop/tests/xta-xud/README.rst

Defines the required labels that must be present in the source code or binary for the timing analysis script to function correctly. These labels mark the start/end of the analyzed code, endpoints, and control flow targets.

```text
xta_start
# Marks the beginning of the Low-Level Driver (LLD) code to be analyzed.

xta_end
# Marks the end of the LLD code to be analyzed.

xta_ep_LABEL
# Labels an endpoint (input or output instruction) with a specific name (LABEL) for constraint definition.

xta_no_pauseX
# An alternative label for endpoints, where X is a unique value, used when a specific LABEL is not desired.

xta_targetX_DESTINATION_LABEL
# Labels a control flow change (e.g., bru, bau, retsp) to a specific destination. X makes the label unique, and DESTINATION_LABEL is the target address.
```

--------------------------------

### Main Application Function (main.xc)

Source: https://github.com/xmos/lib_xud/blob/develop/examples/app_hid_mouse/doc/rst/AN00129.rst

The main function of the USB HID mouse application. It initializes and runs three core tasks: USB library communication, Endpoint0 handling, and custom HID interface logic. It also configures the USB library for high-speed mode and self-powered operation.

```c
int main
{
    // Setup xCONNECT channels for inter-task communication
    chan_usb_rx_cmd, chan_usb_tx_cmd, chan_usb_rx_data, chan_usb_tx_data;

    // Run the USB library task
    par {
        XUD_Main(chan_usb_rx_cmd, chan_usb_tx_cmd, chan_usb_rx_data, chan_usb_tx_data, XUD_SPEED_HS, XUD_PWR_SELF);
    }

    // Run the Endpoint0 task
    par {
        Endpoint0(chan_usb_rx_cmd, chan_usb_tx_cmd, chan_usb_rx_data, chan_usb_tx_data);
    }

    // Run the HID mouse application task
    par {
        hid_mouse(chan_usb_rx_cmd, chan_usb_tx_cmd, chan_usb_rx_data, chan_usb_tx_data);
    }

    // All tasks run on tile[0]
    // ... (rest of the main function logic)
}
```

--------------------------------

### USB Endpoint Stall Control

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/basic_usage.rst

Provides functions to manage the stall condition for USB endpoints, allowing the device to respond to the host when an endpoint is halted or a control pipe request is unsupported. Supports both endpoint objects and addresses.

```APIDOC
XUD_SetStall(endpoint)
  - Sets the stall condition for a specified USB endpoint.
  - Parameters:
    - endpoint: The endpoint object to stall.
  - Returns: Void.
  - Related: XUD_SetStallByAddr, XUD_ClearStall, XUD_ClearStallByAddr

XUD_SetStallByAddr(endpoint_address)
  - Sets the stall condition for a USB endpoint identified by its address.
  - Parameters:
    - endpoint_address: The address of the endpoint to stall.
  - Returns: Void.
  - Related: XUD_SetStall, XUD_ClearStall, XUD_ClearStallByAddr

XUD_ClearStall(endpoint)
  - Clears the stall condition for a specified USB endpoint.
  - Parameters:
    - endpoint: The endpoint object to clear the stall condition from.
  - Returns: Void.
  - Related: XUD_ClearStallByAddr, XUD_SetStall, XUD_SetStallByAddr

XUD_ClearStallByAddr(endpoint_address)
  - Clears the stall condition for a USB endpoint identified by its address.
  - Parameters:
    - endpoint_address: The address of the endpoint to clear the stall condition from.
  - Returns: Void.
  - Related: XUD_ClearStall, XUD_SetStall, XUD_SetStallByAddr
```

--------------------------------

### USB Endpoint 0 Task

Source: https://github.com/xmos/lib_xud/blob/develop/examples/app_hid_mouse/doc/rst/AN00129.rst

Manages device requests made to the standard endpoint 0. It handles both standard USB device requests and requests specific to the HID class.

```xc
/* Endpoint 0 Task
 * Handles all device requests on endpoint 0.
 */
void Endpoint0(void)
{
    /* Endpoint 0 Task */
    while (1)
    {
        /* Wait for a SETUP packet */
        usb_wait_for_setup_packet();

        /* Process the SETUP packet */
        switch (Setup.bmRequestType & USB_BM_REQUEST_TYPE_MASK)
        {
            case USB_BM_REQUEST_TYPE_STANDARD:
                /* Handle standard requests */
                break;
            case USB_BM_REQUEST_TYPE_CLASS:
                /* Handle class-specific requests */
                if ((Setup.bmRequestType & USB_BM_REQUEST_RECIPIENT_MASK) == USB_BM_REQUEST_RECIPIENT_INTERFACE)
                {
                    if (HidInterfaceClassRequests() < 0)
                    {
                        /* Stall endpoint if request is not handled */
                        usb_stall_endpoint(0);
                    }
                }
                else
                {
                    /* Stall endpoint for other class recipients */
                    usb_stall_endpoint(0);
                }
                break;
            case USB_BM_REQUEST_TYPE_VENDOR:
                /* Handle vendor-specific requests */
                break;
            default:
                /* Stall endpoint for unknown request types */
                usb_stall_endpoint(0);
                break;
        }
        /* Clear the SETUP packet */
        usb_clear_setup_packet();
    }
}
/* Endpoint0 */
```

--------------------------------

### USB HID Report Descriptor

Source: https://github.com/xmos/lib_xud/blob/develop/examples/app_hid_mouse/doc/rst/AN00129.rst

Describes the usage of the HID device and the data it reports. This allows for configuration flexibility between the host and the device, enabling standard driver support.

```xc
/* HID Report Descriptor
 * Describes the device usage and data format.
 */
const unsigned char hidReportDesc[] = {
    0x05, 0x01, /* Usage Page (Generic Desktop) */
    0x09, 0x02, /* Usage (Mouse)
    0xa1, 0x01, /* Collection (Application)
        0x09, 0x01, /* Usage (Pointer)
        0xa1, 0x00, /* Collection (Physical)
            0x05, 0x09, /* Usage Page (Button) */
            0x19, 0x01, /* Usage Minimum (Button 1) */
            0x29, 0x03, /* Usage Maximum (Button 3) */
            0x15, 0x01, /* Logical Minimum (0) */
            0x25, 0x01, /* Logical Maximum (1) */
            0x95, 0x03, /* Report Count (3) */
            0x75, 0x01, /* Report Size (1) */
            0x81, 0x02, /* Input (Data, Var, Abs) */
            0x95, 0x01, /* Report Count (1) */
            0x75, 0x05, /* Report Size (5) */
            0x81, 0x03, /* Input (Cnst, Var, Abs) */
            0x05, 0x01, /* Usage Page (Generic Desktop) */
            0x09, 0x30, /* Usage (X) */
            0x09, 0x31, /* Usage (Y) */
            0x15, 0x81, /* Logical Minimum (-127) */
            0x25, 0x7f, /* Logical Maximum (127) */
            0x75, 0x08, /* Report Size (8) */
            0x95, 0x02, /* Report Count (2) */
            0x81, 0x06, /* Input (Data, Rel) */
        0xc0, /* End Collection */
    0xc0, /* End Collection */
};
```

--------------------------------

### Timing Constraints File Format

Source: https://github.com/xmos/lib_xud/blob/develop/tests/xta-xud/README.rst

Specifies the format for the timing constraints file used by the analysis script. This file defines timing requirements between different labeled endpoints within the analyzed code.

```text
FLOATING_POINT_VALUE ns
# Sets the maximum allowed time in nanoseconds for subsequent endpoint pairs.

{ENDPOINT1} {ENDPOINT2}
# Constrains the time from ENDPOINT1 to ENDPOINT2 to the last specified nanosecond value.
# All other data is ignored.
```

--------------------------------

### Handle XUD Transfer Results and Prepare Data

Source: https://github.com/xmos/lib_xud/blob/develop/doc/rst/high_bandwidth_endpoints.rst

This snippet demonstrates handling the result of a USB XUD transfer. It includes logic for error conditions, such as retrying a transfer, and for successful transfers, where it prepares the next packet with incremented data before setting the endpoint as ready.

```c
if (result == XUD_RES_ERROR)
{
    /* Handle error, e.g., retry */
    XUD_SetReady_In(ep_in, txBuffer, sizeof(txBuffer));
}
else
{
    /* Packet successfully sent to host */
    // Prepare next packet...
    for(int i = 0; i < IN_TRANSFER_SIZE; i++)
    {
        txBuffer[i] = (txBuffer[i]+1) % 256; // Example data to send
    }
    XUD_SetReady_In(ep_in, txBuffer, sizeof(txBuffer));
}
```

--------------------------------

### USB HID Class Requests Handling

Source: https://github.com/xmos/lib_xud/blob/develop/examples/app_hid_mouse/doc/rst/AN00129.rst

Implements the handling of USB HID class-specific requests made from the host to the device. These requests are not part of the standard requests required by all device classes.

```xc
/* HID Class Requests Handling
 * Handles device class specific requests.
 */
int HidInterfaceClassRequests(void)
{
    int ret = 0;
    switch (Setup.bRequest)
    {
        case GET_REPORT:
            /* Handle GET_REPORT request */
            break;
        case GET_IDLE:
            /* Handle GET_IDLE request */
            break;
        case GET_PROTOCOL:
            /* Handle GET_PROTOCOL request */
            break;
        case SET_REPORT:
            /* Handle SET_REPORT request */
            break;
        case SET_IDLE:
            /* Handle SET_IDLE request */
            break;
        case SET_PROTOCOL:
            /* Handle SET_PROTOCOL request */
            break;
        default:
            /* Unknown HID request */
            ret = -1;
            break;
    }
    return ret;
}
/* HidInterfaceClassRequests */
```

--------------------------------

### USB HID Device Product Defines (hid_defs.h)

Source: https://github.com/xmos/lib_xud/blob/develop/examples/app_hid_mouse/doc/rst/AN00129.rst

Defines essential USB identifiers for the HID device, including Vendor ID (VID), Product ID (PID), and Device Version Number. These values are crucial for the host machine to recognize and identify the specific USB device.

```c
/* USB HID Device Product Defines
 * Vendor ID, Product ID and Device Version Number
 */
#define USB_VID                 (0x1234)
#define USB_PID                 (0x5678)
#define USB_VERSION             (0x0001)

/* Device Descriptor
 * Standard USB device descriptor structure
 */
const unsigned char devDesc[] = {
    // ... descriptor data ...
}
```

--------------------------------

### USB String Descriptors

Source: https://github.com/xmos/lib_xud/blob/develop/examples/app_hid_mouse/doc/rst/AN00129.rst

Holds strings for the device, including manufacturer and product strings referenced by the device descriptor. The string at index 0 must be the Language ID Descriptor.

```xc
/* String Descriptors
 * Holds device strings like manufacturer and product.
 */
const unsigned char stringDescriptors[][USB_MAX_STRING_LEN] = {
    /* String 0: Language ID Descriptor */
    { 0x04, 0x03, 0x09, 0x04 }, /* English (US) */

    /* String 1: Manufacturer String */
    { 0x12, 0x03, 'X', 0x00, 'M', 0x00, 'O', 0x00, 'S', 0x00, ' ', 0x00, 'L', 0x00, 'T', 0x00, 'D', 0x00 },

    /* String 2: Product String */
    { 0x1a, 0x03, 'X', 0x00, 'M', 0x00, 'O', 0x00, 'S', 0x00, ' ', 0x00, 'H', 0x00, 'I', 0x00, 'D', 0x00, ' ', 0x00, 'M', 0x00, 'o', 0x00, 'u', 0x00, 's', 0x00, 'e', 0x00 },

    /* String 3: Serial Number String */
    { 0x08, 0x03, '1', 0x00, '2', 0x00, '3', 0x00, '4', 0x00 }
};
```
Tokens:
Raw