GigaDevice Semiconductor Inc.

ARM® Cortex™ 32-bit MCU

USBFS/HS Firmware Library User Guide

Revision 1.0

(Apr. 2019 )
 GD32 USBFS/HS Firmware Library User Guide

Table of Contents
Table of Contents ........................................................................................................... 2
List of Figures ................................................................................................................ 3
List of Table .................................................................................................................... 4
1. USBFS/USBHS ......................................................................................................... 5
1.1. Brief ................................................................................................................................... 5
1.2. USBFS/USBHS principle brief ........................................................................................ 5
1.2.1. USBFS interface principle ....................................................................................................... 5
1.2.2. USBHS interface principle ...................................................................................................... 8

1.3. USBFS/USBHS module firmware ................................................................................. 10

1.3.1. USBFS/USBHS module firmware structure .......................................................................... 10
1.3.2. Underlying file and function introduction ............................................................................... 10
1.3.3. USB_Host middle layer file and library function introduction ................................................. 11
1.3.4. USB_Device middle layer file and library function introduction ............................................ 14
1.3.5. Application interface layer file and library function introduction ............................................ 16

1.4. USBFS host state machine ........................................................................................... 19

1.5. Interrupt handle .............................................................................................................. 22
1.6. USB DEMO ...................................................................................................................... 26
1.6.1. USB demo brief..................................................................................................................... 26
1.6.2. MSC host .............................................................................................................................. 26
1.6.3. HID keyboard device ............................................................................................................ 29

2. Revision history ..................................................................................................... 32

2
 GD32 USBFS/HS Firmware Library User Guide

List of Figures
Figure 1-1. USBFS structure diagram ................................................................................................. 6
Figure 1-2. USBFS connect diagram as host or device .................................................................. 7
Figure 1-3. USBFS connection diagram as OTG device................................................................. 8
Figure 1-4. USBHS structure diagram ................................................................................................. 9
Figure 1-5. External ULPI PHY connection diagram........................................................................ 9
Figure 1-6. GD32F4xx series MCU USBFS/USBHS structure...................................................... 10
Figure 1-7. User callback function structure ................................................................................... 17
Figure 1-8. USBFS host state machine lookup table..................................................................... 19
Figure 1-9. USBFS host state machine flow diagram ................................................................... 20
Figure 1-10. Enumeration state machine handle lookup table ................................................... 20
Figure 1-11. Enumeration state machine flow diagram ................................................................ 21
Figure 1-12. Control transfer state machine handle lookup table ............................................. 22
Figure 1-13. Control transfer state machine flow diagram .......................................................... 22
Figure 1-14. OUT endpoint interrupt handle function ................................................................... 24
Figure 1-15. IN endpoint interrupt handle function ....................................................................... 25
Figure 1-16. USBFS demo diagram .................................................................................................... 26
Figure 1-17. USBFS host U disk main function .............................................................................. 27
Figure 1-18. USBFS host U disk enumeration information.......................................................... 28
Figure 1-19. USBFS host connect U disk routine result............................................................... 29
Figure 1-20. USBFS main function ..................................................................................................... 30
Figure 1-21. HID device experiment result ....................................................................................... 31

3
 GD32 USBFS/HS Firmware Library User Guide

List of Table
Table 1-1. USB_FS characteristic ......................................................................................................... 6
Table 1-2. USB bottom layer file table ............................................................................................... 11
Table 1-3. usb_core.h/.c file function table ...................................................................................... 11
Table 1-4. USB_Host middle layer file ............................................................................................... 11
Table 1-5. usbh_core.h/.c file function table ................................................................................... 12
Table 1-6. usbh_ctrl.h/.c file function ................................................................................................ 12
Table 1-7. usbh_hcs.h/.c file function table ..................................................................................... 13
Table 1-8. usbh_int.h/.c file function table ....................................................................................... 13
Table 1-9. usbh_std.h/.c file function table ...................................................................................... 13
Table 1-10. USB_Device middle layer file ......................................................................................... 14
Table 1-11. usbd_core.h/.c file function table ................................................................................. 14
Table 1-12. usbd_int.h/.c file function table ..................................................................................... 15
Table 1-13. usbd_std.h/.c file function table.................................................................................... 15
Table 1-14. Application interface layer file table ............................................................................ 16
Table 1-15. Main.c file function table ................................................................................................. 16
Table 1-16. usr_cb user callback function structure function .................................................... 17
Table 1-17. usb_delay.c file function table ...................................................................................... 17
Table 1-18. HID/MSC host class library function ............................................................................ 18
Table 1-19. USB globle interrupt......................................................................................................... 22
Table 2-1. Revision history ................................................................................................................... 32

4
 GD32 USBFS/HS Firmware Library User Guide
1. USBFS/USBHS

1.1. Brief

Basing on universal serial bus full speed / high speed interface structure, this article
introduce the interface principle and firmware structure of USBFS/USBHS, briefly describe
the firmware function performance, host state machine and USB interrupt mechanism.
Taking the MSC host and HID device for example, the article show the USB host and device
demo implementation.

1.2. USBFS/USBHS principle brief

At present, GD32F105/107/205/207/305/307/350/4xx/E103 series have USBFS interface

module, the framework of all series MCU USBFS is same. This article introduce principle of
the most advanced MCU series of GD, GD32F4xx, which have both USBFS and USBHS.

As device, USBFS only support FS (12Mbps) device, meanwhile, as host, USBFS support
FS (12Mbps) and LS (1.5Mbps) device. To be dual role device, USBFS could be configured
as host or device. In OTG mode, the switch between host and device should conform to SRP
protocol and HNP protocol.

USBHS not only support all common characteristic and function, which USBFS support, but
also support USB2.0 HS (480Mbps) host and device.

1.2.1. USBFS interface principle

USBFS structure

As the block diagram of Figure 1-1. USBFS structure diagram shown, Cortex-M core read
and write USBFS module register through AHB slave bus. USBFS register generate USB
interrupt for NVIC. There is 1.25KB data FIFO for USBFS, which is connected to SIE. In
device mode, FIFO is compose of one receive FIFO and multiple FIFOs. Every IN endpoint
own its transmit FIFO, and all OUT endpoints share receive FIFO. In host mode, data FIFO
divide into three parts, one is receive FIFO which is used to receive data, one is periodical
transmit FIFO which is used to transmit periodical data, and the other one is non-periodical
transmit FIFO which is used to transmit non-periodical data. All IN channel share receive
FIFO, all periodical OUT channel share periodical transmit FIFO and all non-periodical OUT
channel share non-periodical transmit FIFO. Data FIFO is connected to SIE. USB clock
domain comes from internal 48MHz clock. Through UIMI, USBFS controller is connected to
USBFS PHY, which is used to realize USB communication and compose of USB receiver
and USB interface circuit.

5
 GD32 USBFS/HS Firmware Library User Guide
Figure 1-1. USBFS structure diagram

USB Interrupt

Register

Device Bus Host Port

Control Control
Data DP
FIFO Transcation OTG UTMI DM
Scheduler Control MUX USB FS PHY
ID
VBUS
SIE
USB Clock
48MHz USB Clock Domain

USBFS module character

Table 1-1. USB_FS characteristic

Host characteristic Device characteristic

8 host channels 4 bidirectional endpoints (include endpoint 0)
dedicated TX_FIFO
1, periodical TX_FIFO：storage synchronization and
Four independent TX_FIFO corresponding to
interrupt transfer data
its IN endpoint
2, non-periodical TX_FIFO: storage bulk and control
transfer data
One shared RX_FIFO to receive data one shared RX_FIFO
Support power for connected device through
support software disconnect
external power chip
Support USB 2.0 FS/LS host mode Support USB 2.0 FS device mode
Two request queue:
1,periodical queue: manage utmost 8
synchronization and interrupt transfer request
2,non-periodical queue: manage utmost 8 bulk and
control transfer request
Support four kinds of transfer: control transfer, bulk transfer, interrupt transfer and synchronization
transfer
Support HNP protocol , SRP protocol and OTG protocol

USBFS host mode

There is four condition when USBFS is identified as host

1, insert USB A port when USBFS interface is configured as default.

2, insert USB B port, then USBFS interface module is HNP switched.

3, HNP bit of USB configuration register is write to be 0.

6
 GD32 USBFS/HS Firmware Library User Guide
4, force host mode bit of USB global configuration register is set, just only treat USB as host,
in this condition, ignore ID line state and enable integrate pull-down resistor in DP and DM
line

USBFS host or device connection diagram is shown in Figure 1-2. USBFS connect
diagram as host or device. If USBFS is configured as host, it should supply 5V power, in
this case, 5V power is external USB device power supply.

USBFS device mode

There is four conditions when USBFS is identified as device

1, insert USB B port when USBFS interface is configured as default.

2, insert USB A port, then USBFS interface module is HNP switched.

3, HNP bit of USB configuration register is write to be 0.

4, force device mode bit of USB global configuration register is set, just only treat USB as
device.

USBFS connection diagram is shown as below. If USBFS is host, 5V power supply is

unnecessary, VBUS pin detect VBUS voltage, detect whether host is disconnect. DP and
DM line represent differential signal line.

Figure 1-2. USBFS connect diagram as host or device

VDD

USBFS
5V Supply Power
(necessary in host
GPIO
mode)
USB A/B connector

VBUS VBUS

DM DM

DP
DP
GND

USBFS OTG mode

USBFS OTG connection diagram is shown in Figure 1-3. USBFS connection diagram as
OTG device. Except common four wires in USB, ID wire, which indicates role of USBFS, is
necessary. If USB cable B port is connected, its ID wire is floating, high level of ID wire will
be detected, and USBFS is configured as slave device default. If USB cable A port is

7
 GD32 USBFS/HS Firmware Library User Guide
connected, its ID wire is on the ground, USBFS will generate ID wire status change interrupt
to initial host software, and switch to host automatically.

GPIO port is used to control generating 5V power supply, and this power is input from
external, to be USBFS A device, supply power for other device and MCU. VBUS pin is used
to detect VBUS voltage.

Figure 1-3. USBFS connection diagram as OTG device

1.2.2. USBHS interface principle

USBHS interface module include an embedded USBFS PHY, the function of this PHY is
stronger than the function of USBFS module, it could support 6 bidirectional device
endpoints, 12 host channels and 4K bytes FIFO, thus, USBHS realize full speed and low
speed by USBFS PHY. Moreover, if ULPI interface is connected to USBHS, it could realize
USB high speed communication, its data transfer rate is up to 480Mbps. When USBHS is in
high speed host mode, USBHS support hub connection. In addition, there is DMA engine in
USBHS, which could accelerate data transfer rate between USBHS and system.

USBHS structure

USBHS structure diagram is shown in Figure 1-4. USBHS structure diagram.

Corresponding to USBFS, DMA transfer engine and ULPI interface is added in USBHS
structure diagram.

8
 GD32 USBFS/HS Firmware Library User Guide
Figure 1-4. USBHS structure diagram

USB interrupt

Device bus Host Port

control Control UTMI To ULPI
ULPI Interface
Data
DMA FIFO Transcation OTG UTMI
Scheduler Control Mux
DP
DM
USB FS PHY
SIE ID
USB Clock VBUS
48MHz/60MHz USB Clock Domain

USBHS external ULPI PHY

USBHS provide an ULPI interface to external PHY, if USBHS module try to realize USBHS
application, external HS ULPI PHY is necessary. Combining external ULPI PHY, USBHS
support high speed host and device, meanwhile, support all modes which USBFS PHY
support.

Software need clearing EMBPHY bit of USBHS_GUSBCS register to enable ULPI interface.
When ULPI mode enable, 60MHz clock need be input from ULPI_CLK pin. Software could
open or close 60MHz ULPI clock in RCU register.

Figure 1-5. External ULPI PHY connection diagram.

5V Supply Power
if necessary

USBHS GPIO
USB Micro/Mini

ULPI_D[7:0]
connector

ULPI_DIR VBUS
External
DP
ULPI_NXT ULPI PHY DM
ULPI_STP ID
ULPI_CLK

9
 GD32 USBFS/HS Firmware Library User Guide
1.3. USBFS/USBHS module firmware

1.3.1. USBFS/USBHS module firmware structure

GD32F4xx series MCU interface module structure diagram is shown in Figure 1-6.
GD32F4xx series MCU USBFS/USBHS structure. The figure show USBFS/USBHS host
and device structure. User application call GD32 USB firmware library to realize USB data
communication. The bottom of structure is hardware of MCU evaluation board. There is
three layers in GD32 USBFS/USBHS firmware library. The top is application interface layer,
user could change. Middle layer is USB host or USB device, the bottom layer is USB drivers.
Middle layer and bottom layer are called as “USB firmware library driver”, user could not
modify it. USB class file, which implement USB host application class or USB application
device class file, is part of application layer.

Figure 1-6. GD32F4xx series MCU USBFS/USBHS structure

1.3.2. Underlying file and function introduction

USB Driver underlying file include two files, which are shown in Table 1-2. USB bottom
layer file table.

10
 GD32 USBFS/HS Firmware Library User Guide
Table 1-2. USB bottom layer file table
File name Tips
usb_core.h/.c USB core driver
usb_reg.h USB register operation

Table 1-3. usb_core.h/.c file function table

Function name Functional description
usb_commonint_enable enable common interrupt
usb_core_reset USB core reset
write a packet into Tx FIFO of corresponding
usb_fifo_write
endpoint
read a packet from Rx FIFO of corresponding
usb_fifo_read
endpoint
usb_core_select select USB core
usb_core_init Initial USB controller register and parameter
usb_txfifo_flush Flush a Tx FIFO and all Tx FIFO
usb_rxfifo_flush Flush all Rx FIFO
usb_mode_set configure operation mode(host or device )
usb_hostcore_init Initial USB core for host mode
usb_vbus_drive configure USB interface power
usb_hostint_enable enable host mode interrupt
usb_port_reset reset host channel
usb_hostchannel_init initial host channel
usb_hostchannel_startxfer host channel start transmit
usb_hostchannel_halt halt channel
usb_hostchannel_ping transmit a PING token
usb_host_stop stop host and clear FIFOS
usb_devcore_init Initial USB core register for device mode
usb_devint_enable enable device mode interrupt
usb_ep0_startout Configure endpoint 0 start receive SETUP token
usb_remotewakeup_active start remote wakeup
usb_clock_ungate start USB core clock
usb_device_stop halt USB device an d clear FIFOS

1.3.3. USB_Host middle layer file and library function introduction

USB_Host middle layer include 5 files, which are shown in Table 1-4. USB_Host middle
layer file.

Table 1-4. USB_Host middle layer file

File name Functional description
usbh_core.h/.c USB host state machine handle function
usbh_ctrl.h/.c USB host control transfer handle function
usbh_hcs.h/.c USB open or close channel handle function
11
 GD32 USBFS/HS Firmware Library User Guide
usbh_int.h/.c USB host mode interrupt handle function
usbh_std.h/.c USB communication handle function

Table 1-5. usbh_core.h/.c file function table

Function name Functional description
host_state_polling_fun host state machine polling function
host_idle_handle HOST_IDLE state handle function
host_dev_attached_handle HOST_DEV_ATTACHED state handle function
host_enum_handle HOST_ENUMERATION state handle function
host_user_input_handle HOST_USER_INPUT state handle function
HOST_CLASS_REQUEST state handle
host_class_request_handle
function
host_class_handle HOST_CLASS state handle function
host_suspended_handle HOST_SUSPENDED state handle function
host_error_handle HOST_ERROR state handle function
host_dev_detached_handle HOST_DEV_DETACHED state handle function
HOST_DETECT_DEV_SPEED state handle
host_detect_dev_speed_handle
function
usbh_connected device connection interrupt callback function
device disconnection interrupt callback
usbh_disconnected
function
usbh_sof sof interrupt callback function
hcd_init host core driver initialization
hcd_is_device_connected check whether device is connected
hcd_urb_state_get return latest URB state
hcd_xfer_count_get return transfer data size
usbh_deinit de-initialize host
scd_init state machine core driver initialize
scd_table_regist state machine core driver state table
scd_begin state machine driver start
scd_state_move state machine core driver state switch
scd_event_handle state machine core driver event handle
scd_table_push push current state machine into state stack
scd_table_pop pop current state machine from state stack
device class request state machine polling
class_req_state_polling_fun
function
class_state_polling_fun device class state machine polling function
only_state_move state switch function
goto_up_state_fun return upper state machine

Table 1-6. usbh_ctrl.h/.c file function

12
 GD32 USBFS/HS Firmware Library User Guide
Function name Functional description
ctrl_state_polling_fun Control transfer state machine polling function
ctrl_idle_handle CTRL_IDLE state machine handle function
ctrl_setup_handle CTRL_SETUP state machine handle function
ctrl_data_handle CTRL_DATA state machine handle function
ctrl_status_handle CTRL_STATUS state machine handle function
ctrl_error_handle CTRL_ERROR state machine handle function
ctrl_stalled_handle CTRL_STALLED state machine handle function
ctrl_complete_handle CTRL_COMPLETE state machine handle function
usbh_xfer transmit data form host port
usbh_ctltx_setup Transmit SETUP token packet to device
hcd_submit_request prepare channel, start once transfer

Table 1-7. usbh_hcs.h/.c file function table

Function name Functional description
usbh_channel_open open host channel
usbh_channel_modify update channel
usbh_channel_alloc configure new channel for pipe
usbh_channel_free release USB host channel
usbh_allchannel_dealloc release all USB host channel
achieve a free host channel for configured device
usbh_freechannel_get
endpoint

Table 1-8. usbh_int.h/.c file function table

Function name Functional description
usbh_isr handle global host interrupt
usbh_intf_sof Sof interrupt handle
usbh_intf_hc handle all host channel interrupt
usbh_intf_disconnect handle disconnect interrupt
usbh_intf_nptxfifo_empty handle non-periodic transmit FIFO empty interrupt
usbh_intf_ptxfifo_empty handle periodic transmit FIFO empty interrupt
usbh_intf_port handle host port interrupt
usbh_intf_hc_out handle out channel interrupt
usbh_intf_hc_in handle in channel interrupt
usbh_intf_rxfifo_noempty handle receive FIFO non empty interrupt
usbh_intf_iso_incomplete_xfer handle Incomplete periodic transfer interrupt

Table 1-9. usbh_std.h/.c file function table

Function name Functional description
enum_state_polling_fun enumeration state machine polling function

13
 GD32 USBFS/HS Firmware Library User Guide
enum_idle_handle ENUM_IDLE state handle function
ENUM_GET_FULL_DEV_DESC state handle
enum_get_full_dev_desc_handle
function
enum_set_addr_handle ENUM_SET_ADDR state handle function
enum_get_cfg_desc_handle ENUM_GET_CFG_DESC state handle function
ENUM_GET_FULL_CFG_DESC state handle
enum_get_full_cfg_desc_handle
function
ENUM_GET_MFC_STRING_DESC state handle
enum_get_mfc_string_desc_handle
function
ENUM_GET_PRODUCT_STRING_DESC state
enum_get_product_string_desc_handle
handle function
ENUM_GET_SERIALNUM_STRING_DESC state
enum_get_serialnum_string_desc_handle
handle function
ENUM_SET_CONFIGURATION state handle
enum_set_configuration_handle
function
enum_dev_configured_handle ENUM_DEV_CONFIGURED state handle function
usbh_enum_desc_get get descriptor in host enumeration phase
usbh_enum_addr_set configure address in host enumeration phase
usbh_enum_cfg_set set configuration in host enumeration phase
usbh_device_desc_parse analysis device descriptor
usbh_cfg_desc_parse analysis device descriptor
usbh_interface_desc_parse analysis interface descriptor
usbh_endpoint_desc_parse analysis endpoint descriptor
usbh_string_desc_parse analysis character string descriptor
usbh_next_desc_get get next descriptor packet header

1.3.4. USB_Device middle layer file and library function introduction

Table 1-10. USB_Device middle layer file

Function name Functional description
usbd_core.h/.c USB device mode core driver
usbd_int.h/.c USB device mode interrupt routines
usbd_std.h/.c USB 2.0 standard handler driver

Table 1-11. usbd_core.h/.c file function table

Function name Functional description
initailizes the USB device-mode handler
usbd_init
stack
usbd_ep_init endpoint initialization
usbd_ep_deinit endpoint deinitialize
usbd_ep_rx endpoint prepare to receive data
usbd_ep_tx endpoint prepare to transmit data
usbd_status_enum usbd_ctltx transmit data on the control endpoint

14
 GD32 USBFS/HS Firmware Library User Guide
usbd_status_enum usbd_ctlrx receive data on the control endpoint
usbd_status_enum usbd_ctlstatus_tx transmit status on the control endpoint
usbd_status_enum usbd_ctlstatus_rx receive status on the control endpoint
usbd_ep_stall set an endpoint to STALL status
usbd_ep_clear_stall clear endpoint stalled status
usbd_ep_fifo_flush flushes the fifos
usbd_rxcount_get get the received data length

Table 1-12. usbd_int.h/.c file function table

Function name Functional description
USB device-mode interrupts global service
usbd_isr
routine handler
indicates that an OUT endpoint has a
usbd_intf_outep
pending interrupt
indicates that an in endpoint has a pending
usbd_intf_inep
interrupt
indicates that early suspend state has been
usbd_intf_earlysuspend
detected on the USB
indicates that suspend state has been
usbd_intf_suspend
detected on the USB
indicates that the USB controller has
usbd_intf_resume detected a resume or remote Wake-up
sequence
usbd_intf_sof handle the SOF interrupts
usbd_intf_rxfifo handle the rx FIFO non-empty interrupt
usbd_intf_reset handle USB reset interrupt
usbd_intf_enumfinish handle enumeration finish interrupt
usbd_intf_isoinincomplete handle the ISO in incomplete interrupt
usbd_intf_isooutincomplete handle the ISO OUT incomplete interrupt
usbd_emptytxfifo_write check FIFO for the next packet to be loaded
indicates that the USB_OTG controller has
usbd_intf_sessionrequest
detected a connection
indicates that the USB_OTG controller has
usbd_intf_otg
detected an OTG event

Table 1-13. usbd_std.h/.c file function table

Function name Functional description
usbd_setup_transaction USB setup stage processing
usbd_out_transaction data out stage processing
usbd_in_transaction data in stage processing
usbd_standard_request handle USB standard device request
usbd_device_class_request handle USB device class request
usbd_vendor_request handle USB vendor request
usbd_reserved no operation, just for reserved
15
 GD32 USBFS/HS Firmware Library User Guide
usbd_device_descriptor_get get the device descriptor
usbd_configuration_descriptor_get get the configuration descriptor
usbd_string_descriptor_get get string descriptor
usbd_getstatus handle Get_Status request
usbd_clrfeature handle USB Clear_Feature request
usbd_setfeature handle USB Set_Feature request
usbd_setaddress handle USB Set_Address request
usbd_getdescriptor handle USB Get_Descriptor request
usbd_setdescriptor handle USB Set_Descriptor request
usbd_getconfig handle USB Get_Configuration request
usbd_setconfig handle USB Set_Configuration request
usbd_getinterface handle USB Get_Interface request
usbd_setinterface handle USB Set_Interface request
usbd_synchframe handle USB SynchFrame request
usbd_setup_request_parse decode setup data packet
usbd_enum_error handle USB low level error event

1.3.5. Application interface layer file and library function introduction

Application layer include four files, which are shown in Table 1-14. Application interface
layer file table

Table 1-14. Application interface layer file table

File name Introduction
main.c main application program interface
usbh_usr.c user application program interface
usb_delay.c delay function interface
USB Class device class application program interface

Main.c file mainly realize main application program interface function, it is shown in Table
1-15. Main.c file function table.

Table 1-15. Main.c file function table

Function name Functional description
main application program main function
usb_rcu_init USB RCU initialization
usb_gpio_init USB GPIO initialization
usb_hwp_interrupt_enable configure USB global interrupt
usb_hwp_vbus_drive drive VBUS signal line via GPIO
usb_hwp_vbus_config configure VBUS pin

usbh_usr.c file contains user callback function structure, which is shown in Figure 1-7. User
callback function structure.
16
 GD32 USBFS/HS Firmware Library User Guide
Figure 1-7. User callback function structure

Table 1-16. usr_cb user callback function structure function

Function name Functional description
init initialize user operation in host mode
deinit configure user as default
device_connected user operation of USB connection
device_reset user operation of device resetting
device_disconnected user operation of USB disconnection
over_current_detected user operation of device overloading
device_speed_detected user operation of detecting device speed
device_desc_available user operation when device descriptor is available
device_address_set user operation when device is successfully configured
user operation when configuration descriptor is
configuration_desc_available
available
manufacturer_string user operation when vendor string is available
product_string user operation when product string is available
serial_num_string user operation when serial number is exist
enumeration_finish user operation when enumeration is accomplished
user_input user operation when entering user state
user_application user application program
device_not_supported user operation when device is not supported
unrecovered_error user operation when unrecoverable error happen

Table 1-17. usb_delay.c file function table

Function name Functional description
usb_time_init utilize timer 2 initialize delay unit
usb_udelay delay function in microseconds
usb_mdelay delay function in millisecond
hwp_delay hardware delay function

17
 GD32 USBFS/HS Firmware Library User Guide
hwp_time_set hardware timer initialization

USB class include host class function file, USB protocol support serval class, as shown in
Table 1-18. HID/MSC host class library function, HID and MSC host class function file
would be introduced.

Table 1-18. HID/MSC host class library function

Device class File name Function name Description
HID request state machine
hid_req_state_polling_fun
polling function
HID state machine polling
hid_state_polling_fun
function
hid_clear_feature HID clear characteristic
usbh_hid_cor
usbh_hid_desc_parse analysis HID descriptor
e.h/c
usbh_hid_interface_init initialize HID class interface
recover default configuration
usbh_hid_interface_deinit
for host channel of HID class
hid_req_set_idle set idle state
HID host class hid_req_set_protocol set protocol state
Usbh_hid_ke
keybrd_decode analysis keyboard keys
ybd.h/c
mouse_init initialize mouse state
mouse_decode analysis mouse data
analysis mouse button press
hid_mouse_button_pressed
usbh_hid_mo function
use.h/c analysis mouse button release
hid_mouse_button_released
function
update mouse position
hid_mouse_update_position
function
usbh_msc_init initialize MSC parameters
usbh_msc_handle_botxfer handle BOT transfer state
usbh_msc_b handle abort error for STALL
usbh_msc_bot_abort
ot.h/c state
decode CSW command block
usbh_msc_decode_csw
packet
usbh_msc_interface_init initialize MSC interface
MSC host class usbh_msc_interface_deinit recover interface default state
handle MSC request polling
msc_req_state_polling_fun
usbh_msc_co function
re.h/c msc_state_polling_fun MSC state polling function
usbh_msc_max_lun_get get MSC max logic unit
usbh_msc_error_handle handle MSC error event
usbh_clear_feature clear or forbidden feature
usbh_msc_sc usbh_msc_test_unit_ready transmit test unit ready
18
 GD32 USBFS/HS Firmware Library User Guide
si.c commamd to device
transmit read capacity 10
usbh_msc_read_capacity10
command to device
transmit mode sense 6
usbh_msc_mode_sense6
command to device
transmit request sense
usbh_msc_request_sense
command to device
transmit write 10 command to
usbh_msc_write10
device
transmit read 10 command to
usbh_msc_read10
device
disk_initialize initialize disk driver
disk_status get disk status
usbh_msc_fa
disk_read read disk section
tfs.h/c
disk_write write disk section
disk_ioctl IO control function

1.4. USBFS host state machine

USBFS host state machine apply state machine nesting and state machine lookup table
method. USBFS host machine include host machine handle (usbh_core.c), enumeration
state machine handle (usbh_std.c) and control transfer state machine handle (usbh_ctrl.c).

USBFS host state lookup table is shown as Figure 1-8. USBFS host state machine lookup
table, firstly, introduce the methods to lookup table, the table is consist of nine items. Every
item, which contain four parts, is state switch. The first part is current status, the second part
is current received event, the third part is the next status to which will switch, and the fourth
part is event handle function which the status switch need. It means that, in current status, if
receive current corresponding event, through lookup table and execute event function,
switch to next status. It is easily to understand state machine lookup table.

Figure 1-8. USBFS host state machine lookup table

19
 GD32 USBFS/HS Firmware Library User Guide
Figure 1-9. USBFS host state machine flow diagram

According to lookup state machine table, in HOST_DEV_ATTACHED status, if receive

HOST_EVENT_ENUM event, then enter HOST_ENUMERATION status, so as to handle
enumeration state machine, which is shown in Figure 1-10. Enumeration state machine
handle lookup table and Figure 1-11. Enumeration state machine flow diagram. In
processing of switch host state machine to enumeration state machine, function
scd_table_push ( ) save last state machine to state machine stack, so as to return upper
state machine and continue previous operation.

Figure 1-10. Enumeration state machine handle lookup table

20
 GD32 USBFS/HS Firmware Library User Guide
Figure 1-11. Enumeration state machine flow diagram

According to lookup enumeration state machine table, in ENUM_DEV_CONFIGURED status,

if receive UP_STATE event, it indicate enumeration is completed, function scd_table_pop ()
return to upper state machine. Moreover, in the processing of enumeration, it is necessary to
adopt control transfer, continue to enter control transfer state machine. Control transfer state
machine lookup table is shown in Figure 1-12. Control transfer state machine handle
lookup table, control transfer state machine flow diagram is shown in Figure 1-13. Control
transfer state machine flow diagram.

21
 GD32 USBFS/HS Firmware Library User Guide
Figure 1-12. Control transfer state machine handle lookup table

Figure 1-13. Control transfer state machine flow diagram

In the processing of control transfer, initial status is CTRL_IDLE, once control completed, the
status switch to CTRL_COMPLETE, then return upper state machine.

1.5. Interrupt handle

Interrupt of USBD module contain low priority interrupt and high priority interrupt. Commonly,
IN and OUT transaction transfer, which are distinguished by IFR_DIR flag, would been
handled in low priority interrupt. There are two different interrupts for IN and OUT transaction
of USBFS, whose respective flag of interrupt is GINTF_IEPIF and GINTF_OEPIF, which are
shown in Figure 1-13. Control transfer state machine flow diagram. OUT endpoint
interrupt handle function is shown in Figure 1-14. OUT endpoint interrupt handle
function.

Table 1-19. USB globle interrupt

Interrupt Flag Description Operation Mode

SEIF Session interrupt Host or device mode

DISCIF Disconnect interrupt flag Host Mode

IDPSC ID pin status change Host or device mode

22
 GD32 USBFS/HS Firmware Library User Guide
Interrupt Flag Description Operation Mode

PTXFEIF Periodic Tx FIFO empty interrupt flag Host Mode

HCIF Host channels interrupt flag Host Mode

HPIF Host port interrupt flag Host Mode

ISOONCIF/PXNCI Periodic transfer Not Complete Host or device mode

F Interrupt flag /Isochronous OUT
transfer Not Complete Interrupt Flag

ISOINCIF Isochronous IN transfer Not Complete Device mode

Interrupt Flag

OEPIF OUT endpoint interrupt flag Device mode

IEPIF IN endpoint interrupt flag Device mode

EOPFIF End of periodic frame interrupt flag Device mode

ISOOPDIF Isochronous OUT packet dropped Device mode

interrupt flag

ENUMF Enumeration finished Device mode

RST USB reset Device mode

USB suspend
SP Device mode
Early suspend
ESP Device mode
Global OUT NAK effective
GONAK Device mode
Global IN Non-Periodic NAK effective
GNPINAK Device mode
Non-Periodic Tx FIFO empty interrupt
NPTXFEIF Host Mode
flag
Rx FIFO non-empty interrupt flag
RXFNEIF Host or device mode
Start of frame
SOF Host or device mode
OTG interrupt flag
OTGIF Host or device mode
Mode fault interrupt flag
MFIF Host or device mode

23
 GD32 USBFS/HS Firmware Library User Guide
Figure 1-14. OUT endpoint interrupt handle function

In OUT endpoint interrupt handler function, depending on endpoint interrupt flag register,
interrupt event of OUT endpoint could be distinguished. The events include such events
below: transfer finished event, endpoint disabled event, SETUP phase finished event,
endpoint Rx FIFO overrun event and back-to-back SETUP packets event. When OUT
endpoint event is generated, polling interrupt flag is easy to enter corresponding interrupt
handler function. IN endpoint interrupt handle function is shown in Figure 1-15. IN endpoint
interrupt handle function.

24
 GD32 USBFS/HS Firmware Library User Guide
Figure 1-15. IN endpoint interrupt handle function

In IN endpoint interrupt handler function, depending on IN endpoint interrupt flag register,

interrupt event of IN endpoint could be distinguished. The events include such events below:
transfer finished event, endpoint disabled event, control In Timeout interrupt event, endpoint
Tx FIFO underrun event, IN endpoint NAK effective event and Transmit FIFO empty event.
When IN endpoint event is generated, polling interrupt flag is easy to enter corresponding
interrupt handler function.

25
 GD32 USBFS/HS Firmware Library User Guide
1.6. USB DEMO

1.6.1. USB demo brief

Figure 1-16. USBFS demo diagram

As shown in Figure 1-16. USBFS demo diagram, USB demo compose of host demo and
device demo. Host contain HID host, MSC host, CDC host and IAP host. Device compose of
compsite device and single device. Compsite device could be composed of different device,
like HID and CDC compsite device, MSC and CDC compsite device, CDC and Printer
compsite device and HID and MSC device. According to application protocol, single device
include DFU, HID, Audio, Printer, MSC, CCID and CDC device. There are severval sub HID
class, such as mouse, keyboard, IAP and multi-touch device. MSC device have severval sub
MSC class, like CD-ROM and U-disk device, whose storage medium is MCU flash, SPI flash,
Nand flash, SD card, MCU SRAM and external SRAM. In above those demo, MSC host
demo and HID keyboard demo are selected to introduce Working principle and operating
results of host and device.

1.6.2. MSC host

Overview

The demo briefly introduce USBFS host as U disk, once U disk is connected to GD32F450i

26
 GD32 USBFS/HS Firmware Library User Guide
board, USBFS enumerate the U disk. After U disk completed enumeration, user application
start, the demo could read U disk file index and write file to U disk.

Main function introduction

In the demo, there is USBFS host initialization section before while (1), after initialization,
program enter main loop and start USBFS host machine, which would be introduced as
below.

Figure 1-17. USBFS host U disk main function

MSC host experiment result

Download MSC_Host/GD32450I_EVAL_Fullspeed project code to GD32F450i board, and

connect U disk to USBFS via OTG cable, run the program, user could observe U disk
enumeration information, which is shown in Figure 1-18. USBFS host U disk enumeration
information.

27
 GD32 USBFS/HS Firmware Library User Guide
Figure 1-18. USBFS host U disk enumeration information

Firstly, press User key, screen shown U disk information, then press Tamper key, screen
shown root index content. Pressing Wakeup key is writing file to U disk, then user could
observe MSC host demo complete information, which is shown in Figure 1-19. USBFS host
connect U disk routine result.

28
 GD32 USBFS/HS Firmware Library User Guide
Figure 1-19. USBFS host connect U disk routine result

1.6.3. HID keyboard device

Overview

The demo briefly introduce USBFS device, as keyboard, once GD32F450i board is
connected to host, host enumerate the board as keyboard. Press the board key is print the
corresponding character, pressing the tamper key would output ‘a’, pressing the wakeup key
would output ‘b’, pressing the user key would output ‘c’.

Main function and initialization

USBFS interface module work in device mode, the demo enumerate USBFS device as
keyboard, and its main function is shown in Figure 1-20. USBFS main function

29
 GD32 USBFS/HS Firmware Library User Guide
Figure 1-20. USBFS main function

In the processing of initialization, DP pin doesn`t pull-up, it is difference between USBFS

device and USBD device.

30
 GD32 USBFS/HS Firmware Library User Guide
DP pin pull up and disconnect

When DP pin pull-up of USBFS device is automatically realized through hardware detected,
software do not need operation. When VBUS pin detect B class convention is active level,
USBFS interface module could automatically connect pull-up resistance on DP pin, so as to
send full speed device connected signal to host, and trigger device interrupt (SESIF@
USBFS_GINTF).

When MCU detected that VBUS pin voltage level is lower than B class convention valid
voltage level, USBFS module will automatically disconnect, and trigger device interrupt
(SESEND@USBFS_GOTGINTF). Moreover, software is also used to disconnect device.
Configuring software disconnected bit (SD@USBFS_DCTL) of device control register, so as
to enable software disconnect. Then, USBFS interface module remove pull-up resistance on
DP pin, brings out detecting interrupt of device disconnect, thus, even if USB cable is remain
connected, device disconnect interrupt could be identified still.

HID keyboard device experiment result

Download HID_Keyboard/GD32450I_EVAL_Fullspeed project code to GD32F450i EVAL

board, and connect U disk to USBFS via OTG cable, run the program, as shown in Figure
1-21. HID device experiment result, if user press Wakeup key, Tamper key or User key,
correspondingly output ‘b’, ’a’ or ’c’.

Figure 1-21. HID device experiment result

31
 GD32 USBFS/HS Firmware Library User Guide
2. Revision history

Table 2-1. Revision history

Revision No. Description Date
1.0 Initial Release Apr.1st, 2019

32
 GD32 USBFS/HS Firmware Library User Guide

Important Notice
This document is the property of GigaDevice Semiconductor Inc. and its subsidiaries (the "Company"). This document, including any
product of the Company described in this document (the “Product”), is owned by the Company under the intellectual property laws and
treaties of the People’s Republic of China and other jurisdictions worldwide. The Company reserves all rights under such laws and
treaties and does not grant any license under its patents, copyrights, trademarks, or other intellectual property rights. The names and
brands of third party referred thereto (if any) are the property of their respective owner and referred to for identification purposes only.

The Company makes no warranty of any kind, express or implied, with regard to this document or any Product, including, but not
limited to, the implied warranties of merchantability and fitness for a particular purpose. The Company does not assume any liability
arising out of the application or use of any Product described in this document. Any information provided in this document is provided
only for reference purposes. It is the responsibility of the user of this document to properly design, program, and test the functionality
and safety of any application made of this information and any resulting product. Except for customized products which has been
expressly identified in the applicable agreement, the Products are designed, developed, and/or manufactured for ordinary business,
industrial, personal, and/or household applications only. The Products are not designed, intended, or authorized for use as
components in systems designed or intended for the operation of weapons, weapons systems, nuclear installations, atomic energy
control instruments, combustion control instruments, airplane or spaceship instruments, transportation instruments, traffic signal
instruments, life-support devices or systems, other medical devices or systems (including resuscitation equipment and surgical
implants), pollution control or hazardous substances management, or other uses where the failure of the device or Product could
cause personal injury, death, property or environmental damage ("Unintended Uses"). Customers shall take any and all actions to
ensure using and selling the Products in accordance with the applicable laws and regulations. The Company is not liable, in whole or
in part, and customers shall and hereby do release the Company as well as it’s suppliers and/or distributors from any claim, damage,
or other liability arising from or related to all Unintended Uses of the Products. Customers shall indemnify and hold the Company as
well as it’s suppliers and/or distributors harmless from and against all claims, costs, damages, and other liabilities, including claims for
personal injury or death, arising from or related to any Unintended Uses of the Products.

Information in this document is provided solely in connection with the Products. The Company reserves the right to make changes,
corrections, modifications or improvements to this document and Products and services described herein at any time, without notice.

© 2019 GigaDevice – All rights reserved

33