USB Introduction

Overview

Supported ICs[ RTL8721Dx ][ RTL8730E ][ RTL8721F ]

USB (Universal Serial Bus) is a standard serial communication interface designed to interconnect host controllers and peripheral devices.

The complete USB specification suite, including electrical, mechanical, and protocol layer documentation, is accessible at http://www.usb.org/developers.

Note

Due to the incomplete official USB protocol stack of Zephyr, which only supports device mode. Therefore, we choose not to use the official source code, but instead provide the Realtek USB stack. This chapter briefly introduces the Realtek USB stack, and how to compile and run application examples.

Features

• Supports USB2.0 high-speed (480 Mbps) and full-speed (12 Mbps) modes

• Supports the following USB host solutions:

  • CDC ACM: Implement bidirectional transparent data transmission function, suitable for application scenarios such as serial communication and data collection

  • UAC: Supports audio playback function and can be connected to USB audio devices for audio output

  • UVC: Supports USB video class camera capture, adapted for MJPEG/uncompressed video streams

  • HID+UAC composite host: supports both human-computer interaction and audio playback, achieving integrated control of button control and audio playback

  • DFU: Supports USB Device Firmware Upgrade host function for firmware updating of target devices

  • Vendor: A customized solution that breaks through the limitations of standard host classes and meets the personalized needs of special application scenarios

• Support the following USB device solutions:

  • CDC ACM: Supports bidirectional transparent data transmission and can be used as a virtual serial port

  • HID: Simulate standard HID peripherals such as USB keyboards and mice to achieve rich human-computer interaction functions

  • MSC: As a USB storage device, it realizes data storage and read-write functions (supports RAM disk and RAM + FatFs backend)

  • CDC ACM+HID composite device: supports both transparent communication and interactive control simultaneously

  • CDC ACM+MSC composite equipment: supports both transparent communication and data storage simultaneously

  • DFU: Supports USB Device Firmware Upgrade device function for in-field firmware updating

  • Vendor: Customized solutions that break through the limitations of standard equipment and meet the personalized needs of special application scenarios

• Support full customization of descriptors in device mode

  • VID and PID

  • String descriptors

  • Endpoint mapping

• Supports flexible device matching in host mode

  • Specify device matching strategy (such as matching VID/PID, or matching specific class protocols, etc.)

  • Automatically parse descriptors

  • Adaptive speed mode

• Configurable device core driver parameters

  • Speed mode

  • Data FIFO depth (only for dedicated FIFO mode)

  • Core ISR/thread priority

Note

USB host mode is supported on RTL8730E and RTL8721F . RTL8721Dx supports USB device mode only.

Hardware Features

RTL8721DxRTL8730ERTL8721F

RTL8721Dx:

• Supports device mode

• Supports USB 2.0 full-speed (12 Mbps) mode

• Supports DMA mode

• Endpoint configurations:

  • EP0: INOUT (for Control transfer only)

  • EP1: IN

  • EP2: OUT

  • EP3: IN

  • EP4: OUT

  • EP5: INOUT

Note

One and only one periodic IN endpoint is supported.

• Shared FIFO with following configurations:

  • Total FIFO depth: 768 DWORD

  • Shared receive FIFO: 472 DWORD (max)

  • Shared non-periodic transmit FIFO: 32 DWORD (max)

  • Dedicated periodic transmit FIFO: 256 DWORD (max)

Note

8 DWORD FIFO shall be reserved for DMA registers in DMA mode.

Software Stack Overview

Software stack architecture

Where:

• USB HAL driver: Implements SoC-specific hardware driver for power management and phy calibration, exposing unified HAL API to upper-layer core drivers.

• USB device core drivers: Integrates USB IP-specific hardware driver, device controller driver, enumeration state machine and transfer scheduling algorithms, exposing unified core API for designers to develop classes and applications.

• USB device class drivers: Delivers USB-IF class-compliant drivers via class-specific API, enabling rapid deployment of standard USB solutions.

• USB device applications: Provides reference designs for USB solutions.

Zephyr USB API is consistent with FreeRTOS USB API. For details, see FreeRTOS USB API

File Organization

RTL8721DxRTL8730ERTL8721F

RTL8721Dx:

SDK/modules/hal/realtek
├── ameba/common/usb/source
│   ├── common
│   │   ├── usb_cdc_acm.h
│   │   ├── usb_ch9.h
│   │   ├── usb_dfu.h
│   │   ├── usb_msc.h
│   │   ├── usb_os.h
│   │   ├── usb_ringbuf.h
│   │   ├── usb_scsi.h
│   │   ├── usb_uac1.h
│   │   └── usb_uac2.h
│   │
│   └── device
│       ├── cdc_acm
│       ├── composite
│       ├── dfu
│       ├── hid
│       ├── msc
│       ├── uac
│       ├── vendor
│       └── core
│           └── usbd.h
│
└── zephyr/blobs/ameba/amebadplus/lib
    └── lib_usbd.a

Menuconfig and Build

RTL8721DxRTL8730ERTL8721F

RTL8721Dx:

USB DTS and Binding:

• USB device DTS definition file: {sdk}/zephyr/dts/arm/realtek/amebadplus/amebadplus.dtsi

• USB device binding definition file: {sdk}/zephyr/dts/bindings/usb/realtek,ameba-usb.yaml

• Enable USB node in overlay or board level dts:

&usb {
   status = "okay";
};

USB menuconfig:

In the {sdk} directory, execute:

west build -t menuconfig or ./nuwa.py config

Enter hal_realtek in Modules, then choose the class(es) as needed:

[*] RealTek Ameba Zephyr USB stack
   [ ] USB Device Mode
      [ ]   CDC ACM device
      [ ]   HID device
      [ ]   MSC device
      [ ]   Composite device
      [ ]   VENDOR device
      [ ]   DFU device
   [ ] USB Host Mode
      [ ]   CDC ACM host
      [ ]   VENDOR host
      [ ]   UAC host
      [ ]   DFU host
      [ ]   Composite host
      [ ]   UVC host

Save and exit.

Build Commands:

In the {sdk} directory, execute:

./nuwa.py build applications/usb/xxx -b rtl872xda_evb -p

For details, see Zephyr SDK build and Flashing

USB Certification

Refer to the USB Certification chapter in FreeRTOS USB programming guide: USB Certification