Xilinx 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.


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.


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.


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


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.

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.