USB Device & Host
Relevant source files
The following files were used as context for generating this wiki page:
The USB subsystem provides support for both USB Device and USB Host roles, enabling the system to act as a peripheral or a controller. This stack is integrated into the OS services, providing standardized APIs for hardware-agnostic USB communication. The implementation covers device-side features like Mass Storage and CDC, as well as host-side core management and USB-C stack functionality.
Within the project architecture, USB services are classified under OS Services, sitting above platform-specific drivers. The stack facilitates communication between hardware-specific USB IPs and application-level services. For security and reliability, the USB implementation follows the project's Secure Coding principles, including least privilege and input validation for data received over the bus.
Sources: doc/security/security-overview.rst:190-210, doc/releases/release-notes-1.6.rst:11-15
USB Device Stack
The USB Device stack allows the system to function as a USB peripheral. It supports multiple device classes, including Mass Storage and Communication Device Class (CDC). The stack manages the device lifecycle, including initialization, configuration, and data transfer through endpoints.
Key Components and Architecture
The device stack is structured to separate the hardware controller driver from the upper-layer class implementations.
| Component | Description |
|---|---|
| USB Device Core | Manages the USB device state machine and standard requests. |
| Class Drivers | Implements specific USB profiles (e.g., Mass Storage, CDC). |
| Controller Driver | Hardware-specific implementation for USB peripheral IPs. |
The following diagram illustrates the interaction between the device application and the USB core during initialization:
USB Host Core
The USB Host core provides the infrastructure to control the USB bus and communicate with attached peripherals. It handles bus enumeration, device addressing, and pipe management for data transfers. The host core interfaces with the USB Host Controller Driver (HCD) to perform physical signaling and transaction management.
Host Operation Flow
When a device is attached, the host core initiates an enumeration sequence to identify and configure the peripheral.
Sources: subsys/usb/host/usbh_core.c
USB-C Stack
The USB-C stack implements support for Type-C connectors, including Power Delivery (PD) and Port Controller management. It manages the state of the CC (Configuration Channel) pins to determine orientation, attachment status, and power roles (Source/Sink).
USB-C State Machine
The stack maintains a complex state machine to handle the various phases of a Type-C connection.
| State | Description |
|---|---|
| Unattached | Port is waiting for a connection. |
| Attached | Physical connection detected via CC pins. |
| Powered | VBUS is active and power negotiation is complete. |
Sources: subsys/usb/usb_c/usbc_stack.c
Security and Quality Assurance
The USB subsystem is subject to the project's security guidelines to prevent vulnerabilities such as buffer overflows from malicious USB packets. Security measures include:
- Input Validation: All descriptors and data received from the bus must be validated against expected lengths and formats.
- Static Analysis: The USB stack is regularly scanned using static analysis tools to identify common coding mistakes.
- Thread Separation: USB processing can be partitioned into unprivileged execution environments to limit the impact of a compromised stack.
Sources: doc/security/security-overview.rst:95-120, doc/security/security-overview.rst:135-150
Conclusion
The USB Device & Host subsystem provides a comprehensive framework for managing USB communication in both peripheral and controller roles. By utilizing a modular architecture and adhering to strict security and quality standards, the subsystem ensures robust and secure integration with a wide variety of USB hardware and applications.