USBX on ThreadX · STM32U575

Follow USB traffic from the STM32U575 controller through USBX CDC ACM and the ThreadX application. This domain brings 37 sampled inputs and five derived channels into live cards, tables and traces, so you can tell a configured idle bridge from work that has stopped progressing.

Before you start

Download the USBX on ThreadX domain. Install this same file in either product. It targets STM32U575 and the STM32Cube USBX CDC ACM on ThreadX example, including its application symbols. It is not a universal domain for every USBX firmware or STM32 device.

Have these items ready:

• A NUCLEO-U575ZI-Q running the matching USBX CDC ACM to USART1 bridge firmware, with ThreadX. The example is based on STM32CubeU5's Ux_Device_CDC_ACM application.
• Its Debug ELF with DWARF information, from the exact build on the board. Structured fields need member types and offsets, not just symbol names.
• The STM32U575 SVD matching the target. It supplies the OTG_FS registers and their RCC clock-enable precondition. Firmware-object-only sampling does not require these register reads.
• Two USB data connections: CN1 / ST-LINK for the probe and UART bridge, and CN15 / target USB-C for the firmware's CDC port. A probe connection alone does not connect the target's USB device to the host.

The example project keeps the descriptor in domains/stm32u575-usbx-threadx.vadomain. A local Debug build produces build/<OS>/threadx-debug/Nucleo_U575_USBX_ThreadX.elf. Select that actual output; another build directory may contain a different ELF. A downloaded descriptor contains no firmware or ELF.

Start in BKPT Debug

1. Open the firmware project in VS Code and open the BKPT Debug layout. Select your probe and the matching Debug ELF.
2. Open Peripheral Registers from Views, then Open SVD and select the STM32U575 SVD.
3. Open Trace Domains. Choose Install custom trace domain…, select the downloaded file, and enable STM32U575 USBX CDC ACM on ThreadX for this workspace.
4. Start or attach the debug session. If the target is halted, choose Continue. USB initialization and host enumeration require running firmware.
5. Open Traces alongside Trace Domains. Once initialization completes with the target USB connected, expect 37 observed inputs, 0 unavailable, and 42 raw plus derived trace channels.

USB traffic is optional for this first check. You can see a configured device and valid controller/firmware values before opening either serial port. Flat traces are normal when their values are not changing.

Choose what to poll in BKPT Debug

Expand Settings inside this domain and set the requested polling rate from 1 to 1,000 Hz per input. The USBX descriptor supplies a 20 Hz default, which you can adjust for your capture. Observed shows the rate achieved with your probe and selected inputs; selecting fewer inputs can allow faster sampling.

Use All inputs, Registers only, Firmware objects only, or None, then adjust individual checkboxes. Firmware objects only selects 32 RAM inputs without peripheral reads. Registers only selects five controller inputs plus the required RCC clock guard. Required guards remain enabled while a selected input needs them.

Before applying a selection, Settings lists the derived values and checks it will disable, with their required input names. After Apply settings, those items say Disabled by settings. For example, disabling usb.gahbcfg disables Interrupt delivery and its interrupt-delivery check. Disabling only an optional evidence input leaves a check available with reduced evidence, clearly identified beside it.

Applying changes saves this workspace's choices, clears this domain's findings, and starts a fresh observation window. Re-enabled checks need fresh samples for their required duration; old samples cannot complete the new window. Existing trace history remains visible, while disabled inputs stop adding samples. Reset defaults restores the descriptor's rate and all inputs.

USB controller cards

USBX device and CDC class cards

These fields come from live USBX objects. Before the class instance exists, the corresponding inputs can be unavailable. Once the pointer and members resolve, they join the observation stream.

CDC endpoint tables

CDC endpoint 1 follows the first endpoint in the CDC interface's linked list; CDC endpoint 2 follows the next one. The numbers identify the descriptor's traversal order. Read Endpoint / direction to identify the actual USB endpoint.

In this bridge, the observed endpoints are 0x01 OUT, from host to device, and 0x81 IN, from device to host. USB direction is always relative to the host.

An OUT endpoint Pending on a 64-byte read while no host is sending data is a normal idle condition. An IN endpoint with no pending request can also be idle. Each field is sampled separately, so a request can change between reads. These tables do not count every USB transfer or measure throughput.

Application and ThreadX

The two indices wrap in a 2048-byte ring; they are not lifetime byte counts. Under traffic they advance and wrap. At idle they can be equal and stop moving. Compare their progress with endpoint demand before diagnosing a stalled bridge. A waiting thread alone is not an error, and separate index samples do not guarantee an exact instantaneous queue length.

Make activity visible

This firmware bridges two serial ports. Data sent to the ST-LINK UART appears at the target's USB CDC port; data sent to the CDC port appears at the UART. It does not echo back to the same port.

Open both ports in serial terminals at 115200, 8-N-1, no flow control, and send data in both directions. Close those terminals before using the project's optional Python traffic helper, because the helper opens both ports itself.

For the example project that includes tools/domain_traffic.py, install its pyserial dependency and run the following from the project root. Replace the two port placeholders with your machine's UART and target CDC ports; Windows COM numbers and macOS/Linux device paths differ.

python -m pip install pyserial
python tools/domain_traffic.py --uart YOUR_UART_PORT --cdc YOUR_CDC_PORT --duration 60 --output usb-traffic.json --stop-file usb-traffic.stop

The helper sends test payloads in both directions and checks the received bytes. It stops after the requested duration, allowing an in-flight transfer to finish or time out. Ctrl+C stops it early. If a previous usb-traffic.stop file exists, remove that file before starting another run. Use the helper only when you own both serial ports and the board's test session.

Watch the producer/consumer indices advance during UART-to-USB traffic, the endpoint request fields change, and DTR/RTS reflect the host's port settings. Some transfers complete between polls and will not be visible. When the helper exits and releases the ports, the indices should settle again; the domain can stay observed and Configured.

All registers and trace channels

The input list contains five controller registers, 30 structured firmware fields and two application variables. Five decoded fields bring the available channel total to 42. Select Graph for the histories you want displayed; other values remain in the domain view. The RCC clock guard is an additional prerequisite read, not an additional displayed trace. Use the domain's Settings in BKPT Debug to choose the polling rate and active inputs.

Raw controller registers

All five come from OTG_FS in the STM32U575 SVD. They are declared read-safe configuration/status inputs; reading them does not acknowledge an interrupt.

The five controller inputs require RCC.RCC_AHB2ENR1 OTGEN, mask 0x4000. When this clock is disabled, those register inputs are unavailable; firmware-object sampling can remain available. It does not represent unavailable values as zero.

USBX and ThreadX inputs

Member offsets come from the matching ELF's debug information. Pointer slots are reread, so null, invalid or changing object paths can produce gaps rather than stale values. This validation cannot detect every lifetime race, including reuse of the same memory address.

The current descriptor also observes usbx.last_error, usbx.error_count, five app.control_queue.* fields and six usbx.memory.* fields. Their cards show retained error reports, USB start/stop queue occupancy and allocator free/total values. These are distinct from CDC payload buffering. The engineering reference documents their exact paths, units, pressure thresholds and limitations.

Application inputs and derived traces

The two application values are raw polled inputs. The five usb.* values in the last five rows are Derived channels. Enumerated speed is available in Traces even though it is not one of the controller cards.

Findings and their limits

The current descriptor also checks additional USBX error reports, recognized endpoint error codes, control-queue free slots and allocator free space. See the complete finding reference. The original controller checks used in this walkthrough are:

In BKPT Debug, expand a finding for its explanation and evidence. Show evidence in Traces brings the supporting signals into view. Acquisition problems belong in Health and input availability; subsystem findings describe conditions in the observed USB state.

If your example firmware includes the optional B1 button fault demo, a short press after enumeration deliberately disables interrupt delivery for three seconds of running target time, then restores it. The interrupt-enable trace falls to zero and the finding appears after the sustained interval. Halting the CPU pauses the firmware's recovery timer. This demo is a property of that firmware build, not something installing a domain adds to arbitrary firmware.

Use the same domain in ViewAlyzer RS

1. End the BKPT Debug session to release the probe. Open ViewAlyzer RS and configure the same target with the matching ELF and SVD. Turn Software Trace off for domain-only capture. The app polls domain inputs without a recorder control block. Enable Software Trace only when also collecting compatible recorder data; RAM snapshots require recorder firmware.
2. In the sidebar's Trace Domains section, choose Load Domain File and select the same .vadomain. Enable it before starting a capture.
3. Start capture with the target running, and open the domain's sidebar gear to inspect its live cards and tables. Collapse sections you are not inspecting, and enable Graph for the values you want in Trace. The pencil opens the JSON editor.
4. Stop capture to review the derived series, completed findings and their evidence. A finding describes its interval in the recording; it need not indicate a fault is still active now.

The same domain supplies the channel names, derived fields and rules in both products. Their views and timing of report evaluation differ. Installing the domain into the desktop app does not install it into BKPT Debug, and opening a recording does not read new state from the board.

When the view looks empty or unavailable

For format details, see the Trace Domain reference. For the broader debug workflow, see BKPT Debug getting started.