Skip to content

USB MIDI device mode (rebased #24) - #34

Open
macroexp wants to merge 5 commits into
mainfrom
usb-midi-device-mode
Open

macroexp wants to merge 5 commits into
mainfrom
usb-midi-device-mode

Conversation

@macroexp

@macroexp macroexp commented Nov 2, 2026 •

Copy link
Copy Markdown
Owner

Supersedes #24 by @waagbo, rebased onto main (0.18.0) with the fixes it needed there. Thanks to waagbo for the feature: their two commits are kept unchanged at the bottom of this branch.

What it does

usb_mode = midi_device in mt32-pi.cfg makes a Pi Zero (W), Zero 2 W, 3A+ or 4B appear as a class-compliant USB MIDI device called "mt32-pi" when it's plugged into a computer, so no MIDI interface is needed. The default stays host, and boards whose USB controller sits behind a hub (2B, 3B, 3B+), and now the Pi 5, log a warning and fall back to host mode. It uses Circle's CUSBMIDIGadget; CMT32Pi now creates either the host controller or the gadget in Initialize(), because they can't share the controller.

Changes on top of #24

  1. Pi 5 build: Circle builds lib/usb/gadget empty for RASPPI=5, so Add support for USB MIDI Device Mode #24 left pi5-64 with undefined references to CUSBMIDIGadget. The gadget class and its use are now under #if RASPPI <= 4; Pi 1–4 kernels compile the same code as Add support for USB MIDI Device Mode #24.
  2. Host tests: Add support for USB MIDI Device Mode #24 predates the host harness (Host test harness with ThreadSanitizer and ASan/UBSan #27, Clang thread-safety analysis for the synth and ring-buffer locks #28). The fake Circle gets usbcontroller.h, a CUSBHCIDevice that derives from it, a CUSBMIDIGadget that never comes up, usb.h and machineinfo.h; src/usbmidigadget.cpp joins the harness sources and CSystem uses the five-argument constructor. Without this host-tests-* and thread-safety fail to compile mt32pi.cpp.
  3. Circle backport: Add support for USB MIDI Device Mode #24 backported Circle #720 and #722 but skipped #721 between them ("Complete bulk transfer cancellation before buffer reuse"). The MIDI gadget's OUT endpoint cancels its transfer on deactivation and re-arms the same buffer, which #720 makes more common. Circle 51.1.1's gadget sources are identical to develop just before the series, so the patch is now upstream's diff for all three, unchanged.
  4. CHANGELOG entry under [Unreleased] (not 0.18.0); mt32-pi.cfg notes the Pi 5 fallback and that usb_mode does nothing with usb = off.

Timing

  • Host mode (default): same Circle driver and the same MIDI path; the only change is that CUSBHCIDevice is created on the heap in CMT32Pi::Initialize() instead of as a CKernel member, before the main loop starts.
  • Device mode: USB MIDI packets reach the synth exactly as from a USB MIDI adapter: the endpoint's transfer-complete interrupt calls the existing USBMIDIPacketHandler(), which enqueues into m_MIDIRxBuffer. #721's busy-waits (≤10 ms each, LOGPANIC on a hardware timeout) are only in CancelTransfer(), which runs when the host suspends or reconfigures the device, not while notes are flowing.

Testing

  • Host tests: plain, ThreadSanitizer and ASan/UBSan builds, 16/16 pass; Clang thread_safety target builds (only the two warnings already on main).
  • Kernels: CI builds all six boards and the package on ae43a5e (11/11 checks green). Locally with Arm GNU Toolchain 15.2.rel1, pi5-64 links again and its kernel holds the host-mode fallback warning but none of the gadget strings; make mrproper reverses the Circle patch cleanly.
  • Add support for USB MIDI Device Mode #24's author reports a Pi Zero 2 W enumerating at high speed on macOS with DOSBox-X playback.

Before merging

  • Hardware (Mike): Zero 2 W with usb_mode = midi_device and Cakewalk on Windows: enumeration, Laura Bow 2 including the AMONRA.SYX upload, PC reboot and cable replug (the #720 path). Then usb_mode = host with a USB MIDI adapter on the Zero 2 W and the Pi 5, since host-mode setup moved.
  • USB ID: this PR still uses pid.codes' shared test ID 1209:0001, which must not ship in a release. 1209:3200 is requested in Describe pim-32's need for a new pid pidcodes/pidcodes.github.com#1348; branch usb-pid-3200 (one commit on top of this one) switches to it, for its own PR once pid.codes merges. Don't change the PID after release: Windows caches drivers by VID/PID.

https://claude.ai/code/session_012SetuMHhTUS7PvQSJZLUsy


Generated by Claude Code

With usb_mode = gadget, a Pi Zero (W), Zero 2 W, 3A+ or 4B connected to a
computer appears there as a USB MIDI device called "mt32-pi", using
Circle's CUSBMIDIGadget. Other models log a warning and fall back to host
mode, as their USB controller sits behind the onboard hub.

- The USB controller is now created in CMT32Pi::Initialize() as either
  CUSBHCIDevice or CMT32PiUSBMIDIGadget, since both can't share it.
- The gadget subclass sets our USB IDs (pid.codes test IDs for now) and
  manufacturer/product strings.
- Link libusbgadget.a.
- Backport two Circle develop fixes (patches/circle-51.1.1-usb-midi-gadget.patch):
  reuse the MIDI interface after reconfiguration (otherwise a second
  enumeration fails an assertion) and invalidate DMA receive buffers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013W5uqwthuKxfKoH5S4ft1C
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013W5uqwthuKxfKoH5S4ft1C
Circle builds lib/usb/gadget empty for RASPPI=5, so src/usbmidigadget.o
left pi5-64 with undefined references to CUSBMIDIGadget. The gadget class
and its use in CMT32Pi::Initialize() are now under #if RASPPI <= 4; on the
Pi 5, usb_mode = midi_device logs the existing warning and uses host mode.
Pi 1-4 kernels compile the same code as before.

mt32-pi.cfg: say that the Pi 5 falls back to host mode and that usb_mode
has no effect with usb = off.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012SetuMHhTUS7PvQSJZLUsy
CMT32Pi now owns its USB controller (host or gadget) through
CUSBController, so the fake Circle gets usbcontroller.h, a CUSBHCIDevice
that derives from it with Circle's constructor, a CUSBMIDIGadget that never
comes up, usb.h's DESCRIPTOR_STRING and a CMachineInfo that reports a
Zero 2 W. src/usbmidigadget.cpp joins the harness sources, and CSystem
uses the five-argument CMT32Pi constructor.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012SetuMHhTUS7PvQSJZLUsy
The patch backported Circle #720 and #722 but skipped #721 between them
("Complete bulk transfer cancellation before buffer reuse"). The MIDI
gadget's OUT endpoint cancels its transfer on deactivation and re-arms the
same buffer, the path #720 makes more common. Circle 51.1.1's gadget
sources match develop just before the series, so the patch is now
upstream's diff for all three commits, unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012SetuMHhTUS7PvQSJZLUsy
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants