USB Programming Guide - USB Programming Guide - AM026

Versal AI Edge Series Gen 2 and Prime Series Gen 2 Technical Reference Manual (AM026)
Document ID
AM026
Release Date
2025-12-23
Revision
1.3 English

Initial Commands to USB Controller

There is only one command ring that is used for issuing xHCI specific commands or commands related to device slots.

The command ring control register is defined in the operational register space. All xHCI commands are issued by placing the desired command Transfer Request Block (TRB) on the command ring, then ringing the xHCI command doorbell register, that is writing the host controller command code to the DB target field of doorbell register 0.

All commands result in the generation of a command completion event TRB on the event ring.

Host Mode Initialization

After the system boots, the following steps are executed in the system software.
  1. The host controller is enumerated, assigned a base address for the xHCI register space.
  2. The system software sets the frame length adjustment (GFLADJ) register to a system-specific value.
  3. Initialize the system I/O memory maps.
  4. Wait until the controller not ready (CNR) flag in the USBSTS is 0 before writing any xHCI operational or run time registers.
  5. Program the maximum device slots enabled (MAXSLOTSEN) field in the configuration register to enable the device slots that system software is going to use.
  6. Program the device context base address array pointer (DCBAAP) register with a 64-bit address pointing to where the device context base address array is located.
  7. Define the command ring dequeue pointer by programming the command ring control register with a 64-bit address pointing to the starting address of the first TRB of the command ring.
  8. Initialize interrupts
  9. Initialize each active interrupter by with the following steps
    1. Defining the event ring.
      • Allocate and initialize the event ring segment(s)
      • Allocate the event ring segment table (ERST). Initialize the ERST table entries to point to and to define the size (in TRBs) of the respective event ring segment.
      • Program the interrupter event ring segment table size (ERSTSZ) register with the number of segments described by the event ring segment table.
      • Program the interrupter event ring dequeue pointer (ERDP) register with the starting address of the first segment described by the event ring segment table.
      • Program the interrupter event ring segment table base address (ERSTBA) register with a 64-bit address pointer to where the event ring segment table is located.

        Note: Writing the ERSTBA enables the event ring.

    2. Define the interrupts.
      • Enable system bus interrupt generation by writing a 1 to the interrupter enable (INTE) flag of the USBCMD register.
      • Enable the interrupter by writing a 1 to the interrupt enable (IE) field of the management register.
      • Write the USBCMD to turn the host controller ON by setting the run/stop (R/S) bit to 1. This operation allows the xHCI to begin accepting doorbell references.
    3. The host controller is now up and running.
  10. The root hub ports begin reporting device connects. System software can begin enumerating devices. USB2 (LS/FS/HS) devices require the port reset process to advance the port to the enabled state. Once USB2 ports are enabled, the port is active with start of files (SOFs) occurring on the port.

Device Detection and Enumeration

The USB device initialization process is the same, whether the device attached to the port is a function or a hub. Once the pipes associated with an external hub are set up, the hub driver enumerates the devices attached to the external hub's ports using standard hub class command sequences.
  1. When the xHCI detects a device attach, it sets the current connect status (CCS) and connect status change (CSC) flags to 1. If the assertion of CSC results in a 0 to 1 transition of the port status change event generation, the xHCI generates a port status change event.
  2. Upon receipt of a port status change event the system software evaluates the port ID field to determine the port that generated the event.
  3. System software then reads the PORTSC register of the port that generated the event. CSC = 1 if the event was due to attach (CCS = 1) or detach (CCS = 0).
  4. A USB2 protocol port requires software to reset the port, to advance the port to the enabled state, and a USB device from the powered state to the default state. After an attach event, the PED and PR flags is 0 and the PLS field is 7 (polling) in the PORTSC register.
  5. System software enables the port by resetting the port (writing a 1 to the PORTSC PR bit) then waiting for a port status change event due to the assertion of the port reset change (PRC) flag.
  6. The completion of the port reset causes the PORTSC register PRC and PED flags to be set (1), the PR flag to be cleared (0), and the PLS field to be U0 (0). If the assertion of PRC results in a 0 to 1 transition of PSCEG, the xHCI generates a port status change event as a result of the transition of PRC. The reset operation sets the USB2 device into the default state, preparing it for a SET_ADDRESS request.
  7. After the port successfully reaches the enabled state, the system software obtains a device slot for the newly attached device using an enable slot command.
  8. After successfully obtaining a device slot, the system software initializes the data structures associated with the slot.
  9. Once the slots related data structures are initialized, the system software uses an address device command to assign an address to the device and enable its default control endpoint.
  10. For full-speed devices, the system software should initially read the first 8 bytes of the USB device descriptor to retrieve the value of the bMaxPacketSize0 field and determine the actual maximum packet size for the default control endpoint, by issuing a USB GET_DESCRIPTOR request to the device, update the default control endpoint context with the actual maximum packet size, and inform the xHCI of the context change.
  11. Software then issues an evaluate context command with add context bit [1] (A1) set to 1 to inform the xHCI of the change to the default control endpoint's maximum packet size parameter.
  12. Now that the default control endpoint is fully operational.
    1. System software can read the complete USB device descriptor and possibly the configuration descriptors to be able to hand the device off to the appropriate class driver(s).
    2. The class driver can then configure the device slot using a configure endpoint command, and configure the USB device itself by issuing a USB SET_CONFIGURATION request through the devices' default control endpoint.
    3. The successful completion of both operations is required to advance the state of the USB device from Address to Configured and the xHCI device slot from Address to Configured.
    4. If required, the system software can configure alternate interfaces.
  13. The pipe interfaces to the USB device are now fully operational.

Device Detach

  • When the device is detached from a root hub port, the PORTSC current connection status (CCS) bit is cleared to 0 and the connect status change (CSC) bit is set to 1.
  • If a 0 to 1 transition of PSCEG occurs, the xHCI reports the change through a port status change event.
  • After the detection of detach, system software disables the device slot associated with the port by issuing a disable slot command for the affected slot.

Device Programming

The following sequence describes register programming for initialization of the xHCI controller as a USB device.
  1. In register DCTL, set the CSftRst field to 1 and wait for a read to return 0. This resets the device.
  2. In registers GSBUSCFG0/1, leave the default values if the correct power-on values were selected during coreConsultant configuration.
  3. This step is only required to enable threshold. In register GTXTHRCFG/ GRXTHRCFG, leave the default values (if the correct power-on values were selected during coreConsultant configuration).
  4. In register GSNPSID, the software must read the Synopsys ID register to find the device version and configure the driver for any version-specific features.
  5. Optionally, in register GUID, the software can program the user ID GUID read/write register.
  6. In register GUSB2PHYCFG, program the following PHY configuration fields: USBTrdTim, FSIntf, PHYIf, TOUTCal, or leave the default values (if the correct power-on values were selected during coreConsultant configuration).
  7. In register GUSB3PIPECTL, program the following PHY configuration fields: DatWidth, PrtOpDir, or leave the default values (if the correct power-on values were selected during coreConsultant configuration).
  8. In register GTXFIFOSIZn, write these registers to allocate prefetch buffers for each TX endpoint. Unless the packet sizes of the endpoints are application specific, it is recommended to use the default value.
  9. In register GRXFIFOSIZ0, write this register to allocate the receive buffer for all endpoints. Unless the packet sizes of the endpoints are application-specific, it is recommended to use the default value.
  10. In registers GEVNTADRn/ GEVNTSIZn/ GEVNTCOUNTn, depending on the number of interrupts allocated, program the event buffer address and size registers to point to the event buffer locations in system memory, the sizes of the buffers, and unmask the interrupt.
  11. In register GCTL, program this register to override scaledown, RAM clock select, and clock gating parameters.
  12. In register DCFG, program device speed and periodic frame interval.
  13. In register DEVTEN, at a minimum, enable USB reset, connection done, and USB/link state change events.
  14. In register DEPCMD0, issue a DEPSTARTCFG command with DEPCMD0.XferRscIdx set to 0 and CmdIOC set to 0 to initialize the transfer resource allocation. Poll CmdAct for completion.
  15. In registers DEPCMD0/ DEPCMD1, issue a DEPCFG command for physical endpoints 0 and 1 with the following characteristics, and poll CmdAct for completions.
    • USB endpoint number = 0 or 1 (for physical endpoint 0 or 1)
    • FIFONum = 0
    • XferNRdyEn and XferCmplEn = 1
    • Maximum packet size = 512
    • Burst size = 0
    • EPType = 2’b00 (Control)
  16. In registers Device Physical Endpoint-n Command Parameter, issue a DEPXFERCFG command for physical endpoints 0 and 1 with DEPCMDPAR0_0/1 set to 1, and poll CmdAct for completions.
  17. In register DEPCMD0, prepare a buffer for a setup packet, initialize a setup TRB, and issue a DEPSTRTXFER command for physical endpoint 0, pointing to the setup TRB. Poll CmdAct for completion.

    Note: The block attempts to fetch the setup TRB through the master interface after this command completes.

  18. In register DALEPENA, enable physical endpoints 0 and 1 by writing 0x3 to this register.
  19. In register DCTL, set DCTL.RunStop to 1 to allow the device to attach to the host. The device now is ready to receive start-of-file (SOF) packets, respond to control transfers on control endpoint 0, and generate events.