Skip to content

libuuu: use hidapi for HID devices on macOS to avoid sudo - #514

Open
marekvi95 wants to merge 1 commit into
nxp-imx:masterfrom
marekvi95:macos-hid-no-sudo
Open

marekvi95 wants to merge 1 commit into
nxp-imx:masterfrom
marekvi95:macos-hid-no-sudo

Conversation

@marekvi95

Copy link
Copy Markdown
Contributor

Problem

On macOS, downloading to i.MX/RT boards in SDP/SDPS mode needs sudo; otherwise uuu (and the Python libuuu wrapper) fails with:

detach kernel driver failure (-3)

The boot ROM HID interface is owned by the IOHIDFamily kernel driver. libusb can only detach it on Darwin by re-enumerating the device with capture, which requires root. Skipping the detach only moves the failure to libusb_claim_interface (LIBUSB_ERROR_ACCESS).

Change

  • On __APPLE__, HIDTrans uses hidapi (IOHIDFamily, no extra privileges) for open/read/write/close. libusb is still used for enumeration; the matching HID device is selected by its USB location ID.
  • Stale input reports are flushed on open; reads skip reports with an unexpected report ID (hidapi returns whichever input report arrived first).
  • Linux and Windows code paths are unchanged.
  • hidapi added as a macOS dependency: libuuu/uuu CMake (pkg-config), Python wrapper (CMake + vcpkg osx platform), macOS CI workflow, README.

Testing (macOS arm64, no sudo)

Board Test Result
MIMXRT1060-EVK SDP: write 192 KB ×3 + rdmem read-back, uuu CLI OK
MIMXRT1060-EVK same via Python wrapper OK
i.MX93 SDPS: boot of signed U-Boot, uuu CLI OK
i.MX93 same via Python wrapper OK
MIMXRT1060-EVK stock libuuu 1.5.243 detach kernel driver failure (-3)

The wrapper was built manually against Homebrew libraries; the vcpkg wrapper build has not been run locally.

🤖 Generated with Claude Code

On macOS the SDP/SDPS boot ROM HID interface is owned by the
IOHIDFamily kernel driver. libusb can only detach it by re-enumerating
the device with capture, which requires root, so uuu fails with
"detach kernel driver failure (-3)" (or LIBUSB_ERROR_ACCESS on claim)
unless run with sudo.

On macOS, let HIDTrans talk to the device through hidapi, which goes
through IOHIDFamily and needs no extra privileges. libusb is still used
for enumeration; the matching HID device is selected by its USB
location ID. Stale input reports are flushed on open and reads skip
reports with an unexpected ID. Linux and Windows are unchanged.

Add hidapi as a macOS dependency for uuu, libuuu, the Python wrapper
(vcpkg) and the macOS CI workflow, and update the README.

Tested without sudo on MIMXRT1060-EVK (SDP write/rdmem) and i.MX93
(SDPS boot of a signed U-Boot) with both uuu and the Python wrapper.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Marek Vitula <marek.vitula@nxp.com>
@nxpfrankli

Copy link
Copy Markdown
Contributor

The key problem is that hidapi block -m options and mult-boards support.

This branch has not been deployed

No deployments
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