FPGA USB-device

FPGA USB-device

What and Why?

The usual solution to realize custom USB devices on FPGA is to use USB chips (such as CY7C68013), which leads to high circuit cost. This repo is an FPGA-based USB Full-Speed device core, which only require a simple circuit (just like STM32 microcontrollers) instead of additional USB chips.

Based on this, I further implement USB audio, USB camera, USB disk, USB keyboard and USB-Serial devices on FPGA. They are all standard devices specified by USB, which can be plug and play without installing drivers.

Features

Pure Verilog implementation for universal FPGAs such as Xilinx, Altera, etc.
The circuit is simple, only need three FPGA pins, one resistor and one USB connector (see Circuit connection).

If you're not familiar with USB protocol stack, but want to quickly implement USB devices on FPGA, you can use some USB classes I provide:

USB audio is a USB Audio Class (UAC) device. It can let FPGA be a speaker and a microphone (they are both in stereo 2-channel, 48ksps). It provides streaming interfaces for FPGA developers to receive speaker data and send microphone data.
USB camera is a USB Video Class (UVC) device. It can let FPGA be a USB camera, which provides a streaming interface for sending video data to PC.
USB flash drive is a USB Mass Storage (MSC) device. It can let FPGA be a USB flash disk.
USB keyboard is a USB Human Interface (HID) device. It can let FPGA be a USB keyboard, which provides a interface for FPGA developers to send "key press" action.
USB-Serial is a USB Communication Device Class (USB-CDC) device. It can let FPGA be a USB serial port device, which provides interfaces for FPGA developers to receive and send data to PC.
USB-Serial-2channel: is a composite device that includes two USB-CDC devices. It can let FPGA a two-channel serial port device, which provides interfaces for FPGA developers to receive and send data to PC.

If you are familiar with USB protocol stack, you can use the usb device core in this repo to develop more USB devices (see Development using USB core). The core provides:

Customize 1 device descriptor, 1 configuration descriptor, and 6 string descriptors.
4 IN endpoints (0x81~0x84), 4 OUT endpoints (0x01~0x04).
An optional debug interface for printing debug information to the computer via a UART, you can see the USB communication process through it.

Demonstration of USB devices

	What you can see in Windows Device Manager	What you can see in softwares
USB audio
USB camera
USB disk
USB keyboard		Press a key every 2 seconds
USB Serial
USB Serial 2channel		ditto

Compatibility for Operation Systems

I tested the compatibility of these devices on different operating systems, as shown below.

	Windows 10	Linux Ubuntu 18.04	macOS 10.15
USB audio
USB camera			*
USB disk
USB keyboard
USB Serial
USB Serial 2channel

macOS recognizes my USB camera device, but it can't read the video. The reason is unknown and to be resolved later.

Special thanks

Thanks xiaowuzxc for submitting the code of a USB speaker device. I later expanded it to current USB audio device (speaker+microphone).
Thanks ****8125@qq.com for solving the problem of Linux cannot recongnize one of the channels of USB-Serial-2channel.

Circuit connection

USB has 4 wires: VBUS, GND, USB_D-, and USB_D+ . Taking USB Type B connector as an example, the 4 wires are defined in the figure below.


Figure: USB connector (square female) and cable.

Please connect the circuit according to the figure below. Where usb_dp_pull, usb_dp, usb_dn are the three common IO pins of FPGA (must be 3.3 V). Note that:

If you use flying leads for connection, ensure that the length of flying leads not longer than 10 cm.
If you use PCB for connection, note that USB_D- and USB_D+ are differential pairs.
The usb_dp_pull should connect to USB_D+ through a 1.5kΩ resistor.
Don't forget to connect GND
The VBUS pin of USB connector VBUS is a 5V power source that comes from USB-host, it can be ignored, or can supply power for FPGA.

  _________________
  |               |
  |  usb_dp_pull* |-------|
  |               |       |
  |               |      |-| 1.5k resistor
  |               |      | |
  |               |      |_|            ____________                             __________
  |               |       |             |          |                             |
  |       usb_dp* |-------^-------------| USB_D+   |                             |
  |               |                     |          |    USB cable                |
  |       usb_dn* |---------------------| USB_D-   |<===========================>| Host PC
  |               |                     |          |                             |
  |           GND |---------------------| GND      |                             |
  |               |                     |          |                             |
  -----------------                     ------------                             ----------
        FPGA              USB connector (Type-B, mini, micro, or Type-C)           Host PC
 *: usb_dp_pull, usb_dp, usb_dn are common 3V3 IO pins of FPGA.

                        Figure : Connect FPGA to USB

II List of Design code

RTL The folder contains all the design source code, which is divided into 3 folders according to the level:

Folder	Level	Description
RTL/fpga_examples	Application	Realize specific applications based on USB class. To facilitate testing, the applications here are very simple. You can develop complex applications such as capturing data from a CMOS sensor and sending to the USB UVC core.
RTL/usb_class	USB class	Realize some USB class cores based on the USB device core.
RTL/usbfs_core	USB device core	A universal USB device core, which implements USB protocol stack from signal-level to transaction-level. Developers that know well about the USB protocol can use it to develop more USB devices. See Development using USB core.

Specifically, each source code file is listed as follows:

Folder	File Name	Description
RTL/fpga_examples	fpga_top_usb_audio.v	Simple demo of using usb_audio_top.v. Let FPGA be a USB speaker & microphone with loopback connection, so that the speaker's voice will recorded by the microphone.
RTL/fpga_examples	fpga_top_usb_camera.v	Simple demo of using usb_camera_top.v. Let FPGA be a USB camera that generates a black and white stripe video.
RTL/fpga_examples	fpga_top_usb_disk.v	Simple demo of using usb_disk_top.v. Let FPGA be a USB flash disk with a 24 KB FAT16 file system.
RTL/fpga_examples	fpga_top_usb_keyboard.v	Simple demo of using usb_keyboard_top.v. Let FPGA be a USB keyborad that pressing a key every 2 seconds.
RTL/fpga_examples	fpga_top_usb_serial.v	Simple demo of using usb_serial_top.v. Let FPGA be a USB serial port device.
RTL/fpga_examples	fpga_top_usb_serial2.v	Simple demo of using usb_serial2_top.v. Let FPGA be a two-channel USB serial port device.
RTL/usb_class	usb_audio_top.v	use usbfs_core_top.v to implement USB speaker & microphone
RTL/usb_class	usb_camera_top.v	use usbfs_core_top.v to implement USB Video Class (UVC) camera
RTL/usb_class	usb_disk_top.v	use usbfs_core_top.v to implement USB Mass Storage Class (MSC) disk
RTL/usb_class	usb_keyboard_top.v	use usbfs_core_top.v to implement USB Human Interface Device Class (HID) keyboard
RTL/usb_class	usb_serial_top.v	use usbfs_core_top.v to implement USB Communication Device Class (CDC) serial port
RTL/usb_class	usb_serial2_top.v	use usbfs_core_top.v to implement a composite device, including 2 USB-CDC serial ports
RTL/usbfs_core	usbfs_core_top.v	Top module of the USB device core
RTL/usbfs_core	usbfs_transaction.v	USB transaction-level controller, called by usbfs_core_top.v.
RTL/usbfs_core	usbfs_packet_rx.v	USB packet-level RX controller, called by usbfs_core_top.v.
RTL/usbfs_core	usbfs_packet_tx.v	USB packet-level TX controller, called by usbfs_core_top.v.
RTL/usbfs_core	usbfs_bitlevel.v	USB bit-level controller (PHY) , called by usbfs_core_top.v.
RTL/usbfs_core	usbfs_debug_monitor.v	Collects and send out debug information. only for debug
RTL/usbfs_core	usbfs_debug_uart_tx.v	Convert the debug information to a UART signal. only for debug

The following sections describe how to use these USB classes.

Ⅲ USB audio

The USB audio device implements speaker + microphone. The file hierarchy is as follows. Please add these files to the FPGA project, compile and program it to the FPGA.

RTL/fpga_examples/fpga_top_usb_audio.v
- RTL/usb_class/usb_audio_top.v
  - RTL/usbfs_core/usbfs_core_top.v
    - Other .v files in RTL/usbfs_core/

The USB core of this repo requires a 60 MHz driving clock. Since I use Altera Cyclone IV, an altpll primitive module is used in my code to convert inputted 50MHz clock to 60MHz clock. If your FPGA is not a Altera Cyclone IV, you should remove altpll module and use the corresponding primitive or IP core to generate 60 MHz clock. For example, for Xilinx FPGAs, you can use Clock Wizard IP.

Test

After the USB is plugged in, open the Windows Device Manager, you would find a device:

Because fpga_top_usb_audio.v loopback connects the speaker and the microphone, the played voice of the speaker will be recorded by the microphone.

For testing, first select the device as the audio output device:

Then play a music. Meanwhile use any recording software or video recording software (such as obstudio), select FPGA-USB-audio as the input microphone, and record an audio. Finally you will find that the recorded audio is the same as the music you played.

Application development

You can develop more complex audio applications based on this simple example, for which you need to pay attention to the in/out ports of usb_audio_top.v . See the code comments for details.

IV USB camera

The file hierarchy is as follows. Please add these files to the FPGA project, compile and program it to the FPGA.

RTL/fpga_examples/fpga_top_usb_camera.v
- RTL/usb_class/usb_camera_top.v
  - RTL/usbfs_core/usbfs_core_top.v
    - Other .v files in RTL/usbfs_core/

The USB core of this repo requires a 60 MHz driving clock. Since I use Altera Cyclone IV, an altpll primitive module is used in my code to convert inputted 50MHz clock to 60MHz clock. If your FPGA is not a Altera Cyclone IV, you should remove altpll module and use the corresponding primitive or IP core to generate 60 MHz clock. For example, for Xilinx FPGAs, you can use Clock Wizard IP.

Test

After the USB is plugged in, open the Windows Device Manager, you would find a device:

Open the "camera" software of Windows, you would see a scrolling black and white stripe:

Application development

You can develop more camera applications based on this simple example, for which you need to pay attention to the in/out ports of usb_camera_top.v

Parameters of usb_camera_top.v

The key parameters are listed here:

// parameters of usb_camera_top.v
parameter        FRAME_TYPE = "YUY2",    // "MONO" or "YUY2"
parameter [13:0] FRAME_W    = 14'd320,   // video-frame width  in pixels, must be a even number
parameter [13:0] FRAME_H    = 14'd240,   // video-frame height in pixels, must be a even number

You can set the width and height of the video frame by modifying parameter FRAME_W and FRAME_H.

As for paramter FRAME_TYPE , it can be "MONO" or "YUY2" .

FRAME_TYPE="MONO"

FRAME_TYPE="MONO" Is grayscale mode. Each pixel is a 1-byte luminance value (0-255).

For example, for a 4x3 video frame, each frame has 12 pixels. While working, the user should send following 12 bytes successively to the module:

Y00  Y01  Y02  Y03  Y10  Y11  Y12  Y13  Y20  Y21  Y22  Y23

Where Y00 is the luminance value of row0 column0; Y01 is the luminance value of row0, column1; ......

FRAME_TYPE="YUY2"

FRAME_TYPE="YUY2" is color mode, also known as YUYV, in which each pixel has an independent 1-byte luminance value (Y), while two adjacent pixels share a 1-byte blue chroma value (U) and a 1-byte red chroma value (V).

For example, for a 4x2 video frame, the user should send following 12 bytes successively to the module:

Y00  U00  Y01  V00  Y02  U02  Y03  V02  Y10  U10  Y11  V10  Y12  U12  Y13  V12

Where (Y00, U00, V00) is the pixel of row0 column0; (Y01, U00, V00) is the pixel of row0 column1; (Y02, U02, V02) is the pixel of row0 column2; (Y03, U02, V02) is the pixel of row0 column3. (Y12, U10, V10) is the pixel of row1 column0; ...

Ports of usb_camera_top.v

The ports of usb_camera_top.v used to read the pixel from the outside is:

// pixel fetch signals of usb_camera_top.v    start-of-frame |  frame data transmitting   | end-of-frame
output reg         vf_sof,                // 0000000001000000000000000000000000000000000000000000000000000    // vf_sof=1 indicate a start of video-frame
output reg         vf_req,                // 0000000000000000010001000100010001000100010001000000000000000    // when vf_req=1, a byte of pixel data on vf_byte need to be valid
input  wire [ 7:0] vf_byte,               //                                                                  // a byte of pixel data

usb_camera_top.v will continuously input and sent frames to the Host-PC.

At the beginning of each video frame, vf_sof=1 pulses for one cycle. Then vf_req=1 pulses for N cycles, where N is the number of bytes of the video frame, for FRAME_TYPE="MONO", N = frame width × frame height; For FRAME_TYPE="YUY2", N = 2 × frame width × frame height. Each time when vf_req=1, the outside world should provide a byte onto vf_byte signal, which should be valid at most 4 cycles after vf_req=1 and keep until the next time when vf_req=1.

Frame rate and performance

This module sends the video to the Host-PC with a fixed speed. The larger the video frame size, the smaller the frame rate. The theoretical bandwidth of USB Full Speed is 12Mbps. In fact, the module sends 800 bytes of pixel data (400 pixels) every 1ms. Therefore, the approximate calculation formula of the frame rate is:

Frame Rate = 400000/ (Frame Width × Frame Height)

Ⅴ U disk

The file hierarchy is as follows. Please add these files to the FPGA project, compile and program it to the FPGA.

RTL/fpga_examples/fpga_top_usb_disk.v
- RTL/usb_class/usb_disk_top.v
  - RTL/usbfs_core/usbfs_core_top.v
    - Other .v files in RTL/usbfs_core/

The USB core of this repo requires a 60 MHz driving clock. Since I use Altera Cyclone IV, an altpll primitive module is used in my code to convert inputted 50MHz clock to 60MHz clock. If your FPGA is not a Altera Cyclone IV, you should remove altpll module and use the corresponding primitive or IP core to generate 60 MHz clock. For example, for Xilinx FPGAs, you can use Clock Wizard IP.

Test

After the USB is plugged in, open the Windows Device Manager, you would find a device:

And you would see a new disk in Windows File Explorer, with one file "example,txt" in it.

Since it is implemented with the FPGA's on-chip memory (BRAM), all your modifications will disappear when the FPGA is powered off or re-programed. The free space of this hard disk is only 3.5 KB, which is basically useless and only for testing.

Application development

You can develop larger or more complex USB-disks based on this simple example, for which you need to pay attention to the in/out ports usb_disk_top.v (see code comments for details).

The key ports including:

// signals of usb_disk_top.v
output reg  [40:0] mem_addr,      // byte address
output reg         mem_wen,       // 1:write   0:read
output reg  [ 7:0] mem_wdata,     // byte to write
input  wire [ 7:0] mem_rdata,     // byte to read

These signals are used for reading and writing the Storage space of hard disk. mem_addr Is a 41-bit byte address, so the accessable addressing space is 2^41=2TB.

At each clock cycle:

If mem_wen=1, the Host wants to write one byte of data to the device, the write address is mem_addr, and the write data is mem_wdata;
If mem_wen=0 the device needs to read a byte of data, the read address is mem_addr, and the read data should appear on mem_rdata on the next cycle.

This interface is very easy to connect to the BRAM of FPGA.

In order for disk to be recognized as a formatted hard disk, you can provide an initial data to the BRAM, which contains a file system.

A file system is a data structure used to organize files and is stored on the hard disk. The production method is quite complicated and will not be describe here. If you need to make a customized U disk device, you can contact me through issue or email.

VI USB keyboard

The file hierarchy is as follows. Please add these files to the FPGA project, compile and program it to the FPGA.

RTL/fpga_examples/fpga_top_usb_keyboard.v
- RTL/usb_class/usb_keyboard_top.v
  - RTL/usbfs_core/usbfs_core_top.v
    - Other .v files in RTL/usbfs_core/

The USB core of this repo requires a 60 MHz driving clock. Since I use Altera Cyclone IV, an altpll primitive module is used in my code to convert inputted 50MHz clock to 60MHz clock. If your FPGA is not a Altera Cyclone IV, you should remove altpll module and use the corresponding primitive or IP core to generate 60 MHz clock. For example, for Xilinx FPGAs, you can use Clock Wizard IP.

Test

After the USB is plugged in, open the Windows Device Manager, you would find a device:

The keyboard will press a English letter key every 2 seconds.

Application development

You can develop more complex keyboard applications based on this simple example, for which you need to pay attention to the in/out ports of usb_keyboard_top.v (see code comments for details).

Note the following signals:

// signals of usb_keyboard_top.v:
input  wire [15:0] key_value,     // Indicates which key to press, NOT ASCII code! see https://www.usb.org/sites/default/files/hut1_21_0.pdf section 10.
input  wire        key_request,   // when key_request=1 pulses, a key is pressed.

key_request usually needs to maintain 0, when you need to press a key, let key_request=1 for a cycle, meanwhile set a key code on key_value . Refer to https://www.usb.org/sites/default/files/hut1_21_0.pdf Section 10 for the definition of key code. For example, keys 'A'-'Z' corresponds to key_value=16'h0004~16'h001D

Ⅶ USB-Serial

The file hierarchy is as follows. Please add these files to the FPGA project, compile and program it to the FPGA.

RTL/fpga_examples/fpga_top_usb_serial.v
- RTL/usb_class/usb_serial_top.v
  - RTL/usbfs_core/usbfs_core_top.v
    - Other .v files in RTL/usbfs_core/

The USB core of this repo requires a 60 MHz driving clock. Since I use Altera Cyclone IV, an altpll primitive module is used in my code to convert inputted 50MHz clock to 60MHz clock. If your FPGA is not a Altera Cyclone IV, you should remove altpll module and use the corresponding primitive or IP core to generate 60 MHz clock. For example, for Xilinx FPGAs, you can use Clock Wizard IP.

Test

After the USB is plugged in, open the Windows Device Manager, you would find a device:

In this example, the usb_serial_top.v received data is converted from lowercase letters to uppercase letters (ASCII code), and then looped back to the sending interface. You can send data to Serial Port using minicom, putty, HyperTerminal, or Serial Assistant software on Host-PC, and the sent data will be echoed (with lowercase letters converted to uppercase letters). As shown in figure below.

Because this USB-CDC-based Serial-Port is not a true UART, it is also called Virtual serial port. So there will be no any effects when you change baud rate, data bit, check bit, and stop bits.

Application development

You can develop more complex Serial-Port communication applications based on this simple example, for which you need to pay attention to the in/out ports of usb_serial_top.v (see the code comments for details).

The key signals are described here, including:

// signals of usb_serial_top.v
// receive data (host-to-device)
output wire [ 7:0] recv_data,     // received data byte
output wire        recv_valid,    // when recv_valid=1 pulses, a data byte is received on recv_data
// send data (device-to-host)
input  wire [ 7:0] send_data,     // data byte to send
input  wire        send_valid,    // when device want to send a data byte, set send_valid=1. the data byte will be sent successfully when (send_valid=1 && send_ready=1).
output wire        send_ready,    // send_ready handshakes with send_valid. send_ready=1 indicates send-buffer is not full and will accept the byte on send_data. send_ready=0 indicates send-buffer is full and cannot accept a new byte.

The signal of host-to-device is relatively simple. Every time a data byte is received, recv_valid will become high of one cycle, and the byte will appear on recv_data at the same time.

The device-to-host signal is in the opposite direction, and there is an send_ready signal, send_ready=0 indicating that the send buffer inside the module is full and cannot send new data temporarily. send_ready And send_valid form a handshake signal, when the user needs to send a byte, he should let send_valid=1, at the same time let the byte appear on send_data. When send_valid=1 && send_ready=1 , the byte is successfully sent to the send buffer, and the user can proceed to send the next byte. This handshake mechanism is similar to AXI-stream.

There is a send buffer of 1024 bytes in usb_serial_top.v . If the send throughput is not large, the send buffer will never be full, in this case you can ignore send_ready. However, when the send throughput is large, which may cause the sending buffer to be full, then send_ready shouldn't be ignored.

Ⅷ Dual-channel USB-Serial

The file hierarchy is as follows. Please add these files to the FPGA project, compile and program it to the FPGA.

RTL/fpga_examples/fpga_top_usb_serial2.v
- RTL/usb_class/usb_serial2_top.v
  - RTL/usbfs_core/usbfs_core_top.v
    - Other .v files in RTL/usbfs_core/

The USB core of this repo requires a 60 MHz driving clock. Since I use Altera Cyclone IV, an altpll primitive module is used in my code to convert inputted 50MHz clock to 60MHz clock. If your FPGA is not a Altera Cyclone IV, you should remove altpll module and use the corresponding primitive or IP core to generate 60 MHz clock. For example, for Xilinx FPGAs, you can use Clock Wizard IP.

Test

After the USB is plugged in, open the Windows Device Manager, you would find two Serial devices:

It's behavior is as same as the single-channel USB-Serial, which will not be described here.

Application development

You can develop a more complex Serial-Port communication application based on this simple example. For this, you need to pay attention to the in/out ports of usb_serial2_top.v (see the code comment for details). Its usage is as same as the single-channel USB-Serial, except that the sending and receiving interfaces become dual-channel, which will not be repeated here.

Ⅸ Development using USB device core

You can use my USB device core (usbfs_core_top.v) to develop more USB devices. The core provides:

Customize 1 device descriptor, 1 configuration descriptor, and 6 string descriptors.
Four IN endpoints (0x81~0x84) and four OUT endpoints (0x01~0x04) .
An optional debug interface for printing debug information to the computer via a UART, you can see the USB communication process through it.

The parameters and in/out ports of usbfs_core_top.v are described below.

Parameters of usbfs_core_top.v

Parameters	Type	Explain
`DESCRIPTOR_DEVICE`	`[18*8-1:0]` (can contain 18 bytes)	Device descriptor
`DESCRIPTOR_STR1`	`[64*8-1:0]` (can contain 64 bytes)	String descriptor 1
`DESCRIPTOR_STR2`	`[64*8-1:0]` (can contain 64 bytes)	String Descriptor 2
`DESCRIPTOR_STR3`	`[64*8-1:0]` (can contain 64 bytes)	String Descriptor 3
`DESCRIPTOR_STR4`	`[64*8-1:0]` (can contain 64 bytes)	String Descriptor 4
`DESCRIPTOR_STR5`	`[64*8-1:0]` (can contain 64 bytes)	String Descriptor 5
`DESCRIPTOR_STR6`	`[64*8-1:0]` (can contain 64 bytes)	String Descriptor 6
`DESCRIPTOR_CONFIG`	`[512*8-1:0]` (can contain 512 bytes)	Configuration descriptor
`EP00_MAXPKTSIZE`	`[7:0]`	max packet size of control endpoint
`EP81_MAXPKTSIZE`	`[9:0]`	max packet size of IN endpoint 0x81
`EP82_MAXPKTSIZE`	`[9:0]`	max packet size of IN endpoint 0x82
`EP83_MAXPKTSIZE`	`[9:0]`	max packet size of IN endpoint 0x83
`EP84_MAXPKTSIZE`	`[9:0]`	max packet size of IN endpoint 0x84
`EP81_ISOCHRONOUS`	0 or 1	Is IN endpoint 0x81 isochronous?
`EP82_ISOCHRONOUS`	0 or 1	Is IN endpoint 0x82 isochronous?
`EP83_ISOCHRONOUS`	0 or 1	Is IN endpoint 0x83 isochronous?
`EP84_ISOCHRONOUS`	0 or 1	Is IN endpoint 0x84 isochronous?
`EP01_ISOCHRONOUS`	0 or 1	Is OUT endpoint 0x01 isochronous?
`EP02_ISOCHRONOUS`	0 or 1	Is OUT endpoint 0x02 isochronous?
`EP03_ISOCHRONOUS`	0 or 1	Is OUT endpoint 0x03 isochronous?
`EP04_ISOCHRONOUS`	0 or 1	Is OUT endpoint 0x04 isochronous?
`DEBUG`	TRUE or FALSE	Enable Debug interface ?

According to USB 1.1 specification, when an endpoint is in isochronous transfer mode, the maximum packet size can be any value from 8 \ to 1023. When the endpoint is in interrupt or bulk transfer mode, the maximum packet size can only be 8, 16, 32, or 64.

Ports of usbfs_core_top.v

Clock and Reset

The clk signal needs to be 60 MHz:

// signals of usbfs_core_top.v
input  wire clk,           // 60MHz is required

The reset signal rstn should be set to high level during normal operation. If it is necessary to stop the operation, set rstn to low. At this time, if the USB is plugged into the Host-PC, the Host-PC will detect that the USB is unplugged.

// signals of usbfs_core_top.v
input  wire rstn,          // active-low reset, reset when rstn=0 (USB will unplug when reset)

USB Signal

The following 3 signals need to be connect according to Circuit connection.

// signals of usbfs_core_top.v
// USB signals
output reg  usb_dp_pull,   // connect to USB D+ by an 1.5k resistor
inout       usb_dp,        // USB D+
inout       usb_dn,        // USB D-

Signal for indicating whether the USB is plugged.

The usb_rstn signal indicates whether the USB is connected, high for connected and low for disconnected. There are two possible reasons for disconnection: either the USB cable is not plugged in the Host, or the FPGA side is in resetting state ( rstn=0).

// signals of usbfs_core_top.v
output reg  usb_rstn,      // 1: connected , 0: disconnected (when USB cable unplug, or when system reset (rstn=0))

USB-transfer and USB-frame detection signal

When sot and sof are high for one cycle, it indicates that a USB-transfer or a USB-frame is detected, respectively.

USB-transfer refers to the whole process of USB transfer, including control transfer, interrupt transfer, bulk transfer and isochronous transfer.

USB-frame means a SOF token is sent from USB-host to USB-device every 1ms, which can be used to guide the isochronous transfer.

// signals of usbfs_core_top.v
output reg  sot,           // detect a start of USB-transfer
output reg  sof,           // detect a start of USB-frame

Response signal of control transfer

The following three signals ep00_setup_cmd ep00_resp_idx ep00_resp provide the interface for control transfer.

// signals of usbfs_core_top.v
// endpoint 0 (control endpoint) command response here
output wire [63:0] ep00_setup_cmd,
output wire [ 8:0] ep00_resp_idx,
input  wire [ 7:0] ep00_resp,

According to the USB specification, control transfer is performed only on control endpoint (0x00), and the Host will first send an 8-byte SETUP command. The device may respond data packets to the Host. Based on the fields of bmRequestType[6:5] of the SETUP command, control transfer can be divided into three categories:

Standard control transfer ( bmRequestType[6:5]=0)
Class-specific control transfer ( bmRequestType[6:5]=1)
Vendor-specific control transfer ( bmRequestType[6:5]=2)

Standard control transfer is used to respond to descriptor and other data, which is processed internally in usbfs_core_top.v and does not need to be concerned by the developer. The developer only needs to specify the descriptor with parameter.

Class-specific control transfer and vendor-specific control transfer are related to the implementation of specific devices. Developers can respond to them through these three signals. For example, the UVC device provided by this repo uses it to respond to the UVC Video Probe and Commit Controls. In addition, some simple devices do not need Class-specific control transfer and Vendor-specific control transfer at all, so developers can ignore these three signals.

When a control transfer is performed, the 8-byte SETUP command will appear on ep00_setup_cmd first. Then ep00_resp_idx signal will increase from 0, representing the byte address that the response is currently required. The developer needs to set ep00_resp to the corresponding byte at next cycle.

Taking the UVC device as an example, the following code detects whether the SETUP command requires the device to respond to the UVC Video Probe and Commit Controls.

// In the UVC device, the host requests UVC Video Probe and Commit Controls, the following code is to respond this request:
always @ (posedge clk)
    if(ep00_setup_cmd[7:0] == 8'hA1 && ep00_setup_cmd[47:16] == 32'h_0001_0100 )
        ep00_resp <= UVC_PROBE_COMMIT[ep00_resp_idx];
    else
        ep00_resp <= '0;

For the content of the command and response data of control transfer, please refer to the specific USB class's specification.

IN endpoint (0x81~0x84) signals

The following 4 groups of signals correspond to 4 IN endpoints and are used to send packets from device to host.

For example, if the FPGA needs to send an IN packet on the IN endpoint 0x81, the following is required:

First, let ep81_valid=1 and hold, meanwhile holding the 0th byte of the packet on ep81_data.
ep81_ready and ep81_valid form a pair of handshake signals. Each time when ep81_ready=ep81_valid=1 , a byte is successfully transmitted.
At the next cycle when ep81_ready=1 , if the entire IN packet transmission is finished, let ep81_valid=0 . If the IN packet still has bytes to send, keep ep81_valid=1 and let ep81_data to be the next byte to be sent.

// signals of usbfs_core_top.v
// endpoint 0x81 data input (device-to-host)
input  wire [ 7:0] ep81_data,     // IN data byte
input  wire        ep81_valid,    // when device want to send a data byte, assert valid=1. the data byte will be sent successfully when valid=1 & ready=1.
output wire        ep81_ready,    // handshakes with valid. ready=1 indicates the data byte can be accept.
// endpoint 0x82 data input (device-to-host)
input  wire [ 7:0] ep82_data,     // IN data byte
input  wire        ep82_valid,    // when device want to send a data byte, assert valid=1. the data byte will be sent successfully when valid=1 & ready=1.
output wire        ep82_ready,    // handshakes with valid. ready=1 indicates the data byte can be accept.
// endpoint 0x83 data input (device-to-host)
input  wire [ 7:0] ep83_data,     // IN data byte
input  wire        ep83_valid,    // when device want to send a data byte, assert valid=1. the data byte will be sent successfully when valid=1 & ready=1.
output wire        ep83_ready,    // handshakes with valid. ready=1 indicates the data byte can be accept.
// endpoint 0x84 data input (device-to-host)
input  wire [ 7:0] ep84_data,     // IN data byte
input  wire        ep84_valid,    // when device want to send a data byte, assert valid=1. the data byte will be sent successfully when valid=1 & ready=1.
output wire        ep84_ready,    // handshakes with valid. ready=1 indicates the data byte can be accept.

OUT endpoint (0x01~0x04) signals

The following four groups of signals correspond to four OUT endpoints and are used to receive the OUT packet from host to device.

For example, when ep01_valid=1 for one cycle, a byte of OUT packet is received, the byte appears on ep01_data . In addition, the boundary of different packets can be detected by the sot signal mentioned before.

// signals of usbfs_core_top.v
// endpoint 0x84 data input (device-to-host)
input  wire [ 7:0] ep84_data,     // IN data byte
input  wire        ep84_valid,    // when device want to send a data byte, assert valid=1. the data byte will be sent successfully when valid=1 & ready=1.
output wire        ep84_ready,    // handshakes with valid. ready=1 indicates the data byte can be accept.
// endpoint 0x01 data output (host-to-device)
output wire [ 7:0] ep01_data,     // OUT data byte
output wire        ep01_valid,    // when out_valid=1 pulses, a data byte is received on out_data
// endpoint 0x02 data output (host-to-device)
output wire [ 7:0] ep02_data,     // OUT data byte
output wire        ep02_valid,    // when out_valid=1 pulses, a data byte is received on out_data
// endpoint 0x03 data output (host-to-device)
output wire [ 7:0] ep03_data,     // OUT data byte
output wire        ep03_valid,    // when out_valid=1 pulses, a data byte is received on out_data
// endpoint 0x04 data output (host-to-device)
output wire [ 7:0] ep04_data,     // OUT data byte
output wire        ep04_valid,    // when out_valid=1 pulses, a data byte is received on out_data

Debug output interface

To enable Debug interface, set the parameter DEBUG=1 . Otherwise the debug interface will not output any data.

The following signals are used to print debug information to the outside world. The debug information is a stream of printable ASCII code bytes. When debug_en=1 , one byte appears on debug_data .

// signals of usbfs_core_top.v
// debug output info, only for USB developers, can be ignored for normally use
output wire        debug_en,      // when debug_en=1 pulses, a byte of debug info appears on debug_data
output wire [ 7:0] debug_data,    // 
output wire        debug_uart_tx  // debug_uart_tx is the signal after converting {debug_en,debug_data} to UART (format: 115200,8,n,1). If you want to transmit debug info via UART, you can use this signal. If you want to transmit debug info via other custom protocols, please ignore this signal and use {debug_en,debug_data}.

In order to facilitate the use, I will also convert the {debug_en,debug_data} to a UART output signal debug_uart_tx . You can connect the UART to PC, and use a Serial Port software (minicom, HyperTermainal, etc) to monitor the debugging information.

Note that the UART configurations are : baud rate=115200, data bits=8, no parity bits.

The following figure shows the debug data printed on the UART when my USB UVC device is plugged into the computer. As you can see, this is a descriptor enumeration process.


Figure: Debugging data printed on the UART when the USB UVC device is plugged into the computer.

Because the speed of UART is slow, when a large amount of debugging information is generated, some debugging information will be discarded. For example, when UVC transmits video, the information printed by UART is incomplete. If you want to view the full debugging information when large amount of USB data, you should use other high-speed communication to send {debug_en, debug_data} to Host-PC instead of UART.

References

https://www.usbmadesimple.co.uk/ : USB Made Simple
https://github.com/FengJungle/USB_Protocol_CH USB Chinese Protocol Manual
https://www.usb.org/document-library/usb-20-specification : USB 2.0 Specification
https://www.usb.org/document-library/video-class-v11-document-set : USB Video Class (UVC) 1.1 Specification
https://www.usb.org/document-library/audio-device-class-spec-basic-audio-devices-v10-and-adopters-agreement : USB Audio Class (UAC) 1.0 Specification
https://www.usb.org/document-library/mass-storage-class-specification-overview-14 : USB Mass Storage Class (USB-MSC) 1.4 Specification
https://www.usb.org/document-library/class-definitions-communication-devices-12 : USB Communication Device Class (USB-CDC) 1.2 Specification
Other FPGA implementations:
- https://github.com/avakar/usbcorev : a USB-device controller, only supported up to the transaction layer.
- http://jorisvr.nl/article/usb-serial : One USB-CDC, VHDL implementation, requires additional UTMI PHY.
- https://github.com/pbing/USB A USB-HID implementation for Low Speed.
- https://github.com/ultraembedded/cores : Contains some USB-host and USB-device implementations, requiring UTMI PHY or ULPI PHY.

FPGA USB-device

USB 1.1 device 控制器。可在 FPGA 上实现各种 USB 设备。比如 USB扬声器和麦克风、USB摄像头、U盘、USB键盘、USB串口。

为了在 FPGA 上实现 USB 设备，通常的技术路线是使用 USB 芯片 (例如 Cypress CY7C68013)，导致电路和软件的开发成本较高。本库用 FPGA 实现一个通用的 USB 1.1 (Full Speed) device 控制器，可以像 STM32 单片机那样，用非常简单的电路来实现 USB 设备，而不依赖额外的 USB 芯片。

基于此，我还在 FPGA 上实现了 USB音频、USB摄像头、U盘、USB键盘、USB-Serial (串口)，它们是 USB 所规定的标准设备，因此不需要安装驱动就能即插即用。

本库的特点：

纯 Verilog 实现，适用于 Xilinx 、Altera 等各种型号的 FPGA 。
所需的电路非常简单，除了FPGA外，只需3个FPGA引脚，1个电阻，1个USB接口座（见电路连接）

如果你不熟悉 USB 协议栈，但想快速实现某种 USB 设备，可以使用我封装的一些 USB 功能：

USB音频 : 包括扬声器和麦克风 (双声道, 48ksps) ，提供接收扬声器音频数据、发送麦克风音频数据的流式接口。
USB摄像头 : 可向电脑传输视频（宽和高可自定义），提供发送视频数据的流式接口。
U盘。
USB键盘：提供"按键按下"的控制接口。
USB-Serial : 实现串口设备，可在电脑上使用 minicom, putty, HyperTerminal, 串口助手等软件与 FPGA 进行数据传输。
USB-Serial-2ch : 是一个复合设备，包括2个独立的 USB-Serial 。

如果你熟悉 USB 协议栈，可以使用本库来开发更多的 USB 设备 (详见USB-device二次开发)。它提供：

自定义1个设备描述符(device descriptor)、1个配置描述符(configuration descriptor)、6个字符串描述符(string descriptor) 。
4 个 IN endpoint (0x81~0x84) 、 4 个 OUT endpoint (0x01~0x04) 。
可选的调试输出接口 (debug interface)，通过一个额外的UART打印调试信息到电脑，可以看到 USB 数据包的通信过程。

效果展示

	Windows 设备管理器中看到的设备	效果展示
USB音频
USB摄像头
U盘
USB键盘		每2秒按下一个英文字母键
USB-Serial
USB-Serial-2ch		同上

兼容性

我测试了这些设备在不同操作系统上的兼容性，如下表。

兼容性测试	Windows 10	Linux Ubuntu 18.04	macOS 10.15
USB音频		(不识别bug已解决)
USB摄像头
U盘
USB键盘
USB-Serial
USB-Serial-2ch		(不识别bug已解决)

macOS 能识别我的 USB 摄像头设备，但无法读出视频，原因未知，留待后续解决。

特别鸣谢

感谢 github.com/xiaowuzxc 提交的 USB 扬声器的代码。本人后来将其拓展为现在的 USB音频 (扬声器+麦克风)
感谢 *****8125@qq.com 解决了 USB-Serial-2ch 中有一个通道不识别的问题。

Ⅰ 电路连接

USB 具有 VBUS, GND, USB_D-, USB_D+ 这4根线。以 USB Type B 连接座（俗称USB方口母座）为例，这4根线定义如下图。


图：USB 连接座（方口母座）与线。

请进行如下图的电路连接。其中 usb_dp_pull, usb_dp, usb_dn 是 FPGA 的 3 个普通IO引脚（电平必须为 3.3V）。其中：

FPGA 的 usb_dn 接 USB_D- 。如果是飞线连接，要保证连接线长度在10cm以内。如果是PCB连接，要与 usb_dp 差分布线。
FPGA 的 usb_dp 接 USB_D+ 。如果是飞线连接，要保证连接线长度在10cm以内；如果是PCB连接，要与 usb_dn 差分布线。
FPGA 的 usb_dp_pull 要通过 1.5kΩ 的电阻接 USB_D+
FPGA 的 GND 接 USB 连接座的 GND
USB 连接座的 VBUS 是一个 5V, 500mA 的电源，可以不连，也可给 FPGA 供电。

  _________________
  |               |
  |   usb_dp_pull |-------|
  |               |       |
  |               |      |-| 1.5k resistor
  |               |      | |
  |               |      |_|        ____________                  __________
  |               |       |         |          |                  |
  |        usb_dp |-------^---------| USB_D+   |                  |
  |               |                 |          |    USB cable     |
  |        usb_dn |-----------------| USB_D-   |<================>| Host PC
  |               |                 |          |                  |
  |           GND |-----------------| GND      |                  |
  |               |                 |          |                  |
  -----------------                 ------------                  ----------
        FPGA                          USB 连接座                      电脑
                       图 : FPGA 连接 USB 的方法

Ⅱ 代码文件一览

RTL 文件夹包含了所有代码，其中按层级分为三个文件夹：

文件夹	层级	说明
RTL/fpga_examples	应用层	在 USB class 的基础上实现具体的应用功能。为了方便测试，这里实现的应用功能非常简单，例如回环测试 USB-Serial、生成黑白条纹给 USB 摄像头。你可以开发复杂的应用，例如采集 CMOS 图象传感器的数据给 USB 摄像头。
RTL/usb_class	USB class	在 USB device core 的基础上实现了一些 USB class 。例如用 USB Communication Device Class (USB-CDC) 实现 USB-Serial；用 USB Video Class (UVC) 实现摄像头 ……
RTL/usbfs_core	USB device core	一个通用的 USB device core，实现 USB 底层信号的处理，包括从 bit-level 到 transaction-level 。熟悉 USB 协议栈的开发者可以用它来开发更多的 USB 设备，详见 USB device 二次开发。

具体地，对每个代码文件说明如下：

文件夹	文件名	说明
RTL/fpga_examples	fpga_top_usb_audio.v	把 usb_audio_top.v 的扬声器和麦克风回环连接，扬声器的放音会被麦克风录到
RTL/fpga_examples	fpga_top_usb_camera.v	生成黑白条纹给 usb_camera_top.v ，用照相机软件能看到这个黑白条纹
RTL/fpga_examples	fpga_top_usb_disk.v	用 usb_disk_top.v 实现了 24 KB 的 FAT16 文件系统的 U盘
RTL/fpga_examples	fpga_top_usb_keyboard.v	每2秒生成一个按键信号给 usb_keyboard_top.v
RTL/fpga_examples	fpga_top_usb_serial.v	把 usb_serial_top.v 的发送和接收回环连接，电脑上发送的字符会被回显
RTL/fpga_examples	fpga_top_usb_serial2.v	把 usb_serial2_top.v 的发送和接收回环连接，电脑上发送的字符会被回显
RTL/usb_class	usb_audio_top.v	实现 USB扬声器+麦克风
RTL/usb_class	usb_camera_top.v	USB Video Class (UVC) 实现 USB摄像头
RTL/usb_class	usb_disk_top.v	USB Mass Storage Class (USB-MSC) 实现 U盘
RTL/usb_class	usb_keyboard_top.v	USB Human Interface Device Class (USB-HID) 实现 USB键盘
RTL/usb_class	usb_serial_top.v	USB Communication Device Class (USB-CDC) 实现 USB-Serial
RTL/usb_class	usb_serial2_top.v	复合设备，包含2个 USB-CDC ，实现双通道USB-Serial
RTL/usbfs_core	usbfs_core_top.v	USB device core 的顶层模块
RTL/usbfs_core	usbfs_transaction.v	实现 USB transaction-level，被 usbfs_core_top.v 调用
RTL/usbfs_core	usbfs_packet_rx.v	实现 USB packet-level RX，被 usbfs_core_top.v 调用
RTL/usbfs_core	usbfs_packet_tx.v	实现 USB packet-level TX，被 usbfs_core_top.v 调用
RTL/usbfs_core	usbfs_bitlevel.v	实现 USB bit-level，被 usbfs_core_top.v 调用
RTL/usbfs_core	usbfs_debug_monitor.v	收集调试信息（不干扰 USB 的功能），被 usbfs_core_top.v 调用
RTL/usbfs_core	usbfs_debug_uart_tx.v	将调试信息转为一个 UART 信号，被 usbfs_core_top.v 调用

下文逐一介绍本库提供的每一个 USB class 的使用方法。最后会介绍基于 USB device core 的二次开发。

Ⅲ USB 音频

本库的 USB 音频设备实现了扬声器+麦克风。代码文件调用关系如下。请将这些文件加入 FPGA 工程，编译并烧录到 FPGA 。

RTL/fpga_examples/fpga_top_usb_audio.v
- RTL/usb_class/usb_audio_top.v
  - RTL/usbfs_core/usbfs_core_top.v
    - RTL/usbfs_core/里的其它.v文件(不逐个列出了)

本库的 USB core 需要 60MHz 的驱动时钟。fpga_top_usb_audio.v 里调用了 Altera 的 altpll 原语来把晶振的 50MHz 时钟转为 60MHz 时钟。如果你的 FPGA 不是 Altera Cyclone IV ，请删掉 altpll 部分的代码，然后用对应的原语或 IP 核来生成 60MHz 时钟。例如对于 Xilinx FPGA ，可以使用 Clock Wizard IP 。

测试

USB插入后，打开 Windows 设备管理器，应该能看到音频设备：

由于 fpga_top_usb_audio.v 将扬声器和麦克风回环连接，因此扬声器的放音会被麦克风录到。为了测试，首先要选择该设备为音频输出设备：

然后随便放一个音乐。再用任意录音软件或录视频软件 (比如 obstudio) ，选择 FPGA-USB-audio 作为输入麦克风，录一段音或视频。最后你会发现录到的音频和你放的音乐一样。

应用开发

你可以基于这个简单的例子开发更复杂的音频应用，为此你需要关注 usb_audio_top.v 的模块接口，详见代码注释，这里不做赘述。

Ⅳ USB 摄像头

本库的 USB 摄像头设备的代码文件调用关系如下。请将这些文件加入 FPGA 工程，编译并烧录到 FPGA 。

RTL/fpga_examples/fpga_top_usb_camera.v
- RTL/usb_class/usb_camera_top.v
  - RTL/usbfs_core/usbfs_core_top.v
    - RTL/usbfs_core/里的其它.v 文件(不逐个列出了)

本库的 USB core 需要 60MHz 的驱动时钟。fpga_top_usb_camera.v 里调用了 Altera 的 altpll 原语来把晶振的 50MHz 时钟转为 60MHz 时钟。如果你的 FPGA 不是 Altera Cyclone IV ，请删掉 altpll 部分的代码，然后用对应的原语或 IP 核来生成 60MHz 时钟。例如对于 Xilinx FPGA ，可以使用 Clock Wizard IP 。

测试

USB插入后，打开 Windows 设备管理器，应该能看到摄像头设备：

打开 Windows 10 自带的照相机软件，应该能看到一个滚动的黑白条纹：

应用开发

你可以基于这个简单的例子开发更复杂的摄像头应用，为此你需要关注 usb_camera_top.v 的模块接口（详见代码注释）。

usb_camera_top.v 的参数

这里对关键的参数进行说明：

// parameters of usb_camera_top.v
parameter        FRAME_TYPE = "YUY2",    // "MONO" or "YUY2"
parameter [13:0] FRAME_W    = 14'd320,   // video-frame width  in pixels, must be a even number
parameter [13:0] FRAME_H    = 14'd240,   // video-frame height in pixels, must be a even number

你可以用 FRAME_W 和 FRAME_H 设置视频帧的宽和高。FRAME_TYPE 可取 "MONO" 或 "YUY2" 。

FRAME_TYPE="MONO"

FRAME_TYPE="MONO" 是灰度模式，每个像素对应1字节的明度值。例如，对于一个 4x3 的视频帧，该模块会先后从外界读取以下12个字节：

Y00  Y01  Y02  Y03  Y10  Y11  Y12  Y13  Y20  Y21  Y22  Y23

其中 Y00 是第0行第0列的明度值；Y01 是第0行第1列的明度值；……

FRAME_TYPE="YUY2"

FRAME_TYPE="YUY2" 是一种彩色模式，又称为 YUYV ，每个像素具有独立的 1字节明度值(Y)，而相邻的两个像素共享1字节的蓝色度(U)和1字节的红色度(V) 。例如，对于一个 4x2 的视频帧，该模块会先后从外界读取以下16个字节：

Y00  U00  Y01  V00  Y02  U02  Y03  V02  Y10  U10  Y11  V10  Y12  U12  Y13  V12

其中 (Y00, U00, V00) 是第0行第0列的像素；(Y01, U00, V00) 是第0行第1列的像素；(Y02, U02, V02) 是第0行第2列的像素；(Y03, U02, V02) 是第0行第3列的像素；(Y10, U10, V10) 是第1行第0列的像素；……

usb_camera_top.v 的信号

usb_camera_top.v 中用来从外界读取像素的信号是：

// pixel fetch signals of usb_camera_top.v    start-of-frame |  frame data transmitting   | end-of-frame
output reg         vf_sof,                // 0000000001000000000000000000000000000000000000000000000000000    // vf_sof=1 indicate a start of video-frame
output reg         vf_req,                // 0000000000000000010001000100010001000100010001000000000000000    // when vf_req=1, a byte of pixel data on vf_byte need to be valid
input  wire [ 7:0] vf_byte,               //                                                                  // a byte of pixel data

usb_camera_top.v 会通过以上信号不断读取视频帧，并发送给 Host-PC 。在每个视频帧的开始， vf_sof 会出现一周期的高电平。然后 vf_req 会断续地出现 N 次高电平，其中 N 是视频帧的字节数，对于 FRAME_TYPE="MONO" ，N=帧宽度×帧高度；对于 FRAME_TYPE="YUY2" ，N=2×帧宽度×帧高度。每当 vf_req=1 时，外界应该提供一个字节（像素数据）到 vf_byte 信号上，最晚应该在 vf_req=1 后的第4个时钟周期让 vf_byte 有效，并且保持有效直到下一次 vf_req=1 。

帧率与性能

本模块以固定带宽发送视频到 Host-PC ，视频帧的尺寸越大，帧率越小。 USB Full Speed 的理论带宽是 12Mbps ，实际上本模块每1ms固定发送 800 字节的像素数据（400个像素），因此帧率的大致计算公式为：

帧率 = 400000 / (帧宽度×帧高度) (帧/秒)

Ⅴ U盘

本库的 U盘设备的代码文件调用关系如下。请将这些文件加入 FPGA 工程，编译并烧录到 FPGA 。

RTL/fpga_examples/fpga_top_usb_disk.v
- RTL/usb_class/usb_disk_top.v
  - RTL/usbfs_core/usbfs_core_top.v
    - RTL/usbfs_core/里的其它.v文件(不逐个列出了)

本库的 USB core 需要 60MHz 的驱动时钟。fpga_top_usb_disk.v 里调用了 Altera 的 altpll 原语来把晶振的 50MHz 时钟转为 60MHz 时钟。如果你的 FPGA 不是 Altera Cyclone IV ，请删掉 altpll 部分的代码，然后用对应的原语或 IP 核来生成 60MHz 时钟。例如对于 Xilinx FPGA ，可以使用 Clock Wizard IP 。

测试

USB插入后，打开 Windows 设备管理器，应该能看到一个硬盘：

Windows 文件资源管理器中应该能看到这个硬盘，里面有一个文件 "example.txt" 。你可以在这个硬盘里添加、修改、删除文件。由于它是用 FPGA 的片内存储器 (BRAM) 实现的，因此 FPGA 断电或重新烧录后，你的所有修改都会消失。这个硬盘的可用空间只有 3.5 KB ，基本上没啥用，仅供测试。

应用开发

你可以基于这个简单的例子开发更大或更复杂的 USB-disk ，为此你需要关注 usb_disk_top.v 的模块接口（详见代码注释）。

这里对其中关键的信号进行说明，包括：

// signals of usb_disk_top.v
output reg  [40:0] mem_addr,      // byte address
output reg         mem_wen,       // 1:write   0:read
output reg  [ 7:0] mem_wdata,     // byte to write
input  wire [ 7:0] mem_rdata,     // byte to read

这些信号用于读写 硬盘的存储空间 。 mem_addr 是 41-bit 的字节地址，因此寻址空间为 2^41=2TB 。不过实际的硬盘存储空间肯定小于 2TB ，因此只有从 mem_addr=0 到 mem_addr=硬盘容量 的地址是有效的。在每个时钟周期：

如果 mem_wen=1 ，说明 Host 想写一字节的数据给设备，写地址为 mem_addr ，写数据为 mem_wdata ；
如果 mem_wen=0 ，设备需要读一个字节的数据，读地址为 mem_addr ，读数据应该在下一周期送到 mem_rdata 上。

该接口非常容易接到 FPGA 的 BRAM 上，这样我们就用 BRAM 实现了硬盘的存储空间。

为了让 disk 能被识别为格式化好的硬盘，你可以给这个 BRAM 提供一个初始数据，里面包含一个文件系统。fpga_top_usb_disk.v 里的 BRAM 就实现了一个总大小为 24KB 的 FAT16 文件系统。

文件系统是用来组织文件的数据结构，和文件本身一样也存储在硬盘里。制作方法比较复杂，不在这里赘述。如果需要制作定制的 U盘设备，可以通过 issue 联系本人。

Ⅵ USB键盘

本库的 USB 键盘设备的代码文件调用关系如下。请将这些文件加入 FPGA 工程，编译并烧录到 FPGA 。

RTL/fpga_examples/fpga_top_usb_keyboard.v
- RTL/usb_class/usb_keyboard_top.v
  - RTL/usbfs_core/usbfs_core_top.v
    - RTL/usbfs_core/里的其它.v文件(不逐个列出了)

本库的 USB core 需要 60MHz 的驱动时钟。fpga_top_usb_keyboard.v 里调用了 Altera 的 altpll 原语来把晶振的 50MHz 时钟转为 60MHz 时钟。如果你的 FPGA 不是 Altera Cyclone IV ，请删掉 altpll 部分的代码，然后用对应的原语或 IP 核来生成 60MHz 时钟。例如对于 Xilinx FPGA ，可以使用 Clock Wizard IP 。

测试

USB插入后，打开 Windows 设备管理器，应该能看到一个键盘设备：

该键盘会每2秒按下英文字母按键。打开一个记事本就能看到效果。

应用开发

你可以基于这个简单的例子开发更复杂的键盘应用，为此你需要关注 usb_keyboard_top.v 的模块接口（详见代码注释）。

这里的对其中用来发送按键信号的信号进行说明：

// signals of usb_keyboard_top.v:
input  wire [15:0] key_value,     // Indicates which key to press, NOT ASCII code! see https://www.usb.org/sites/default/files/hut1_21_0.pdf section 10.
input  wire        key_request,   // when key_request=1 pulses, a key is pressed.

key_request平时需要保持为0，当你需要按下一个键时，需要让 key_request=1 一个周期，同时在 key_value 上输入该按键对应的代码。按键代码的定义详见 https://www.usb.org/sites/default/files/hut1_21_0.pdf 的 Section 10 。例如，按键 'a'-'z' 对应 key_value=16'h0004~16'h001D ，按键 '1'-'0' 对应 key_value=16'h001E~16'h0027 。

Ⅶ USB-Serial

本库的 USB-Serial 设备的代码文件调用关系如下。请将这些文件加入 FPGA 工程，编译并烧录到 FPGA 。

RTL/fpga_examples/fpga_top_usb_serial.v
- RTL/usb_class/usb_serial_top.v
  - RTL/usbfs_core/usbfs_core_top.v
    - RTL/usbfs_core/里的其它.v文件(不逐个列出了)

本库的 USB core 需要 60MHz 的驱动时钟。fpga_top_usb_serial.v 里调用了 Altera 的 altpll 原语来把晶振的 50MHz 时钟转为 60MHz 时钟。如果你的 FPGA 不是 Altera Cyclone IV ，请删掉 altpll 部分的代码，然后用对应的原语或 IP 核来生成 60MHz 时钟。例如对于 Xilinx FPGA ，可以使用 Clock Wizard IP 。

测试

USB插入后，打开 Windows 设备管理器，应该能看到一个 USB-serial 设备：

本例把 usb_serial_top.v 收到的数据按照 ASCII 码把小写字母转换为大写字母，然后回环连接到发送接口。你可以在 Host-PC 上用 minicom, putty, HyperTerminal, 串口助手的软件来发送数据给 Serial Port ，发送的数据会被回显（其中小写字母转化为大写字母）。以串口助手为例，如下图。

因为该 Serial-Port 并不是真正的 UART，所以又称为虚拟串口。设置虚拟串口的波特率、数据位、校验位、停止位将不会有任何效果。

应用开发

你可以基于这个简单的例子开发更复杂的 Serial-Port 通信应用，为此你需要关注 usb_serial_top.v 的模块接口（详见代码注释）。

这里对其中关键的信号进行说明，包括：

// signals of usb_serial_top.v
// receive data (host-to-device)
output wire [ 7:0] recv_data,     // received data byte
output wire        recv_valid,    // when recv_valid=1 pulses, a data byte is received on recv_data
// send data (device-to-host)
input  wire [ 7:0] send_data,     // data byte to send
input  wire        send_valid,    // when device want to send a data byte, set send_valid=1. the data byte will be sent successfully when (send_valid=1 && send_ready=1).
output wire        send_ready,    // send_ready handshakes with send_valid. send_ready=1 indicates send-buffer is not full and will accept the byte on send_data. send_ready=0 indicates send-buffer is full and cannot accept a new byte.

其中 host-to-device 的信号较为简单，每当收到数据字节时，recv_valid 出现一个周期的高电平，同时 recv_data 上出现该字节。

而 device-to-host 的信号方向相反，而且多出来了一个 send_ready 信号，send_ready=0 说明模块内部的发送缓冲区满了，暂时不能发送新的数据。 send_ready与 send_valid 构成握手信号，当用户需要发送一个字节时，应该让 send_valid=1 ，同时让字节出现再 send_data 上。当 send_valid=1 && send_ready=1 时，该字节被成功送入发送缓存，用户就可以继而发送下一字节。该握手机制类似 AXI-stream 。

usb_serial_top.v 中有 1024 字节的发送缓存。如果需要发送的数据吞吐率不大，发送缓存永远不会满，也可也无视 send_ready 信号。然而，在数据吞吐率较大从而可能导致发送缓存满的情况下，如果无视 send_ready=0 的情况，可能导致部分数据丢失。

Ⅷ 双通道 USB-Serial

本库的双通道 USB-Serial 设备的代码文件调用关系如下。请将这些文件加入 FPGA 工程，编译并烧录到 FPGA 。

RTL/fpga_examples/fpga_top_usb_serial2.v
- RTL/usb_class/usb_serial2_top.v
  - RTL/usbfs_core/usbfs_core_top.v
    - RTL/usbfs_core/里的其它.v文件(不逐个列出了)

本库的 USB core 需要 60MHz 的驱动时钟。fpga_top_usb_serial2.v 里调用了 Altera 的 altpll 原语来把晶振的 50MHz 时钟转为 60MHz 时钟。如果你的 FPGA 不是 Altera Cyclone IV ，请删掉 altpll 部分的代码，然后用对应的原语或 IP 核来生成 60MHz 时钟。例如对于 Xilinx FPGA ，可以使用 Clock Wizard IP 。

测试

USB插入后，打开 Windows 设备管理器，应该能看到2个 USB-serial 设备：

测试方法与单通道的 USB-Serial 相同，这里不做赘述。

应用开发

你可以基于这个简单的例子开发更复杂的 Serial-Port 通信应用，为此你需要关注 usb_serial2_top.v 的模块接口（详见代码注释），其用法与单通道的 USB-Serial 相同，只不过发送和接收接口都变成了双通道，这里不做赘述。

Ⅸ 基于 USB device core 的二次开发

你可以使用 usbfs_core_top.v 开发其它的 USB 设备，它提供：

自定义1个设备描述符(device descriptor)、1个配置描述符(configuration descriptor)、6个字符串描述符(string descriptor) 。
除了 control endpoint (0x00) 外，提供 4 个 IN endpoint (0x81~0x84) 、 4 个 OUT endpoint (0x01~0x04) 。
可选的调试输出接口 (debug interface)，通过一个额外的UART打印调试信息到电脑，可以看到 USB 数据包的通信过程。

下文对 usbfs_core_top.v 的参数和输入输出信号进行说明。

usbfs_core_top.v 的参数

usbfs_core_top.v 的参数如下表。

usbfs_core_top 的参数	类型	说明
`DESCRIPTOR_DEVICE`	`[18*8-1:0]` (最长18字节)	设备描述符
`DESCRIPTOR_STR1`	`[64*8-1:0]` (最长64字节)	字符串描述符1
`DESCRIPTOR_STR2`	`[64*8-1:0]` (最长64字节)	字符串描述符2
`DESCRIPTOR_STR3`	`[64*8-1:0]` (最长64字节)	字符串描述符3
`DESCRIPTOR_STR4`	`[64*8-1:0]` (最长64字节)	字符串描述符4
`DESCRIPTOR_STR5`	`[64*8-1:0]` (最长64字节)	字符串描述符5
`DESCRIPTOR_STR6`	`[64*8-1:0]` (最长64字节)	字符串描述符6
`DESCRIPTOR_CONFIG`	`[512*8-1:0]` (最长512字节)	配置描述符
`EP00_MAXPKTSIZE`	`[7:0]`	control endpoint 最大包大小
`EP81_MAXPKTSIZE`	`[9:0]`	IN endpoint 0x81 最大包大小
`EP82_MAXPKTSIZE`	`[9:0]`	IN endpoint 0x82 最大包大小
`EP83_MAXPKTSIZE`	`[9:0]`	IN endpoint 0x83 最大包大小
`EP84_MAXPKTSIZE`	`[9:0]`	IN endpoint 0x84 最大包大小
`EP81_ISOCHRONOUS`	0 或 1	IN endpoint 0x81 是否是 isochronous 模式
`EP82_ISOCHRONOUS`	0 或 1	IN endpoint 0x82 是否是 isochronous 模式
`EP83_ISOCHRONOUS`	0 或 1	IN endpoint 0x83 是否是 isochronous 模式
`EP84_ISOCHRONOUS`	0 或 1	IN endpoint 0x84 是否是 isochronous 模式
`EP01_ISOCHRONOUS`	0 或 1	OUT endpoint 0x01 是否是 isochronous 模式
`EP02_ISOCHRONOUS`	0 或 1	OUT endpoint 0x02 是否是 isochronous 模式
`EP03_ISOCHRONOUS`	0 或 1	OUT endpoint 0x03 是否是 isochronous 模式
`EP04_ISOCHRONOUS`	0 或 1	OUT endpoint 0x04 是否是 isochronous 模式
`DEBUG`	"TRUE" 或 "FALSE"	是否启用调试接口

根据 USB 1.1 specification ，当一个 endpoint 是 isochronous 传输模式时，最大包大小可取 8~1023 的任意值。当 endpoint 是 interrupt 或 bulk 传输模式时，最大包大小只能取 8, 16, 32, 或 64 。

usbfs_core_top.v 的信号

时钟与复位

需要给 clk 信号提供 60MHz 的时钟：

// signals of usbfs_core_top.v
input  wire clk,           // 60MHz is required

复位信号 rstn 在正常工作时应该取高电平，如果需要停止工作，可以让 rstn 取低电平，此时如果 USB 插在 Host-PC 上，Host-PC 会检测到 USB 被拔出。

// signals of usbfs_core_top.v
input  wire rstn,          // active-low reset, reset when rstn=0 (USB will unplug when reset)

USB 信号

以下3个信号需要引出到 FPGA 的引脚上，并按照电路连接方法来连接到 USB 接口。

// signals of usbfs_core_top.v
// USB signals
output reg  usb_dp_pull,   // connect to USB D+ by an 1.5k resistor
inout       usb_dp,        // USB D+
inout       usb_dn,        // USB D-

用来指示USB是否被插入的信号

usb_rstn 信号指示了 USB 是否连接，高电平代表已连接；低电平代表未连接。未连接可能是有两种情况：要么USB线被从 Host 上拔出，要么 FPGA 侧主动进行复位（ rstn=0 ）

// signals of usbfs_core_top.v
output reg  usb_rstn,      // 1: connected , 0: disconnected (when USB cable unplug, or when system reset (rstn=0))

USB-transfer 和 USB-frame 检测信号

当以下两个信号 sot 和 sof 出现一周期的高电平时，分别指示了 USB-transfer 和 USB-frame 的开始。其中 USB-transfer 是指一个 USB transfer 的全过程，包括 control transfer, interrupt transfer, bulk transfer 和 isochronous transfer 。而 USB-frame 起始于 USB-host 每 1ms 会发送一次的 SOF token ，可以用来指导 isochronous transfer 。

// signals of usbfs_core_top.v
output reg  sot,           // detect a start of USB-transfer
output reg  sof,           // detect a start of USB-frame

control transfer 响应信号

以下三个信号 ep00_setup_cmd, ep00_resp_idx, ep00_resp 提供了响应 control transfer 的接口。

// signals of usbfs_core_top.v
// endpoint 0 (control endpoint) command response here
output wire [63:0] ep00_setup_cmd,
output wire [ 8:0] ep00_resp_idx,
input  wire [ 7:0] ep00_resp,

根据 USB specification ，control transfer 只在 control endpoint (0x00) 上进行，Host 会先发送 8 字节的 SETUP command ，根据 SETUP command ，device 可能响应数据给 Host 。根据 SETUP command 中的 bmRequestType[6:5] 字段，control transfer 可以分为三类：

Standard control transfer (bmRequestType[6:5]=0)
Class-specific control transfer (bmRequestType[6:5]=1)
Vendor-specific control transfer (bmRequestType[6:5]=2)

其中 Standard control transfer 用来响应描述符等数据，在 usbfs_core_top.v 内部处理的，不需要开发者关心，开发者只需要用 parameter 指定好描述符即可。而 Class-specific control transfer 和 Vendor-specific control transfer 与具体设备的实现有关，开发者可以通过这三个信号响应它们。例如本库提供的 UVC 设备用它来响应 UVC Video Probe and Commit Controls ，而 HID 设备用它来响应 HID descriptor 。另外，有些简单的设备根本不需要 Class-specific control transfer 和 Vendor-specific control transfer ，则开发者可以无视这三个信号。

当一个 control transfer 进行时，ep00_setup_cmd 信号上先出现 8 字节的 SETUP command 。然后 ep00_resp_idx 信号从 0 开始递增，代表了当前需要响应第几个字节。开发者需要随时将响应数据的第 ep00_resp_idx 个字节打在 ep00_resp 信号上。

以 UVC 设备举例，以下代码检测 SETUP command 是否要求设备响应 UVC Video Probe and Commit Controls ，如果是，就响应 UVC_PROBE_COMMIT 数组中的第 ep00_resp_idx 字节打在 ep00_resp 信号上，否则就响应 0x00 ：

// 举例：在 UVC 设备中，当 host 请求 UVC Video Probe and Commit Controls 时，应该使用以下写法进行响应：
always @ (posedge clk)
    if(ep00_setup_cmd[7:0] == 8'hA1 && ep00_setup_cmd[47:16] == 32'h_0001_0100 )
        ep00_resp <= UVC_PROBE_COMMIT[ep00_resp_idx];
    else
        ep00_resp <= '0;

关于 control transfer 的命令和响应数据的内容，请参考具体的协议 specification 。

IN endpoint (0x81~0x84) 数据输入信号

以下 4 组信号对应 4 个 IN endpoint ，用于发送 device-to-host 的 IN packet 。

例如，如果 FPGA 需要在 IN endpoint 0x81 上发送一个 IN packet ，需要：

首先，令 ep81_valid=1 并保持，同时在 ep81_data 上保持 packet 的第0个字节。
ep81_ready 与 ep81_valid 构成握手信号。每当 ep81_ready 出现一个周期的高电平，说明一个字节被成功发送。
在 ep81_ready=1 的下一个周期，如果 IN packet 发送结束，需要令 ep81_valid=0 。如果 IN packet 还有字节每发完，保持 ep81_valid=1 ，并将 ep81_data 更新为新的待发送的字节。

// signals of usbfs_core_top.v
// endpoint 0x81 data input (device-to-host)
input  wire [ 7:0] ep81_data,     // IN data byte
input  wire        ep81_valid,    // when device want to send a data byte, assert valid=1. the data byte will be sent successfully when valid=1 & ready=1.
output wire        ep81_ready,    // handshakes with valid. ready=1 indicates the data byte can be accept.
// endpoint 0x82 data input (device-to-host)
input  wire [ 7:0] ep82_data,     // IN data byte
input  wire        ep82_valid,    // when device want to send a data byte, assert valid=1. the data byte will be sent successfully when valid=1 & ready=1.
output wire        ep82_ready,    // handshakes with valid. ready=1 indicates the data byte can be accept.
// endpoint 0x83 data input (device-to-host)
input  wire [ 7:0] ep83_data,     // IN data byte
input  wire        ep83_valid,    // when device want to send a data byte, assert valid=1. the data byte will be sent successfully when valid=1 & ready=1.
output wire        ep83_ready,    // handshakes with valid. ready=1 indicates the data byte can be accept.
// endpoint 0x84 data input (device-to-host)
input  wire [ 7:0] ep84_data,     // IN data byte
input  wire        ep84_valid,    // when device want to send a data byte, assert valid=1. the data byte will be sent successfully when valid=1 & ready=1.
output wire        ep84_ready,    // handshakes with valid. ready=1 indicates the data byte can be accept.

OUT endpoint (0x01~0x04) 数据输出信号

以下 4 组信号对应 4 个 OUT endpoint ，用于接收 host-to-device 的 OUT packet。

例如，当 ep01_valid 出现一个周期的高电平时，说明收到了 OUT packet 中的一个字节，该字节出现在 ep01_data 上。另外，packet 的边界可以用之前讲过的 sot 信号来检测。

// signals of usbfs_core_top.v
// endpoint 0x84 data input (device-to-host)
input  wire [ 7:0] ep84_data,     // IN data byte
input  wire        ep84_valid,    // when device want to send a data byte, assert valid=1. the data byte will be sent successfully when valid=1 & ready=1.
output wire        ep84_ready,    // handshakes with valid. ready=1 indicates the data byte can be accept.
// endpoint 0x01 data output (host-to-device)
output wire [ 7:0] ep01_data,     // OUT data byte
output wire        ep01_valid,    // when out_valid=1 pulses, a data byte is received on out_data
// endpoint 0x02 data output (host-to-device)
output wire [ 7:0] ep02_data,     // OUT data byte
output wire        ep02_valid,    // when out_valid=1 pulses, a data byte is received on out_data
// endpoint 0x03 data output (host-to-device)
output wire [ 7:0] ep03_data,     // OUT data byte
output wire        ep03_valid,    // when out_valid=1 pulses, a data byte is received on out_data
// endpoint 0x04 data output (host-to-device)
output wire [ 7:0] ep04_data,     // OUT data byte
output wire        ep04_valid,    // when out_valid=1 pulses, a data byte is received on out_data

调试输出接口

要使用调试接口，需要把模块参数 DEBUG 设为 1，否则调试接口不会有任何输出。

以下信号用来向外界打印调试信息。调试信息是一个 ASCII 码字节流，是人类可读的。当 debug_en=1 时， debug_data 上出现一个字节。

// signals of usbfs_core_top.v
// debug output info, only for USB developers, can be ignored for normally use
output wire        debug_en,      // when debug_en=1 pulses, a byte of debug info appears on debug_data
output wire [ 7:0] debug_data,    // 
output wire        debug_uart_tx  // debug_uart_tx is the signal after converting {debug_en,debug_data} to UART (format: 115200,8,n,1). If you want to transmit debug info via UART, you can use this signal. If you want to transmit debug info via other custom protocols, please ignore this signal and use {debug_en,debug_data}.

为了方便使用，我还将 {debug_en,debug_data} 字节流转化位 UART 输出信号 debug_uart_tx ，可以将 debug_uart_tx 连接到电脑的 UART 上，用串口助手等软件来查看调试信息。

注意： UART 的配置应该为波特率=115200, 数据位=8，无校验位，停止位=1 。

下图展示了我的 USB UVC 设备插入电脑时 UART 上打印的调试数据。可以看到这是一个描述符枚举的过程。


图：USB UVC 设备插入电脑时 UART 上打印的调试数据。

因为 UART 的传输速度较慢，当大量的调试信息产生时，会有一部分调试信息被 UART 丢弃。例如当 UVC 进行视频传输时，因为传输的数据量很大，UART 打印的信息是不完整的。因此如果需要在大量数据通信的过程中查看调试信息，就不能用 UART ，而是用其它高速的通信方式将 {debug_en, debug_data} 发给 host-PC 来查看。

参考资料

https://www.usbmadesimple.co.uk/ : USB Made Simple
https://github.com/FengJungle/USB_Protocol_CH : USB 中文协议手册
https://www.usb.org/document-library/usb-20-specification : USB 2.0 Specification
https://www.usb.org/document-library/video-class-v11-document-set : USB Video Class (UVC) 1.1 Specification
https://www.usb.org/document-library/audio-device-class-spec-basic-audio-devices-v10-and-adopters-agreement : USB Audio Class (UAC) 1.0 Specification
https://www.usb.org/document-library/mass-storage-class-specification-overview-14 : USB Mass Storage Class (USB-MSC) 1.4 Specification
https://www.usb.org/document-library/class-definitions-communication-devices-12 : USB Communication Device Class (USB-CDC) 1.2 Specification
其它 FPGA 实现：
- https://github.com/avakar/usbcorev : 一个 USB-device 控制器，仅支持到了 transaction 层。
- http://jorisvr.nl/article/usb-serial : 一个 USB-CDC，VHDL实现，需要额外的 UTMI PHY。
- https://github.com/pbing/USB : 一个 Low Speed 的 USB-HID 实现。
- https://github.com/ultraembedded/cores : 包含一些 USB-host 和 USB-device 实现，需要 UTMI PHY 或 ULPI PHY。

WangXuan95 / FPGA-USB-Device .gitee-modal { width: 500px !important; }

FPGA USB-device

What and Why?

Features

Demonstration of USB devices

Compatibility for Operation Systems

Special thanks

Circuit connection

II List of Design code

Ⅲ USB audio

Test

Application development

IV USB camera

Test

Application development

Parameters of usb_camera_top.v

FRAME_TYPE="MONO"

FRAME_TYPE="YUY2"

Ports of usb_camera_top.v

Frame rate and performance

Ⅴ U disk

Test

Application development

VI USB keyboard

Test

Application development

Ⅶ USB-Serial

Test

Application development

Ⅷ Dual-channel USB-Serial

Test

Application development

Ⅸ Development using USB device core

Parameters of usbfs_core_top.v

Ports of usbfs_core_top.v

Clock and Reset

USB Signal

Signal for indicating whether the USB is plugged.

USB-transfer and USB-frame detection signal

Response signal of control transfer

IN endpoint (0x81~0x84) signals

OUT endpoint (0x01~0x04) signals

Debug output interface

References

FPGA USB-device

效果展示

兼容性

特别鸣谢

Ⅰ 电路连接

Ⅱ 代码文件一览

Ⅲ USB 音频

测试

应用开发

Ⅳ USB 摄像头

测试

应用开发

usb_camera_top.v 的参数

FRAME_TYPE="MONO"

FRAME_TYPE="YUY2"

usb_camera_top.v 的信号

帧率与性能

Ⅴ U盘

测试

应用开发

Ⅵ USB键盘

测试

应用开发

Ⅶ USB-Serial

测试

应用开发

Ⅷ 双通道 USB-Serial

测试

应用开发

Ⅸ 基于 USB device core 的二次开发

usbfs_core_top.v 的参数

usbfs_core_top.v 的信号

时钟与复位

USB 信号

用来指示USB是否被插入的信号

USB-transfer 和 USB-frame 检测信号

WangXuan95 / FPGA-USB-Device