usb
Vitis Drivers API Documentation
usb Documentation

This file contains the implementation of the XUsb component. It is the driver for the USB device controller.

The USB device controller supports the following features:

  • USB 2.0 Specification supporting High/Full/Low Speed
  • 8 Endpoints
    • 1 Control Endpoint
    • 7 Configurable Endpoints, which can be configured as IN or OUT , and configurable as Interrupt or Bulk or Isochronous
  • 2 Ping Pong Buffers for all the endpoints except the Control Endpoint

Initialization & Configuration

The device driver enables higher layer software (e.g., an application) to communicate to the USB device. Apart from transmission and reception of USB frames the driver also handles the configuration of the device. A single device driver can support multiple USB devices.

XUsb_CfgInitialize() API is used to initialize the USB device. The user needs to first call the XUsb_LookupConfig() API which returns the Configuration structure pointer which is passed as a parameter to the XUsb_CfgInitialize() API.

  • Configuration of the DEVICE endpoints: The endpoints of the device need to be configured using the XUsb_EpConfigure() function call. After configuration is complete, the endpoints need to be initialized using the XUsb_EpInitializeAll() function call.

PHY Communication

As the H/W doesn't give any provision for the driver to configure the PHY, the driver doesn't provide any mechanism for directly programming the PHY.

DMA

The USB device has an inbuilt DMA. It's a simple DMA for data transfer between endpoint buffer memory and the external memory. The driver has two APIs for DMA operation. one API is used for resetting the DMA module of the USB device. The other API is for initiating the DMA transfer. The DMA transfer API is internal to the driver and is used by the USB endpoint data send and data receive functions. Upon completion of DMA transfer the USB device sets the buffer ready bit of the endpoint for which the DMA transfer is initiated. Setting of the buffer ready bit enables transmission/reception of an endpoint data. To enable the USB device to know to which endpoint the current DMA transfer is initiated, the driver writes the buffer ready mask to the DMA control register.

The DMA in the device can be enabled or disabled only during the system build time.

Interrupts

The driver provides an interrupt handler XUsb_IntrHandler for handling the interrupt from the USB device. The users of this driver have to register this handler with the interrupt system and provide the callback functions. The interrupt handlers and associated callback functions for the USB device have to be registered by the user using the XUsb_IntrSetHandler() function and/or XUsb_EpSetHandler() function.

XUsb_IntrSetHandler() function installs an asynchronous callback function for the general interrupts (interrupts other than the endpoint interrupts).

XUsb_EpSetHandler() function installs the callback functions for the interrupts related to the endpoint events. A separate callback function has to be installed for each of the endpoints.

Virtual Memory

This driver supports Virtual Memory. The RTOS is responsible for calculating the correct device base address in Virtual Memory space.

Threads

This driver is not thread safe. Any needs for threads or thread mutual exclusion must be satisfied by the layer above this driver.

Asserts

Asserts are used within all Xilinx drivers to enforce constraints on argument values. Asserts can be turned off on a system-wide basis by defining, at compile time, the NDEBUG identifier. By default, asserts are turned on and it is recommended that users leave asserts on during development.

Building the driver

The XUsb driver is composed of several source files. This allows the user to build and link only those parts of the driver that are necessary.

MODIFICATION HISTORY:
Ver   Who  Date     Changes






1.00a hvm  02/22/07 First release.
1.01a hvm  05/30/07 The chapter 9 files are moved to examples directory.
1.01a sdm  08/22/08 Removed support for static interrupt handlers from the MDD
                file
1.01a hvm  10/02/08 The Buffer0Ready, Buffer1Ready are declared as volatile.
                In function XUsb_EpDataRecv, the initialization of
                Buffer0Ready, Buffer1Ready and CurBufNum variables is
                moved before the buffer ready bit is set in the buffer
                ready register.
                Added the initialization of Buffer0Ready, Buffer1Ready
                and CurBufNum variables in the XUsb_EpDataSecd function.
2.00a   hvm  10/22/08 Added Support for the new XPS USB device. The new
                device has support for DMA. Apart from the
                DMA, remote wakeup feature is also added the USB device.
                        However, there is no additional code needed to be added
                in the driver to support this feature.
3.00a hvm  12/03/09 Added the modifications related to the new USB error
                reporting register in the XPS USB device. Updated to use
                HAL processor APIs. Removed _m from the name of the
                macros.
                XUsb_mReadReg is renamed to XUsb_ReadReg and
                XUsb_mWriteReg is renamed to XUsb_WriteReg.
3.01a hvm  5/20/10  Updated with fix for CR561171.The interrupt handler is
                updated to call the error handler callback function
                        during error interrupts.
3.02a hvm  7/15/10  Added Device ID initialization in XUsb_CfgInitialize
                function (CR555996).
3.02a hvm  8/5/10   Updated the XUsb_EpDataRecv function to ensure that the
                buffer ready bit setup is now made only during non-DMA
                case. CR570776.
3.02a hvm  8/16/10  Updated the examples with the little endian support.
4.00a hvm  10/21/10 Added new API XUsb_DmaIntrSetHandler for setting up DMA
                handler. Updated the XUsb_IntrHandler function to call
                the DMA handler to handle DMA events. Removed DmaDone
                and DmaError variables from the XUsb structure.
                Added two new APIs to provide access to the new ULPI PHY
                register.
4.01a hvm  8/23/11  Added new bit definitions for isochronous transfer bits
                in endpoint configuration register. Added a new API
                for setting these bits for a given endpoint. These bits
                are available only in the newer versions of the AXI USB
                IP. Check the IP datasheet for more details.
4.02a bss  3/04/12  Modified XCOMPONENT_IS_READY to XIL_COMPONENT_IS_READY
                CR 650877
4.03a bss  06/20/10 Added SIE Reset API to reset (XUsb_SieReset) the SIE
              state machine in xusb.c and SIE Reset Mask in xusb_l.h
              for CR 660602
4.04a bss  10/22/13 Added macros for HSIC PHY registers in xusb_l.h.
5.0   adk  19/12/13 Updated as per the New Tcl API's
5.1   sk   11/10/15 Used UINTPTR instead of u32 for Baseaddress CR# 867425.
                    Changed the prototype of XUsb_CfgInitialize API.
5.2  MNK   29/03/15 Added 64bit changes for ZYNQMP.
     ms    03/17/17 Modified text file in examples folder for doxygen
                    generation.
5.3   asa  02/05/19 Added dependencies.props in data folder for
                    importing examples in SDK.
5.6   pm   07/05/23 Added support for system device-tree flow.