[RPi4] Boot-time's "Network-Install keyboard detection" causes permanent USB device stuck state

[damdo]

Describe the bug

When the Pi 4 boots with Network Install keyboard detection active, certain USB devices that are already connected and powered become permanently unresponsive. The device is electrically detected by the hub (connect status) but never enumerates, the kernel sees device descriptor read/64, error -110 and unexpected setup address command completion code 0x24 on every attempt.

The device can only be recovered by physically power-cycling its own power supply. No software action on the Pi (reboot, xHCI driver rebind, USB VBUS power cycle via uhubctl) restores it.

Setting, in the bootloader config, NET_INSTALL_ENABLED=0 (and NET_INSTALL_AT_POWER_ON=0) resolves the issue completely.

The bootloader's Network Install keyboard detection initialises the USB controller and enumerates all connected devices (as documented: "In order to detect the keyboard, network install must initialise the USB controller and enumerate devices"). When the Linux kernel subsequently starts and re-initialises the xHCI controller, it attempts to enumerate the same devices from scratch. Devices that were left in an addressed/configured state by the bootloader's enumeration may fail to handle this re-enumeration and enter a stuck state.

@timg236 noted in #472:

"You could also try setting NET_INSTALL_ENABLED=0, the bootloader will be looking for HID devices by default which will perturb the USB enumeration timings."

The issue likely affects any USB device whose firmware does not cleanly handle re-enumeration after a host-side USB controller reset without a device-side power cycle. In our case it's an Epson TM-T88V POS receipt printer (USB 2.0 full-speed, 04b8:0202), but raspberrypi/linux#5046 reports the same pattern with a ThingMagic USB Pro UHF Reader.

Suggestion: Could the bootloader cleanly release/reset USB devices (or fully de-initialise the xHCI controller) before handing off to the kernel? This would prevent the double-enumeration that leaves certain devices in a stuck state.

Steps to reproduce the behaviour

1. Connect a USB device with its own power supply (so it stays powered across Pi reboots), e.g., Epson TM-T88V receipt printer with 24V PSU
2. Ensure NET_INSTALL_ENABLED=1 (default) or NET_INSTALL_AT_POWER_ON=1 (set in default bootloader images)
3. Boot or reboot the Pi (sudo reboot)
4. The device is detected electrically (uhubctl shows power connect) but never enumerates

Expected: device enumerates normally after every boot.
Actual: device enters permanent stuck state, requiring physical power cycle to recover.

Connecting the device after the Pi has finished booting works every time, the issue is specific to the bootloader-to-kernel USB handoff.

Device (s)

Raspberry Pi 4 Mod. B

Bootloader configuration.

Default (as shipped):

[all]
BOOT_UART=0
WAKE_ON_GPIO=1
POWER_OFF_ON_HALT=0
NET_INSTALL_AT_POWER_ON=1

Workaround: to temporarily fix the issue, set in the bootloader EEPROM config:

NET_INSTALL_ENABLED=0
NET_INSTALL_AT_POWER_ON=0

System

• Non standard distro (https://github.com/gokrazy)
• Kernel: Linux 6.11.4 and 7.0.9 (reproduced on both) e.g. Linux cassa 7.0.9 #1 SMP PREEMPT Wed Mar 1 20:57:29 UTC 2017 aarch64 GNU/Linux
• USB device: Epson TM-T88V receipt printer (04b8:0202, USB 2.0 full-speed, separate 24V power supply)
• Bootloader version: pieeprom-2026-05-17 807d090
• Firmware version: raspberrypi/firmware@0e05e17

Bootloader logs

Not captured via UART. Diagnosis based on kernel dmesg after boot.

USB device details:

• Vendor/Product: 04b8:0202 (Seiko Epson / TM-T88V)
• USB 2.0 full-speed (12 Mbps)
• Connected through the Pi 4's internal USB 2.0 hub (2109:3431)

dmesg after boot (repeats for ~7 minutes, 5 cycles, 20 device numbers before kernel gives up):

[  3.393] xhci_hcd 0000:01:00.0: xHCI Host Controller
[  3.441] hub 1-0:1.0: USB hub found — 1 port detected
[  3.709] usb 1-1: new high-speed USB device number 2 using xhci_hcd
[  3.863] hub 1-1:1.0: USB hub found — 4 ports detected
[  4.164] usb 1-1.4: new full-speed USB device number 3 using xhci_hcd
[ 19.508] usb 1-1.4: device descriptor read/64, error -110
[ 35.128] usb 1-1.4: device descriptor read/64, error -110
[ 35.316] usb 1-1.4: new full-speed USB device number 4 using xhci_hcd
[ 50.740] usb 1-1.4: device descriptor read/64, error -110
[ 66.356] usb 1-1.4: device descriptor read/64, error -110
[ 66.468] usb 1-1-port4: attempt power cycle
[ 67.076] usb 1-1.4: new full-speed USB device number 5 using xhci_hcd
[ 67.707] xhci_hcd 0000:01:00.0: ERROR: unexpected setup address command completion code 0x24.
[ 68.548] xhci_hcd 0000:01:00.0: ERROR: unexpected setup address command completion code 0x24.
[ 68.764] usb 1-1.4: device not accepting address 5, error -22
[ 68.770] usb 1-1.4: WARN: invalid context state for evaluate context command.
[ 70.558] usb 1-1-port4: unable to enumerate USB device

Board Revision

# cat /proc/cpuinfo
processor       : 0
BogoMIPS        : 108.00
Features        : fp asimd evtstrm crc32 cpuid
CPU implementer : 0x41
CPU architecture: 8
CPU variant     : 0x0
CPU part        : 0xd08
CPU revision    : 3

processor       : 1
BogoMIPS        : 108.00
Features        : fp asimd evtstrm crc32 cpuid
CPU implementer : 0x41
CPU architecture: 8
CPU variant     : 0x0
CPU part        : 0xd08
CPU revision    : 3

processor       : 2
BogoMIPS        : 108.00
Features        : fp asimd evtstrm crc32 cpuid
CPU implementer : 0x41
CPU architecture: 8
CPU variant     : 0x0
CPU part        : 0xd08
CPU revision    : 3

processor       : 3
BogoMIPS        : 108.00
Features        : fp asimd evtstrm crc32 cpuid
CPU implementer : 0x41
CPU architecture: 8
CPU variant     : 0x0
CPU part        : 0xd08
CPU revision    : 3

USB boot

Not applicable, booting from SD card, not USB. The affected device is a USB peripheral (receipt printer).

NVMe boot

No response

Network (TFTP boot)

Not applicable

[damdo]

cc. @timg236 as I've seen you posting on similar USB troubles. Thanks!!