USB Introduction

Overview

Supported ICs[ RTL8721Dx ][ 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

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

  • 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

  • UAC: As a USB audio device, it supports audio playback function

  • 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

  • CDC ACM+UAC composite device: supports both transparent communication and audio playback simultaneously

  • HID+UAC composite device: supports both interactive control and audio playback simultaneously

  • 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

Hardware Features

RTL8721DxRTL8721F

• 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

RTL8721DxRTL8721F

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

Menuconfig and Build

RTL8721DxRTL8721F

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
   Select USB Mode (Device)  --->
   [ ]  CDC ACM device
   [ ]  HID device
   [ ]  MSC device
   [ ]  Composite device
   [ ]  Vendor device

Save and exit.

Build Commands:

In the {sdk} directory, execute:

./nuwa.py build -a applications/usb/xxx -d 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