USB Introduction

Overview

Supported ICs[ RTL8721Dx ][ RTL8730E ][ RTL8721F ][RTL8735C]

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.

Features

  • Compatibility: Fully compliant with USB 2.0 High-speed (480 Mbps) and Full-speed (12 Mbps) specifications.

  • Supported USB host solutions:

    • CDC ACM: Enables bidirectional transparent data transmission for serial communication, data acquisition, custom protocols and etc.

    • CDC ECM: Interfaces with Ethernet modules to act as a Network Interface Card (NIC) or a bridge for network routing.

    • MSC: Supports Mass Storage Class devices (e.g., USB flash drives, card readers) for smart speakers, data logging, OTA updates and etc.

    • UAC: Supports USB Audio Class devices (e.g., Type-C headsets) for audio output and volume control.

    • UVC: Interoperates with USB cameras, supporting MJPEG, H.264, and YUV formats for image capture and video streaming in smart locks, surveillance systems and etc.

    • Composite hosts:

      • CDC ACM + CDC ECM: Supports 4G cellular modules for IoT gateways, mobile hotspots and etc.

      • HID + UAC: Integrates Human Interface Device and Audio control for unified inline remote, recording, and playback management.

    • Vendor: Allows custom driver implementation beyond standard USB classes to meet highly customized application requirements.

  • Supported USB device solutions:

    • CDC ACM: Functions as a virtual COM port for bidirectional transparent data transmission.

    • HID: Emulates standard peripherals like keyboards and mice for rich human-machine interaction.

    • MSC: Maps SD cards or Flash memory as external mass storage media.

    • UAC: Acts as a USB audio device for audio playback.

    • Composite devices:

      • CDC ACM + HID: Simultaneous data transmission and interaction control.

      • CDC ACM + MSC: Simultaneous data transmission and mass storage.

      • CDC ACM + UAC: Simultaneous data transmission and audio playback.

      • HID + UAC: Simultaneous interaction control, audio recording, and audio playback..

    • Vendor: Supports customized development for non-standard device classes.

  • Advanced features:

    • Dual-Role switching: Supports dynamic switching between USB Host and Device roles.

    • Highly customizable device mode: Full customization of USB descriptors, including VID/PID, string descriptors, and endpoint mapping.

    • Flexible host enumeration: Features customizable device matching strategies (e.g., matching by VID/PID or specific Class/Protocol), automatic descriptor parsing, and adaptive speed negotiation.

    • Configurable core parameters: Allows adjustment of speed modes, Data FIFO (DFIFO) depth (dedicated FIFO mode only), and scheduling priorities for the USB ISR and core threads.

Note

The RTL8721Dx supports Full-speed Device mode only.

Hardware Configurations

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 Architecture

The architecture of USB software stack:

RTL8721Dx:
../../_images/usb_freertos_device_only_arch.svg

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 host/device core drivers: Integrates USB IP-specific hardware driver, host/device controller driver, enumeration state machine and transfer scheduling algorithms, exposing unified core API for designers to develop classes and applications.

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

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

USB HAL driver

USB HAL driver implements ​​SoC-specific USB power management, interrupt handling and phy calibration interfaces, defines system-level preprocessor constants, exposes unified HAL API to upper-layer drivers.

../../_images/usb_hal_api.svg

Note

  • USB HAL driver is built into USB host/device/DRD core library as default and customization is not allowed.

  • USB PHY calibration data is determined by Realtek during manufacturing and developer-side re-calibration is not allowed, for suspected calibration-related compatibility issues (e.g., USB enumeration failures, intermittent disconnection/reconnection issues), contact Realtek FAE for help.

USB Device Core Driver

../../_images/usb_device_api.svg

USB Host Core Driver

../../_images/usb_host_api.svg

File Organization

USB Path Aliases

For simplicity, the following path aliases are used in the subsequent descriptions.

Alias

Path

SDK_USB_HAL

{SDK}/component/soc/amebaxxx/fwlib/include

SDK_USB

{SDK}/component/usb

SDK_USB_DEV

{SDK}/component/usb/device

SDK_USB_HOST

{SDK}/component/usb/host

SDK_USB_EXAMPLE

{SDK}/example/usb

SDK_USB_LIB

{SDK}/component/soc/amebaxxx/project/project_xxx/lib/application

USB HAL Driver

Path

Description

{SDK_USB_HAL}/ameba_usb.h

USB HAL API definition header file

USB Core Driver

RTL8721Dx:

Path

Description

{SDK_USB}/common/

USB common core driver API definition header file

{SDK_USB_DEV}/core/usbd.h

USB device core driver API definition header file

{SDK_USB_LIB}/lib_usbd.a

USB device core driver static library file

USB Class Driver

Path

Description

{SDK_USB_DEV}/cdc_acm/

CDC ACM device class driver

{SDK_USB_DEV}/composite/

Composite device class driver

{SDK_USB_DEV}/hid/

HID device class driver

{SDK_USB_DEV}/inic/

INIC device class driver (non-standard)

{SDK_USB_DEV}/msc/

MSC device class driver

{SDK_USB_DEV}/uac/

UAC device class driver

{SDK_USB_DEV}/vendor/

Vendor-specific device class driver

{SDK_USB_HOST}/cdc_acm/

CDC ACM host class driver

{SDK_USB_HOST}/cdc_ecm/

CDC ECM host class driver

{SDK_USB_HOST}/msc/

MSC host class driver

{SDK_USB_HOST}/uvc/

UVC host class driver

{SDK_USB_HOST}/vendor/

Vendor-specific host class driver

USB Application

Path

Description

{SDK_USB_EXAMPLE}/usbd_cdc_acm/

Transparent communication device example based on CDC ACM device class

{SDK_USB_EXAMPLE}/usbd_cdc_acm_hid/

Composite device example based on CDC ACM and HID device classes

{SDK_USB_EXAMPLE}/usbd_cdc_acm_uac/

Composite device example based on CDC ACM and UAC device classes

{SDK_USB_EXAMPLE}/usbd_uac_hid/

Composite device example based on HID and UAC device classes

{SDK_USB_EXAMPLE}/usbd_hid/

HID device example

{SDK_USB_EXAMPLE}/usbd_inic/

INIC device example

{SDK_USB_EXAMPLE}/usbd_msc/

Mass storage device example based on MSC device classes

{SDK_USB_EXAMPLE}/usbd_uac/

Audio device example based on UAC device classes

{SDK_USB_EXAMPLE}/usbd_vendor/

Vendor-specific device example

{SDK_USB_EXAMPLE}/usbh_cdc_acm/

Transparent communication host example based on CDC ACM host class

{SDK_USB_EXAMPLE}/usbh_cdc_ecm/

Ethernet communication host example based on CDC ECM host class

{SDK_USB_EXAMPLE}/usbh_msc/

Mass storage host example based on MSC host classe

{SDK_USB_EXAMPLE}/usbh_uvc/

Video host example based on UVC host classe

{SDK_USB_EXAMPLE}/usbh_vendor/

Vendor-specific host example

{SDK_USB_EXAMPLE}/usbh_wifi_bridge/

Ethernet communication bridge example based on CDC ECM host class

{SDK_USB_EXAMPLE}/usb_drd/

DRD example based on MSC host class and MSC device classe

Host Solutions, refer to Host Solutions

Device Solutions, refer to Device Solutions

USB Certification

USB certification generally refers to USB-IF certification, i.e. USB-IF compliance testing, which validates devices against USB-IF electrical, protocol and functional requirements to ensure interoperability, security and reliability. Certified devices are authorized to use USB logos.

While USB-IF certification is not mandatory, it is required when:

  • Products intend to use USB logos

  • Marketing materials claim USB specification compliance or certification

For certification procedures and requirements, refer to https://www.usb.org documentation or contact USB-IF authorized test labs.

Additional Compliance Requirements for USB Devices:

  • FCC/CE: Mandatory for USB devices sold in EU/US markets

  • ISO 26262: Required for automotive USB devices (functional safety)

  • Windows Logo Program: Necessary for “Certified for Windows” branding

  • MFi: Mandatory for Apple-specific USB accessories

Compliance Test Guide

Overview

The USB Electrical Compliance Test is the USB-IF-defined certification standard (Compliance Test Suite, CTS) for verifying that the electrical characteristics of USB devices, hosts, or hubs meet the specification requirements. The Eye Diagram Test is one of the core test items within this suite, designed to evaluate physical layer signal quality, including signal jitter, eye opening, rise/fall times, voltage levels, and SE0 characteristics.

Important

This document covers only the eye diagram test flow, including test firmware compilation and operation commands. For the complete CTS certification (including protocol tests, electrical tests, and all other items), refer to the USB-IF official specifications and test plans.

Official Specifications Reference: https://www.usb.org/usb2

Scope of Application

This test solution applies to the entire Ameba series platform, supporting the following operating environments:

  • Linux

  • RTOS

  • Zephyr

To verify that a product meets the USB eye diagram test requirements, use the test firmware and command set provided below.

Build Test Firmware

The USB eye diagram test firmware can be compiled directly from the SDK. Select the appropriate build steps based on the test mode:

Device Mode:

The eye diagram test firmware can be compiled using code from the project or from SDK examples. The following uses CDC ACM as an example:

  1. Modify the source code to disable hotplug:

    Open example/usb/usbd_cdc_acm/example_usbd_cdc_acm.c and confirm CONFIG_USBD_CDC_ACM_HOTPLUG is set to 0 (hotplug must be disabled during the eye diagram test to avoid interference):

    #define CONFIG_USBD_CDC_ACM_HOTPLUG               0

  2. Build the CDC ACM example:

    ameba.py build -a usbd_cdc_acm -p

    For build environment setup, refer to SDK Guide .

  3. After compilation, flash the firmware to the device. Refer to the Flash Programming Guide for flashing instructions.

  4. Prepare a CDC ACM-compatible host (e.g., Windows 11) as the test peer device.

  5. Reboot the board to start the eye diagram test.

Test Command Set

After flashing the test firmware, send the following test commands to the development board via the serial terminal. Select the appropriate command table based on the test mode (Device / Host):

Device:

Type

Command

Description

RESET

AT+RST

Reboot the test board

A mandatory step before executing any test case. It clears residual states to ensure the system starts from a deterministic initial environment.

Technical Support

For technical issues during testing, contact the Technical Support Team for professional assistance.