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.

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 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 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

  • 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:

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}/component/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

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 designed to verify that the electrical characteristics of USB devices, hosts, or hubs comply with USB-IF (USB Implementers Forum) specifications, ensuring system stability and interoperability. The test scope covers key electrical performance metrics, including signal quality, power management, and timing parameters.

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 whether a product meets the USB CTS (Compliance Test Suite) standards, please use the dedicated test firmware and command set provided below.

Technical Support

If you encounter any technical issues or anomalies during testing, please contact the Technical Support Team for professional assistance.

Test Firmware Preparation

Follow these steps to obtain and deploy the test firmware:

  • Download Firmware: Obtain the latest test image files for your specific chip model from the list below.

  • Flash Firmware: Refer to the Flash Programming Guide to flash the downloaded firmware onto the target device, updating it to the dedicated test version.

Test Command Set

The test commands in this section are based on the Agilent 5485xA oscilloscope. If you are using a different model for electrical characteristic verification, refer to the table below for the corresponding commands.

Type

Command

Description

RESET

reboot

Reboot Test Environment

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

INIT

usbd init

Initialize USB Device

Must be executed after rebooting. Responsible for loading drivers and configuring the USB device environment, establishing the foundation for subsequent tests.

DEINIT

usbd deinit

Release USB Device Resources

Destroys allocated handles, memory, and interrupt resources, returning the device completely to an uninitialized state to prepare for the next reset or test cycle.