itsybitsy_m4 - USB stack depends on code optimization

[FraFrieFa]

Description:
I've encountered an issue with the usb_serial example in the itsybitsy_m4 crate. When building the example in isolation (i.e., outside of the full atsamd workspace), the firmware compiles successfully, but the device fails to enumerate as a CDC ACM device unless the following build options are set:

• lto = true
• opt-level = "s"

Without these settings, the USB functionality does not work as expected.

---

Steps to Reproduce:

1. Clone the atsamd repository containing the itsybitsy_m4 crate.
2. Copy the itsybitsy_m4 folder to a standalone location (thus losing the workspace context and the top-level Cargo.toml).
3. Build the usb_serial example in release without modifying any build profile settings.
4. Flash the resulting firmware onto an ItsyBitsy M4 board.
5. Observe that the board does not register as a CDC ACM device.

---

Expected Behavior:
The USB serial example should enumerate correctly as a CDC ACM device regardless of the build configuration, or at least the need for these specific build settings should be clearly documented to make USB device implementations easier for users of the crate.

---

Observed Behavior:
The device only enumerates as a CDC ACM device when building with:

[profile.release]
lto = true
opt-level = "s"

---

Comments:

• Might be a deeper problem in the rust USB stack
• Optimization level 0 or missing lto = true lead to unstable USB enumeration after multiple attempts

---

Environment

NixOS channel nixos:24.11, rustup

$ rustc --version
rustc 1.85.0 (4d91de4e4 2025-02-17)

$ cargo --version
cargo 1.85.0 (d73d2caf9 2024-12-31)

---

[ianrrees]

Hi @FraFrieFa , thanks for the excellent report! Yes, this is a known issue with our USB implementation - basically it needs to be built with --release profile. I'm hopeful that we can get to a point where the relevant code is usually optimised enough to work properly, regardless of the application's build profile.

In the meantime, do you have any suggestions on where we could more clearly document the requirement to use the release profile for USB firmwares?

[FraFrieFa]

Hi @ianrrees, ah ok that makes sense. Bit weird still that opt-level 3 does not work yet opt-level "s" does—but I might have to look deeper into the generated binary to figure out why. (With opt 3 the device is not even recognized as a USB device and for that it just has to setup all the pins and clocks and write to the USB attach register and not do something time-critical I think) Building the --release profile works, but only with the global Cargo.toml in the repository root that overrides the default release opt-level from 3 to "s".

I’d suggest adding a comment about the need for lto = true and opt-level = "s" in the build instructions of the README somewhere (maybe even in the root README if this affects all boards). Perhaps even better in the crate description/documentation so that users that include the crate know how to properly build their project.

Thanks again for the quick response and for looking into this!

[ianrrees]

The situation is somewhat complicated and I suspect you're seeing a similar symptom with a couple different causes. The failures with opt-level 3 could be the issue that this PR addresses (or perhaps the other Cargo.toml setting was being used?), where I think the debug build ones might just be that the additional bounds checks etc make the code too slow to meet the USB timings.

[FraFrieFa]

Update:
I've tested this on another PC with the same Rust toolchain, and the issue does not occur there. On that machine, the USB serial example enumerates correctly without lto = true or opt-level = "s", and it also works in debug mode (though it takes a second to enumerate).

I'm not entirely sure what the root cause is, but it does not seem to be an inherent issue with the project itself.

[ianrrees]

Yeah, that's what I meant about it being complicated. There are a couple issues, and a major one at the moment is that the usb-device crate isn't designed in a way that can detect a situation where a SETUP transaction has overwritten another transaction. Some hosts are much more prone to triggering this than others, and slower running code (non-release builds) makes the issue more likely too.

I'm hopeful that, once that usb-device PR is merged, we'll find that the USB examples run reasonably well even with the device being built in debug mode. Then, we can look at optimisation settings for the USB code, because I think most of our use cases don't benefit from the usb-device code or the USB implementation in the HAL being built in debug mode.

[kaidokert]

I've long been having similar issue on SAMD21 ( Adafruit Feather M0). With release builds it enumerates okay on Macbook host and serial comms work, but not on Windows for example.

FWIW @ianrrees i tried out your pending PR and at least a quick naive test doesn't fix it. Or maybe there's more that needs to be changed on the atsamd crate ?

[ianrrees]

I'll have to get back to you later on this, but from a quick skim, that looks reasonable. A couple weeks ago, I put my hand up to maintain usb-device, so maybe can get that change upstreamed in not too long...

While I'm quite confident that the issue with SETUP overwriting OUT ZLPs is the root cause of a lot of ATSAM enumeration problems, there easily could be other things going on as well.

Operating systems also differ in how they attach drivers to USB interfaces/devices, and I can't remember details but Windows used to need an INF (?) file for some USB CDC interfaces - maybe it depended on whether the device descriptor indicated it was a CDC or if it was compound?

[kaidokert]

The windows machine otherwise works with the exact same Feather boards fine - when i flash it with C code or any of the UF2 or Bossac bootloaders from Adafruit. Atmels own Atmel Studio samples work as well, so does Arduino stuff when talking to the board. Windows `Usb Device viewer" shows correct enumeration and i can Wireshark log the exact sequence it goes through as well.

I'll do some more testing here on top of those patches. I'll check on scope if we are actually getting a 48mhz clock, and do register dumps to see what else ends up being different from C code.

[ianrrees]

If I had to guess, I'd say the issue with Windows CDC not working is likely to do with the contents of the descriptors (or something higher up in the stack - eg the INF I mentioned) - the device showing up in Usb Device Viewer indicates that the lower layers are working. FWIW, I've found that when diagnosing this sort of OS-dependent issue, it's often helpful to compare against another similar device (which would include the same hardware running different firmware) on the same OS, eg compare your CDC firmware against a different CDC device. Wireshark is pretty good, but bear in mind that it's capturing the URBs (communications in the USB host stack) so lower layer issues might not clearly show up in there. I'd start with a diff between the full device descriptors, and perhaps modifying your firmware to mimic a working one.

Clock accuracy has been an issue in atsamd-rs project before - basically you want the device's clock source to either be an external oscillator, or the DFLL with USB clock recovery mode enabled. Accuracy is pretty important. However, if the same firmware is working with a different host OS then device clocks are unlikely to be the cause of the problem.

If you don't mind, let's move the new discussion in to an open issue, as I think this is straying a bit from USB needing optimisation turned on.