Skip to content

xhc-whb04b-6: bound the display transfer timeout, reconnect on libusb errors - #4838

Draft
hansfbaier wants to merge 2 commits into
LinuxCNC:2.9from
hansfbaier:xhc-whb04b-6-libusb-reconnect
Draft

hansfbaier wants to merge 2 commits into
LinuxCNC:2.9from
hansfbaier:xhc-whb04b-6-libusb-reconnect

Conversation

@hansfbaier

Copy link
Copy Markdown

Problem

A WHB04B-6 handwheel stops responding after a few hours of use, with no error
anywhere: whb.pendant.is-connected stays TRUE, dmesg is clean, the
component keeps running, the mill keeps working. Unplugging and replugging the
receiver brings it back. Power-cycling the pendant does not.

Two defects in src/hal/user_comps/xhc-whb04b-6. One causes the freeze, the
other makes recovery worse than it needs to be.

1. The display push waits forever (usb.cc)

Usb::sendDisplayData() sends each display update with

libusb_control_transfer(deviceHandle, ..., /* transfer timeout[ms] */ 0);

and libusb reads a timeout of 0 as "wait as long as it takes". The call runs on
the same thread that drains USB events for the jog dial, so when the receiver's
firmware stops completing the transfer, that thread blocks with no error and
the dial is dead. A replug is the only way out, because the disconnect makes
the blocked transfer fail.

The patch gives the transfer a 1 second deadline, so a stall becomes an error
the existing reconnect path can act on. A healthy transfer completes in well
under a millisecond, so the deadline costs nothing until something is wrong.

2. libusb return codes are asserted (2.9 only)

XhcWhb04b6Component::process() asserts on three libusb return codes. Any code
the asserts do not list aborts the process, and its HAL pins go with it, so the
LinuxCNC session is left without a pendant until it is restarted. A userspace
USB reset reproduces it:

transfer error: 5
transmission failed, try to reconnect ...
Assertion `(0 == r) || (r == LIBUSB_ERROR_NO_DEVICE)' failed

The codes seen in that path are LIBUSB_ERROR_NOT_FOUND and
LIBUSB_ERROR_OTHER (-99), both outside the assert's list. A failed
libusb_submit_transfer() in the same situation does return EXIT_FAILURE
from run(), which unloads the component just as effectively.

The first commit logs unexpected codes and reconnects instead, and turns the
submit failure into a retry.

master needs only the second commit: there the checks moved into
Usb::process() and no longer assert, so the timeout is the only piece missing.

Testing

LinuxCNC 2.9.10, Raspberry Pi 5 (arm64), receiver 10ce:eb93.

  • Rebuilt with these two commits and installed in place of the packaged binary.
    Normal operation unchanged: component starts, pendant connects, display
    updates, jog counts move.
  • usbreset 10ce:eb93 with the session running. Before: SIGABRT, HAL pins
    removed, session restart needed. After: transfer error: 5, then cleanup: release_interface returned -99, reconnect, whb.pendant.is-connected FALSE
    for about 4 seconds, then TRUE and the dial works again — same process, no
    restart.
  • The freeze itself needs a wedged receiver and was not reproduced on demand.
    The machine now runs a 5 s sampler of the component's thread state plus a
    dump script, so the first field occurrence will show what the 1 s deadline
    does; I will report back either way.

The commits are ordered reconnect-then-timeout because on this branch the
timeout alone could turn a stall into an assert.

The component asserts on libusb return codes in three places, so any error
the asserts do not list kills the process and takes its HAL pins with it.
A USB port reset from userspace is enough to trigger it:

  transfer error: 5
  transmission failed, try to reconnect ...
  Assertion `(0 == r) || (r == LIBUSB_ERROR_NO_DEVICE)' failed

That path is also reachable after an unplug, a hub reset or a power dip.
Log the unexpected code and let the existing reconnect logic do its work,
which is what master already does: there, the checks moved into
Usb::process() and no longer assert.

A failed receive submit is handled the same way: it retries the connection
instead of returning EXIT_FAILURE, which unloads the component.
Usb::sendDisplayData() passes timeout 0 to libusb_control_transfer(), and
libusb reads 0 as "wait forever". The call runs on the thread that also
drains USB events for the jog dial, so when a receiver stops completing the
transfer the handwheel stops responding with no error, no log line, and
pendant.is-connected still TRUE. Unplugging the receiver is the only way
out, because the disconnect finally makes the blocked transfer fail.

A one second deadline turns that stall into an error the reconnect path can
act on. A healthy transfer completes in well under a millisecond, so the
deadline costs nothing in normal operation.
@grandixximo

Copy link
Copy Markdown
Contributor

Thanks for tracking this down. The timeout of 0 in sendDisplayData() is clearly a bug, and master has it too.

This conflicts with #4761, hdiethelm's xhc-whb04b-6 backport to 2.9. That PR already removes these asserts and brings in master's reconnect handling, so once it is merged your first commit isn't needed. Could you wait for #4761, then rebase and keep only the timeout commit? I'll take it to master with the next merge-up.

@hansfbaier

Copy link
Copy Markdown
Author

Agreed on both counts. I checked #4761's head (xhc-whb04b-6-fix-v2_backport-2.9):

  • The libusb asserts are gone and run() uses master's Usb::InitStatus loop, so my first commit — assert removal plus the failed-submit retry — is superseded, and I'll drop it. Our abort reproduction was with the packaged 2.9.10 binary, so that path disappearing in xhc-whb04b-6 fixes backport to 2.9 #4761 is expected.
  • sendDisplayData() there still passes timeout = 0, and the timeout commit applies to that tree unchanged: identical hunk context, git apply --check clean, nothing to rework on rebase.
  • Built xhc-whb04b-6 fixes backport to 2.9 #4761 plus the timeout commit to be sure of the base: compiles with gcc 16.2.1 against the HAL headers in /usr/include/linuxcnc, and the warning count is the same with and without the patch (124, all -Wvolatile from hal_float_t in hal.h).

Marked the PR a draft in the meantime. Once #4761 is merged I will push the branch as a single timeout-only commit on top of the new 2.9 head and flip it back to ready. Taking it up to master with the merge-up sounds good.

Caveat that still stands: the field freeze is not reproduced, so the PR claims only that a stalled display transfer becomes an error the reconnect path can handle instead of an unbounded wait. If the machine catches one, its thread-state dump goes here as a comment.

@hansfbaier
hansfbaier marked this pull request as draft November 14, 2026 08:12
@LinuxCNC LinuxCNC deleted a comment from KentChenY Nov 14, 2026
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