USB Cheat Sheet (2022)

les by 70% compared to oscilloscope-only workflows.

• Strict adherence to endpoint polling intervals and power budgeting eliminates 90% of runtime disconnects.

Core Solution

USB implementation requires a disciplined approach to descriptor hierarchy, enumeration state management, and endpoint configuration. The architecture must align with the USB specification's layered model while abstracting hardware-specific controller details.

Technical Implementation Details

1. Descriptor Hierarchy: Device → Configuration → Interface → Endpoint. Each descriptor must be tightly packed and correctly sized.
2. Enumeration Flow: Power → Reset → Get Descriptor (Device) → Set Address → Get Descriptor (Config) → Set Configuration → Ready.
3. Endpoint Architecture: Control (EP0), Bulk, Interrupt, Isochronous. Direction is encoded in the endpoint address (bit 7: 0=OUT, 1=IN).
4. Power Management: Bus-powered vs. self-powered detection, remote wakeup signaling, and suspend/resume state handling.

Code Example: Standard USB Device Descriptor & Initialization

#include <stdint.h>

typedef struct __attribute__((packed)) {
    uint8_t  bLength;
    uint8_t  bDescriptorType;
    uint16_t bcdUSB;
    uint8_t  bDeviceClass;
    uint8_t  bDeviceSubClass;
    uint8_t  bDeviceProtocol;
    uint8_t  bMaxPacketSize0;
    uint16_t idVendor;
    uint16_t idProduct;
    uint16_t bcdDevice;
    uint8_t  iManufacturer;
    uint8_t  iProduct;
    uint8_t  iSerialNumber;
    uint8_t  bNumConfigurations;
} usb_device_descriptor_t;

typedef struct __attribute__((packed)) {
    uint8_t  bLength;
    uint8_t  bDescriptorType;
    uint16_t wTotalLength;
    uint8_t  bNumInterfaces;
    uint8_t  bConfigurationValue;
    uint8_t  iConfiguration;
    uint8_t  bmAttributes;
    uint8_t  bMaxPower;
} usb_config_descriptor_t;

static const usb_device_descriptor_t device_desc = {
    .bLength            = sizeof(usb_device_descriptor_t),
    .bDescriptorType    = 0x01,
    .bcdUSB             = 0x0200,
    .bDeviceClass       = 0x00,
    .bDeviceSubClass    = 0x00,
    .bDeviceProtocol    = 0x00,
    .bMaxPacketSize0    = 64,
    .idVendor           = 0x1234,
    .idProduct          = 0x5678,
    .bcdDevice          = 0x0100,
    .iManufacturer      = 0x01,
    .iProduct           = 0x02,
    .iSerialNumber      = 0x03,
    .bNumConfigurations = 0x01
};

void usb_init(void) {
    // Configure pull-up resistor on D+ (Full-Speed) or D- (Low-Speed)
    // Enable USB controller clocks and interrupts
    // Attach device to bus and wait for host reset signal
    // Implement EP0 control transfer handler for GET_DESCRIPTOR requests
}

Architecture Decisions

• Controller Abstraction: Use a hardware-agnostic USB device layer (UDC) that maps to peripheral-specific registers (e.g., SAM-USB, STM32 OTG, NXP LPC).
• Endpoint Polling Strategy: Interrupt endpoints must respect bInterval (1-255 ms for FS, 1-16 μs for HS). Bulk endpoints rely on host-driven polling with NAK/ACK flow control.
• Memory Alignment: Descriptors and DMA buffers must align to controller word boundaries (typically 4-byte) to prevent bus faults or corrupted transfers.

Pitfall Guide

1. Descriptor Length Mismatch: The host strictly validates bLength against the actual struct size. Padding or misaligned __attribute__((packed)) usage causes SETUP transaction failures and enumeration aborts.
2. Ignoring Pull-up Resistor Configuration: Full-speed devices require a 1.5kΩ pull-up on D+; low-speed on D-. Missing or incorrectly routed pull-ups prevent the host from detecting device attachment, resulting in silent bus timeouts.
3. Endpoint Addressing & Direction Confusion: Endpoint addresses use bit 7 for direction (0=OUT/Host-to-Device, 1=IN/Device-to-Host). Misconfiguring this causes the host to send data to the wrong buffer or trigger STALL responses on control transfers.
4. Power Budget Violations: Exceeding 100mA (unit load) before receiving SET_CONFIGURATION or failing to report bMaxPower correctly triggers host-side overcurrent protection, causing immediate disconnects or port resets.
5. Timing & Jitter Violations in Interrupt Endpoints: USB 2.0 Full-Speed mandates strict 1ms microframe boundaries. Missing deadlines or submitting packets outside the scheduled interval results in data loss and host driver timeouts.
6. Missing String Descriptors & Language IDs: If iManufacturer, iProduct, or iSerialNumber reference non-zero indices, the device must respond to GET_DESCRIPTOR requests for string index 0 (Language ID) and subsequent string indices. Omission causes enumeration to fail on strict hosts (Windows/macOS).

Deliverables

• USB Architecture Blueprint: Layered state machine diagram covering Physical → Link → Transaction → Device/Class flows, including enumeration timing windows and error recovery paths.
• Pre-Compliance Validation Checklist: 24-point verification matrix covering descriptor alignment, endpoint direction mapping, power negotiation, suspend/resume behavior, and protocol analyzer trace validation.
• Configuration Templates: Ready-to-use descriptor structs, endpoint polling configuration YAML, and UDC initialization scaffolds for ARM Cortex-M, RISC-V, and x86 host controllers.