Skip to content

fix: disable wakeup_on_write by default to prevent HID lockup on host reboot#754

Open
7tg wants to merge 1 commit intosipeed:mainfrom
7tg:fix/usb-hid-wakeup-disconnect
Open

fix: disable wakeup_on_write by default to prevent HID lockup on host reboot#754
7tg wants to merge 1 commit intosipeed:mainfrom
7tg:fix/usb-hid-wakeup-disconnect

Conversation

@7tg
Copy link

@7tg 7tg commented Feb 13, 2026

Summary

  • Disable wakeup_on_write by default in both S03usbdev (regular mode) and S03usbhid (HID-only mode)
  • Invert the opt-out flag (/boot/usb.notwakeup) to an opt-in flag (/boot/usb.wakeup) so the safe default requires no user action

Problem

When wakeup_on_write is enabled (current default), every HID write (keyboard/mouse input) triggers a USB remote wakeup signal. When the host PC is restarting, in BIOS/UEFI, or has suspended USB:

  1. The DWC2 controller spams wakeup signals that the host rejects:
    dwc2 4340000.usb: wakeup: signalling skipped: is not allowed by host
    configfs-gadget gadget: usb_gadget_wakeup
    
  2. This causes USB endpoint transfer timeouts:
    dwc2 4340000.usb: dwc2_hsotg_ep_stop_xfr: timeout GINTSTS.GOUTNAKEFF
    dwc2 4340000.usb: dwc2_hsotg_ep_stop_xfr: timeout DOEPCTL.EPDisable
    
  3. The USB gadget gets stuck — keyboard and mouse become permanently unresponsive
  4. In severe cases (Rebooting PC causes USB errors (keyboard + mouse + drive) #220), this causes a kernel NULL pointer dereference crash

This is a widespread issue affecting NanoKVM Full, Lite, and PCIe variants across many host systems.

Root Cause

The wakeup_on_write feature attempts USB remote wakeup signalling on every HID report write. Many host USB controllers do not allow remote wakeup (especially during boot/BIOS, restart, or on certain chipsets like Intel N100/N305). The failed wakeup attempts corrupt the DWC2 endpoint state machine, making recovery impossible without a full PHY restart.

Fix

USB HID devices do not require remote wakeup to function — the host re-enumerates the gadget naturally after reboot. The fix simply inverts the default:

  • Before: wakeup_on_write=1 unless /boot/usb.notwakeup exists (unsafe default)
  • After: wakeup_on_write=0 unless /boot/usb.wakeup exists (safe default)

Users who specifically need USB remote wakeup can opt in by creating /boot/usb.wakeup.

Testing

Tested on NanoKVM PCIe (firmware 2.3.1) connected to a desktop PC:

  • Host reboot no longer causes HID lockup
  • Keyboard and mouse remain functional through host restart cycle
  • No more wakeup: signalling skipped or ep_stop_xfr: timeout errors in dmesg

Related Issues

Fixes #220 — Rebooting PC causes USB errors (keyboard + mouse + drive) + kernel crash
Fixes #302 — HID stops working
Fixes #383 — USB HID stops working after 10-60s (mouse + keyboard)
Fixes #544 — HID not working in BIOS
Fixes #656 — Keyboard and mouse not working on PCIe KVM

… reboot

wakeup_on_write being enabled by default causes the DWC2 USB controller
to spam USB remote wakeup signals when the host PC is restarting or in
BIOS/UEFI. The host rejects these signals ("wakeup: signalling skipped:
is not allowed by host"), which leads to endpoint transfer timeouts
(dwc2_hsotg_ep_stop_xfr: timeout) and leaves the USB gadget in a stuck
state. In some cases this causes a kernel NULL pointer dereference crash.

This affects keyboard, mouse, and touchpad HID devices in both regular
(S03usbdev) and HID-only (S03usbhid) modes.

The fix inverts the default: wakeup_on_write is now disabled unless
explicitly opted-in via /boot/usb.wakeup. This is safe because USB HID
devices do not require remote wakeup to function - the host will
re-enumerate the gadget naturally after reboot.

Fixes sipeed#220, sipeed#302, sipeed#383, sipeed#544, sipeed#656
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant

Comments