You're reading the documentation for a development version.
For the latest stable release version, please have a look at master.

USB device

Introduction

There is a USB device controller in the SpinalHDL library. In a few bullet points it can be resumed to :

  • Implemented to allow a CPU to configure and manage the endpoints

  • A internal ram which store the endpoints states and transactions descriptors

  • Up to 16 endpoints (for virtualy no price)

  • Support USB host full speed (12Mbps)

  • Test on linux using its own driver (https://github.com/SpinalHDL/linux/blob/dev/drivers/usb/gadget/udc/spinal_udc.c)

  • Bmb memory interace for the configuration

  • Require a clock for the internal phy which is a multiple of 12 Mhz at least 48 Mhz

  • The controller frequency is not restricted

  • No external phy required

Linux gadget tested and functional :

  • Serial connection

  • Ethernet connection

  • Mass storage (~8 Mbps on ArtyA7 linux)

Deployments :

Architecture

The controller is composed of :

  • A few control registers

  • A internal ram used to store the endpoint status, the transfer descriptors and the endpoint 0 SETUP data.

A linked list of descriptors for each endpoint in order to handle of the USB IN/OUT transactions and data.

The endpoint 0 manage the IN/OUT transactions like all the other endpoints but has some additional hardware to manage the SETUP transactions :

  • Its linked list is cleared on each setup transactions

  • The data of the SETUP transaction are stored in a fixed location (SETUP_DATA)

  • It has a specific interrupt flag for SETUP transactions

Registers

Note that all registers and memories of the controller are only accessible in 32 bits word access, bytes access isn’t supported.

FRAME (0xFF00)

Name

Type

Bits

Description

usbFrameId

RO

31-0

Current usb frame id

ADDRESS (0xFF04)

Name

Type

Bits

Description

address

WO

6-0

The device will only listen at tokens with the specified address This field is automaticaly cleared on usb reset events

enable

WO

8

Enable the USB address filtering if set

trigger

WO

9

Set the enable (see above) on the next EP0 IN tocken completion Cleared by the hardware after any EP0 completion

The idea here is to keep the whole register cleared until a USB SET_ADDRESS setup packet is received on EP0. At that moment, you can set the address and the trigger field, then provide the IN zero length descriptor to EP0 to finalise the SET_ADDRESS sequance. The controller will then automaticaly turn on the address filtering at the completion of that descriptor.

INTERRUPT (0xFF08)

All bits of this register can be cleared by writing ‘1’ in them.

Name

Type

Bits

Description

endpoints

RC

15-0

Raised when a enpoint generate a interrupt

reset

RC

16

Raised when a USB reset appeared

ep0Setup

RC

17

Raised when endpoint 0 receive a setup transaction

suspend

RC

18

Raised when a USB suspend appeared

resume

RC

19

Raised when a USB resume appeared

disconnect

RC

20

Raised when a USB disconnect appeared

HALT (0xFF0C)

This register allow to place a single enpoint in a dormant state in order to ensure atomicity of CPU operations, allowing to do things as read/modify/write on the endpoint registers and descriptors. The peripheral will return NAK if the given endpoint is addressed by the usb host.

Name

Type

Bits

Description

endpointId

WO

3-0

The endpoint you want to put in sleep

enable

WO

4

effective enable

RO

5

After setting the enable, you need to wait for this bit to be set by the hardware itself to ensure atomicity

CONFIG (0xFF10)

Name

Type

Bits

Description

pullupSet

SO

0

Write ‘1’ to enable the USB device pullup on the dp pin

pullupClear

SO

1

interruptEnableSet

SO

2

Write ‘1’ to let the present and future interrupt happening

interruptEnableClear

SO

3

INFO (0xFF20)

Name

Type

Bits

Description

ramSize

RO

3-0

The internal ram will have (1 << this) bytes

ENDPOINTS (0x0000 - 0x003F)

The endpoints status are stored at the begining of the internal ram over one 32 bits word each.

Name

Type

Bits

Description

enable

RW

0

If not set, the endpoint will ignore all the trafic

stall

RW

1

If set, the endpoint will always return STALL status

nack

RW

2

If set, the endpoint will always return NACK status

dataPhase

RW

3

Specify the IN/OUT data PID used. ‘0’ => DATA0. This field is also updated by the controller.

head

RW

15-4

Specify the current descriptor head (linked list). 0 => empty list, byte address = this << 4

isochronous

RW

16

maxPacketSize

RW

31-22

To get a endpoint responsive you need :

  • Set its enable flag to 1

Then the there is a few cases : - Either you have the stall or nack flag set, and so, the controller will always responde with the corresponding responses - Either, for EP0 setup request, the controller will not use descriptors, but will instead write the data into the SETUP_DATA register, and ACK - Either you have a empty linked list (head==0) in which case it will answer NACK - Either you have at least one descriptor pointed by head, in which case it will execute it and ACK if all was going smooth

SETUP_DATA (0x0040 - 0x0047)

When endpoint 0 receive a SETUP transaction, the data of the transaction will be stored at that place.

Descriptors

Descriptors allows to specify how a endpoint need to handle the data phase of IN/OUT transactions. They are stored in the internal ram, can be linked together via their linked lists and need to be aligned on 16 bytes boundaries

Name

Word

Bits

Description

offset

0

15-0

Specify the current progress in the transfer (in byte)

code

0

19-16

0xF => in progress, 0x0 => success

next

1

15-4

Point the the next descriptor 0 => nothing, byte address = this << 4

length

1

31-16

Number of bytes allocated for the data field

direction

2

16

‘0’ => OUT, ‘1’ => IN

interrupt

2

17

If set, the completion of the descriptor will generate a interrupt.

completionOnFull

2

18

Normaly, a descriptor completion only occure when a USB transfer is smaller than the maxPacketSize. But if this field is set, then when the descriptor become full is also a considered as a completion event. (offset == length)

data1OnCompletion

2

19

force the endpoint dataPhase to DATA1 on the completion of the descriptoo

data

Note, if the controller receive a frame where the IN/OUT does not match the descriptor IN/OUT, the frame will be ignored.

Also, to initialise a descriptor, the CPU should set the code field to 0xF

Usage

import spinal.core._
import spinal.core.sim._
import spinal.lib.bus.bmb.BmbParameter
import spinal.lib.com.usb.phy.UsbDevicePhyNative
import spinal.lib.com.usb.sim.UsbLsFsPhyAbstractIoAgent
import spinal.lib.com.usb.udc.{UsbDeviceCtrl, UsbDeviceCtrlParameter}


case class UsbDeviceTop() extends Component {
  val ctrlCd = ClockDomain.external("ctrlCd", frequency = FixedFrequency(100 MHz))
  val phyCd = ClockDomain.external("phyCd", frequency = FixedFrequency(48 MHz))

  val ctrl = ctrlCd on new UsbDeviceCtrl(
    p = UsbDeviceCtrlParameter(
      addressWidth = 14
    ),
    bmbParameter = BmbParameter(
      addressWidth = UsbDeviceCtrl.ctrlAddressWidth,
      dataWidth = 32,
      sourceWidth = 0,
      contextWidth = 0,
      lengthWidth = 2
    )
  )

  val phy = phyCd on new UsbDevicePhyNative(sim = true)
  ctrl.io.phy.cc(ctrlCd, phyCd) <> phy.io.ctrl

  val bmb = ctrl.io.ctrl.toIo()
  val usb = phy.io.usb.toIo()
  val power = phy.io.power.toIo()
  val pullup = phy.io.pullup.toIo()
  val interrupts = ctrl.io.interrupt.toIo()
}


object UsbDeviceGen extends App{
  SpinalVerilog(new UsbDeviceTop())
}