max3421: prevent USB host hang at startup#3748
Open
mikeysklar wants to merge 2 commits into
Open
Conversation
On some boards the MAX3421E doesn't report its oscillator ready after a soft reset (CHIPRES), so hcd_init() waits on USBIRQ_OSCOK forever and the host hangs at startup before any USB device can be used. Bound the wait so it proceeds after a timeout; it is a no-op where OSCOK arrives normally. Needed on the Adafruit Feather ESP32 V2 (classic ESP32) + USB Host FeatherWing, which otherwise hangs on essentially every cold boot. Relates to adafruit/circuitpython#10053.
hathach
force-pushed
the
fix-max3421-oscok-hang
branch
from
3daa572 to
2957c10
Compare
Owner
|
@claude review |
Contributor
|
Claude finished @hathach's task in 3m 4s —— View job Claude finished @hathach's taskTasks
ReviewChange is small and sound. Correctness — looks right
Minor, non-blocking suggestions
No bugs found that would block merging. |
hathach
approved these changes
Jul 1, 2026
hathach
left a comment
hathach
left a comment
Owner
There was a problem hiding this comment.
thank you, I change the timeout to time based that machtes the datasheet 3ms (+1 in case we are in the last us). tusb_time_millis_api() must be implement, which is actually requirement for host stack on non-rtos.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR prevents a startup hang in the MAX3421E host controller init path by bounding the wait for the oscillator-ready (OSCOK) IRQ, allowing host initialization to continue even when OSCOK never latches after a soft reset.
Changes:
- Replace the unbounded OSCOK polling loop in
hcd_init()with a millisecond-based timeout (4 ms). - Add in-code rationale and datasheet timing reference to explain why proceeding after timeout is acceptable.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+507
to
+510
| // Wait for the oscillator to stabilize (OSCOK), bounded by a timeout. On boards where the | ||
| // MAX3421E is only soft-reset via CHIPRES (no hardware reset on the nRST pin), the OSCOK IRQ | ||
| // may never latch and would otherwise hang the host forever. The oscillator is generally | ||
| // running regardless, so proceed once the timeout elapses. |
|
Size Difference ReportBecause TinyUSB code size varies by port and configuration, the metrics below represent the averaged totals across all example builds. Note: If there is no change, only one value is shown. Changes >1% in sizeNo entries. Changes <1% in sizeNo entries. No changes
|
Hardware-in-the-loop (HIL) Test Reporthfp.json✅ 52 passed · ❌ 0 failed · ⚪ 0 skipped · blank not run
tinyusb.json✅ 339 passed · ❌ 0 failed · ⚪ 11 skipped · blank not run
|
hathach
force-pushed
the
fix-max3421-oscok-hang
branch
from
2957c10 to
4202e1e
Compare
hathach
reviewed
Jul 1, 2026
| // hangs if the edge is still missed on some board - the clock is running regardless. | ||
| const uint32_t oscok_start_ms = tusb_time_millis_api(); | ||
| while (!(reg_read(rhport, USBIRQ_ADDR, false) & USBIRQ_OSCOK_IRQ) && | ||
| (tusb_time_millis_api() - oscok_start_ms < TIME_TO_EXIT_SUSPEND_MS)) {} |
Owner
There was a problem hiding this comment.
@mikeysklar after checking the datasheet/programming guide, I think the issue is probably we are writing the CHIPRES too fast within ~us that reset signal isn't long enough for the osc is fully stopped to assert the bit. Would you mind trying to comment out the (tusb_time_millis_api() - oscok_start_ms < TIME_TO_EXIT_SUSPEND_MS) the delay in this loop to see if that the above delay work. We will add this anyway, since it prevent actual host hang, any other race condition
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The MAX3421E can fail to report its oscillator ready after a soft reset, so
hcd_init()waits onUSBIRQ_OSCOKforever and the host hangs at startup. This bounds the wait so it proceeds instead (no-op when OSCOK arrives normally).Needed on the Adafruit Feather ESP32 V2 + USB Host FeatherWing. Relates to adafruit/circuitpython#10053; complements adafruit/circuitpython#11081.