Add hidraw backend for FreeBSD by aokblast · Pull Request #730 · libusb/hidapi

aokblast · 2025-03-27T09:16:51Z

FreeBSD support hidraw in Kernel from 13.0.
By using libusb only, we can only see the HID device from usb. To address this, we implement hidraw backend for FreeBSD.

Just like Linux use libudev to handle usb specified HID stuff (like Manufacture), we use libusb to handle it.

Sponsored-by: FreeBSD Foundation

Related to #274
Fixes#543

Assisted-by: codex:gpt-5

aokblast · 2025-03-27T09:19:11Z

Currently, some stuff like the Report Descriptor parser and error registry routine are copied from Linux and I think they are platform independent. Can we create a common directory or hidraw directory in code then put them inside?

Have tested by the hidtest program.

Youw

No more comments

aokblast · 2025-03-27T14:17:41Z

Thanks for @Youw your review:).

Then, What is your opinion about this?

Currently, some stuff like the Report Descriptor parser and error registry routine are copied from Linux and I think they are platform independent. Can we create a common directory or hidraw directory in code then put them inside?
Have tested by the hidtest program.

Youw · 2025-03-27T14:33:01Z

Thanks for @Youw your review:).
Then, What is your opinion about this?
Currently, some stuff like the Report Descriptor parser and error registry routine are copied from Linux and I think they are platform independent. Can we create a common directory or hidraw directory in code then put them inside?
Have tested by the hidtest program.

I thinjk that is a good idea, but I don't think it really is nesessary to do so in scope of this PR.
There are really lots of stuff which I'd like to share among beckends, and I think it is going to be some refactoring after all.

mcuee · 2025-03-28T01:50:28Z

Nice. This will address the following issue.

FreeBSD hidraw backend to replace libusb backend #543

aokblast · 2025-03-28T02:10:47Z

Oops. I forget we have udev-devd stuff. Maybe we should use udev also?

Youw · 2025-03-28T10:27:32Z

Oops. I forget we have udev-devd stuff. Maybe we should use udev also?

I lost context here. What for? Seem like you have all the functionality implemented already. Aren't you?

aokblast · 2025-03-29T07:55:43Z

Oops. I forget we have udev-devd stuff. Maybe we should use udev also?
I lost context here. What for? Seem like you have all the functionality implemented already. Aren't you?

Yes, all functionality is fully implemented. I am just thinking if we should use libudev make hidapi more portable.

mcuee · 2025-03-30T02:00:25Z

First test under FreeBSD 14.1 Release, under a physical machine (Chuwi mini PC, Intel J4125 CPU, 8GB RAM, 256GB SSD)

There are a few compiler warnings.

mcuee@freebsd14:~/build/hidapi_pr730 $ uname -a
FreeBSD freebsd14 14.1-RELEASE FreeBSD 14.1-RELEASE releng/14.1-n267679-10e31f0946d8 GENERIC amd64
mcuee@freebsd14:~/build/hidapi_pr730 $ cc -v
FreeBSD clang version 18.1.5 (https://github.com/llvm/llvm-project.git llvmorg-18.1.5-0-g617a15a9eac9)
Target: x86_64-unknown-freebsd14.1
Thread model: posix
InstalledDir: /usr/bin
mcuee@freebsd14:~/build/hidapi_pr730 $ make
make all-recursive
Making all in freebsd
CC hid.lo
hid.c:396:24: warning: passing 'uint8_t[255]' (aka 'unsigned char[255]') to parameter of type 'const char *' converts between pointers to integer types where one is of the unique plain 'char' type and the other is not [-Wpointer-sign]
396 | mbstowcs(namebuffer, buffer, sizeof(namebuffer));
| ^~~~~~
/usr/include/stdlib.h:107:64: note: passing argument to parameter here
107 | size_t mbstowcs(wchar_t * __restrict , const char * __restrict, size_t);
| ^
hid.c:603:1: warning: non-void function does not return a value [-Wreturn-type]
603 | }
| ^
hid.c:937:7: warning: passing 'const char *' to parameter of type 'void *' discards qualifiers [-Wincompatible-pointer-types-discards-qualifiers]
937 | free(dev->device_path);
| ^~~~~~~~~~~~~~~~
/usr/include/stdlib.h:101:18: note: passing argument to parameter here
101 | void free(void *);
| ^
3 warnings generated.
CCLD libhidapi-hidraw.la
Making all in libusb
CC hid.lo
CCLD libhidapi-libusb.la
Making all in hidtest
CC test.o
CCLD hidtest-libusb
CCLD hidtest-hidraw

aokblast · 2025-03-30T02:06:02Z

Fix it:). Forget to fix the warning.

mcuee · 2025-03-30T02:06:06Z

Somehow hidtest-hidraw will seg fault with the Microchip Simple HID example.

mcuee@freebsd14:~/build/hidapi_pr730 $ sudo ./hidtest/hidtest-hidraw
hidapi test/example tool. Compiled with hidapi version 0.15.0, runtime version 0.15.0.
Compile-time version matches runtime version of hidapi.
Segmentation fault
mcuee@freebsd14:~/build/hidapi_pr730 $ sudo ./hidtest/hidtest-libusb
hidapi test/example tool. Compiled with hidapi version 0.15.0, runtime version 0.15.0.
Compile-time version matches runtime version of hidapi.
Device Found
type: 04f2 0760
path: 0-3:1.0
serial_number: (null)
Manufacturer: Chicony
Product: USB Keyboard
Release: 100
Interface: 0
Usage (page): 0x0 (0x0)
Bus type: 1 (USB)
Report Descriptor: (65 bytes)
0x05, 0x01, 0x09, 0x06, 0xa1, 0x01, 0x05, 0x07, 0x19, 0xe0, 0x29, 0xe7, 0x15, 0x00, 0x25, 0x01, 0x75, 0x01, 0x95, 0x08, 0x81, 0x02, 0x95, 0x01, 0x75, 0x08, 0x81, 0x01, 0x95, 0x03, 0x75, 0x01, 0x05, 0x08, 0x19, 0x01, 0x29, 0x03, 0x91, 0x02, 0x95, 0x05, 0x75, 0x01, 0x91, 0x01, 0x95, 0x06, 0x75, 0x08, 0x15, 0x00, 0x26, 0xff, 0x00, 0x05, 0x07, 0x19, 0x00, 0x2a, 0xff, 0x00, 0x81, 0x00, 0xc0, Device Found
type: 04f2 0760
path: 0-3:1.1
serial_number: (null)
Manufacturer: Chicony
Product: USB Keyboard
Release: 100
Interface: 1
Usage (page): 0x0 (0x0)
Bus type: 1 (USB)
Report Descriptor: (127 bytes)
0x06, 0x01, 0x00, 0x09, 0x80, 0xa1, 0x01, 0x85, 0x01, 0x19, 0x81, 0x29, 0x83, 0x15, 0x00, 0x25, 0x01, 0x95, 0x03, 0x75, 0x01, 0x81, 0x02, 0x95, 0x01, 0x75, 0x05, 0x81, 0x01, 0xc0, 0x05, 0x0c, 0x09, 0x01, 0xa1, 0x01, 0x85, 0x03, 0x15, 0x00, 0x25, 0x01, 0x75, 0x01, 0x95, 0x08, 0x19, 0xb5, 0x29, 0xb8, 0x09, 0xcd, 0x09, 0xe2, 0x09, 0xe9, 0x09, 0xea, 0x81, 0x02, 0x0a, 0x83, 0x01, 0x0a, 0x8a, 0x01, 0x0a, 0x92, 0x01, 0x0a, 0x94, 0x01, 0x0a, 0x21, 0x02, 0x1a, 0x23, 0x02, 0x2a, 0x25, 0x02, 0x81, 0x02, 0x0a, 0x26, 0x02, 0x0a, 0x27, 0x02, 0x0a, 0x2a, 0x02, 0x95, 0x03, 0x81, 0x02, 0x95, 0x05, 0x81, 0x01, 0xc0, 0x06, 0x00, 0xff, 0x09, 0x01, 0xa1, 0x01, 0x85, 0x02, 0x25, 0x01, 0x15, 0x00, 0x75, 0x01, 0x95, 0x08, 0x1a, 0xf1, 0x00, 0x2a, 0xf8, 0x00, 0x81, 0x02, 0xc0, Device Found
type: 1ea7 0064
path: 0-4:1.0
serial_number: (null)
Manufacturer: (null)
Product: 2.4G Mouse
Release: 200
Interface: 0
Usage (page): 0x0 (0x0)
Bus type: 1 (USB)
Report Descriptor: (105 bytes)
0x06, 0xb5, 0xff, 0x09, 0x01, 0xa1, 0x01, 0x85, 0xb5, 0x09, 0x02, 0x15, 0x00, 0x26, 0xff, 0x00, 0x75, 0x08, 0x95, 0x07, 0x81, 0x02, 0x09, 0x02, 0x15, 0x00, 0x26, 0xff, 0x00, 0x75, 0x08, 0x95, 0x07, 0x91, 0x02, 0xc0, 0x05, 0x01, 0x09, 0x02, 0xa1, 0x01, 0x85, 0x02, 0x09, 0x01, 0xa1, 0x00, 0x05, 0x09, 0x19, 0x01, 0x29, 0x08, 0x15, 0x00, 0x25, 0x01, 0x95, 0x08, 0x75, 0x01, 0x81, 0x02, 0x05, 0x01, 0x09, 0x30, 0x09, 0x31, 0x16, 0x01, 0xf8, 0x26, 0xff, 0x07, 0x75, 0x0c, 0x95, 0x02, 0x81, 0x06, 0x09, 0x38, 0x15, 0x81, 0x25, 0x7f, 0x75, 0x08, 0x95, 0x01, 0x81, 0x06, 0x05, 0x0c, 0x0a, 0x38, 0x02, 0x95, 0x01, 0x81, 0x06, 0xc0, 0xc0, Device Found
type: 04d8 003f
path: 0-2:1.0
serial_number: (null)
Manufacturer: Microchip Technology Inc.
Product: Simple HID Device Demo
Release: 2
Interface: 0
Usage (page): 0x0 (0x0)
Bus type: 1 (USB)
Report Descriptor: (28 bytes)
0x06, 0x00, 0xff, 0x09, 0x01, 0xa1, 0x01, 0x19, 0x01, 0x29, 0x40, 0x15, 0x01, 0x25, 0x40, 0x75, 0x08, 0x95, 0x40, 0x81, 0x00, 0x19, 0x01, 0x29, 0x40, 0x91, 0x00, 0xc0, Manufacturer String: Microchip Technology Inc.
Product String: Simple HID Device Demo
Unable to read serial number string
Serial Number String: (0) Report Descriptor: (28 bytes)
0x06, 0x00, 0xff, 0x09, 0x01, 0xa1, 0x01, 0x19, 0x01, 0x29, 0x40, 0x15, 0x01, 0x25, 0x40, 0x75, 0x08, 0x95, 0x40, 0x81, 0x00, 0x19, 0x01, 0x29, 0x40, 0x91, 0x00, 0xc0, Device Found
type: 04d8 003f
path: 0-2:1.0
serial_number: (null)
Manufacturer: Microchip Technology Inc.
Product: Simple HID Device Demo
Release: 2
Interface: 0
Usage (page): 0x1 (0xff00)
Bus type: 1 (USB)
Indexed String 1: Microchip Technology Inc.
Unable to send a feature report: hid_error is not implemented yet
Unable to get a feature report: hid_error is not implemented yet
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
read() timeout

mcuee · 2025-03-30T02:10:28Z

Fix it:). Forget to fix the warning.

Thanks. The compiler warnings are gone.

The Segfault issue is still there though.

aokblast · 2026-05-23T08:51:13Z

Thanks a lot for the updates. Let me digest and check again.
The issue turned out to be quite simple: you forgot to arm EP1OUT the first time
You are absolute right here. I have seen strange issues previously with random data for the initial run. I am not the author of the origina FX2HID code. The original auther is Jan Axelson (author of the book "USB Complete").

@aokblast

Great, now this PR works perfectly under your FreeBSD 16.0 Current build (tested with VirtualBox VM first).

mcuee@freebsd16vm:~/build/hidapitester $ ./hidapitester_hidraw_pr730 --open-path /dev/hidraw0 --buflen 256 -l 129 --send-output 0,1,2,3,4,5,6,7,8,9 ,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,
59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,1
06,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128 --read-input
Opening device. path: /dev/hidraw0
Writing output report of 129-bytes...wrote 129 bytes:
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F
20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F
40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F 50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F
60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F 70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 7F
80
Reading up to 129-byte input report, 250 msec timeout...read 128 bytes:
01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 20
21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F 40
41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F 50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F 60
61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F 70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 7F 80
00
Closing device

Thanks! Hope we can merge this patch ASAP:).

mcuee · 2026-05-24T11:38:52Z

Going back to the Generic HID PIC FW example (Full Speed USB device), there are no issues.

mcuee@freebsd16vm:~/build/hidapitester $ uname -a
FreeBSD freebsd16vm 16.0-CURRENT FreeBSD 16.0-CURRENT #0 main-n286042-28d85db46b48-dirty: Fri May 22 16:36:08 CST 2026 blast@blast-devserv:/usr/obj/usr/src/amd64.amd64/sys/GENERIC-NODEBUG amd64
mcuee@freebsd16vm:~/build/hidapitester $ sudo ./hidapitester_hidraw_pr730 --vidpid 0925:7001 --open --buflen 64 -l 3 --send-output 2,3,4,5 --read-input
Opening device, vid/pid: 0x0925/0x7001
Writing output report of 3-bytes...wrote 3 bytes:
02 03 04
Reading up to 3-byte input report, 250 msec timeout...read 3 bytes:
01 03 04
Closing device
mcuee@freebsd16vm:~/build/hidapitester $ sudo ./hidapitester_hidraw_pr730 --vidpid 0925:7001 --open --buflen 64 -l 3 --send-feature 3,3,4,5 --read-feature 4
Opening device, vid/pid: 0x0925/0x7001
Writing 3-byte feature report...wrote 3 bytes:
03 03 04
Reading 3-byte feature report, report_id 4...read 3 bytes:
04 03 04
Closing device

mcuee · 2026-05-24T11:46:37Z

Going to the original Generic PIC FW (unmodified, from Jan Axelson, Full Speed USB device) with two bytes reoort, it also works.

mcuee@freebsd16vm:~/build/hidapitester $ sudo ./hidapitester_hidraw_pr730 --vidpid 0925:7001 --open --buflen 64 -l 3 --send-output 0,1,2 --read-input
Opening device, vid/pid: 0x0925/0x7001
Writing output report of 3-bytes...wrote 3 bytes:
00 01 02
Reading up to 3-byte input report, 250 msec timeout...read 2 bytes:
01 02 00
Closing device
mcuee@freebsd16vm:~/build/hidapitester $ sudo ./hidapitester_libusb_pr728 --vidpid 0925:7001 --open --buflen 64 -l 3 --send-output 0,1,2 --read-inpu
t
Opening device, vid/pid: 0x0925/0x7001
Writing output report of 3-bytes...wrote 3 bytes:
00 01 02
Reading up to 3-byte input report, 250 msec timeout...read 2 bytes:
01 02 00
Closing device

mcuee · 2026-05-24T11:49:09Z

@aokblast
I have approved this PR.

@Youw
Please review and I think this is a good addition to hidapi under FreeBSD. Since this is a new backend, it does not affect much other codes. Issues specific to this backend can be fixed within this backend.

mcuee · 2026-05-24T11:51:59Z

@wulf7

Please re-review as well. Thanks.

mcuee · 2026-05-27T03:38:58Z

@aokblast

BTW, somehow your ISO image only works under VirtualBox VMs, I could not install it under an Intel N100 mini PC, not so sure about the reason (kernel panic). Therefore I cannot test it under physical machine as of now.

Just FYI only.

Now I am lazy to build FreeBSD using source code. I only did that a few times when HPS was developing the new FreeBSD USB Stack many years ago.

aokblast · 2026-05-27T05:54:08Z

@aokblast
BTW, somehow your ISO image only works under VirtualBox VMs, I could not install it under an Intel N100 mini PC, not so sure about the reason (kernel panic). Therefore I cannot test it under physical machine as of now.
Just FYI only.
Now I am lazy to build FreeBSD using source code. I only did that a few times when HPS was developing the new FreeBSD USB Stack many years ago.

Hi, is there any crash log?

wulf7

LGTM

mcuee · 2026-05-28T05:16:12Z

@aokblast
Hi, is there any crash log?

Let me capture the crash log over the weekend. I will also compare with FreeBSD 16.0-Current Snapshot.
https://download.freebsd.org/ftp/snapshots/amd64/amd64/ISO-IMAGES/16.0/

I have a few Chuwi Herobox mini PCs running Linux and BSDs. All of them have 8GB RAM. Each has the original 256GB SSD and one more SATA SSD (128GB or 256GB).

Intel N4500 Mini PC -- OpenBSD 7.8 (will upgrade to 7.9 later) and NetBSD 10.1
Intel J4125 Mini PC -- Debian 13 and FreeBSD 15 Release
Intel N100 Mini PC -- Ubuntu 26.04 + Fedora 44 on the main SSD, CachyOS on the secondary SSD
Intel N100 Mini PC -- Ubuntu 26.04 + Fedora 44 Silverblue on the main SSD, EndeavourOS on the secondary SSD.

I will kill the two Arch Based Linux distros (not really using them much) and install FreeBSD/OpenBSD.

cederom · 2026-05-28T13:00:25Z

For quick testing I recommend VENTOY [1] it provides USB BOOT menu supporting MBR/GPT/BIOS/UEFI where you can choose ISO from the same pendrive to boot. So you can have multiple images on the same bootable pendrive.. and you can use it for storage as well :-)

Please let me know if there is anything to test on FreeBSD 14 :-) I can also boot of 15 or 16 if needed :-)

[1] https://www.ventoy.net/en/index.html

wulf7 · 2026-05-28T14:27:29Z

I could not install it under an Intel N100 mini PC, not so sure about the reason (kernel panic).

There is a known hardware bug in Alder Lake processors. See https://lists.freebsd.org/archives/freebsd-current/2025-January/006984.html

mcuee · 2026-05-29T13:59:35Z

I could not install it under an Intel N100 mini PC, not so sure about the reason (kernel panic).
Hi, is there any crash log?

Sorry I made a mistake, it is not kernel panic, rather the system does not recognize the USB Flash Disk as bootable at all.

I tried the latest snapshot (FreeBSD-16.0-CURRENT-amd64-20260525-490c53e9353f-286096-disc1.iso) and the issue is the same, tested with two USB Flash disks.

Then I tested OpenBSD 7.9 release and it is able to boot (but then it does not recognize the wired and wireless network adapter).

There is a known hardware bug in Alder Lake processors. See https://lists.freebsd.org/archives/freebsd-current/2025-January/006984.html

Interesting.

aokblast · 2026-05-30T06:47:06Z

I could not install it under an Intel N100 mini PC, not so sure about the reason (kernel panic).
Hi, is there any crash log?
Sorry I made a mistake, it is not kernel panic, rather the system does not recognize the USB Flash Disk as bootable at all.
I tried the latest snapshot (FreeBSD-16.0-CURRENT-amd64-20260525-490c53e9353f-286096-disc1.iso) and the issue is the same, tested with two USB Flash disks.
Then I tested OpenBSD 7.9 release and it is able to boot (but then it does not recognize the wired and wireless network adapter).
There is a known hardware bug in Alder Lake processors. See https://lists.freebsd.org/archives/freebsd-current/2025-January/006984.html
Interesting.

Is it possible to choose EFI file from your UEFI?

mcuee · 2026-05-31T03:07:52Z

Is it possible to choose EFI file from your UEFI?

Using Ventoy and then I can do that.

Interesting findings -- now FreeBSD 15.0 Release and OpenBSD 7.9 can boot and I have installed them to the second SATA SSDs of the two Intel N100 Mini PCs. Somehow I need to use HTTP install.

For the FreeBSD 16.0-Current images (your version or the snapshot version), both will fail to boot.

All in all, looks like the issue is related to file system corruption.
https://lists.freebsd.org/archives/freebsd-current/2025-January/006984.html

Screen photo taken from my mobile phone.

Assisted-by: codex:gpt-5

Youw · 2026-07-30T16:52:11Z

I've used gpt5.6-sol and found a number of issues with this implementation.
I'll run it to fix those issues and push here, instead of posting review comments

Resolve the build-system conflicts with current master, fix the FreeBSD backend review findings, and add comprehensive native-backend CI including installed CMake export consumers. Assisted-by: codex:gpt-5 Assisted-by: claude-code:claude-fable-5

Use explicit zeroing for FreeBSD ioctl structures and keep parser locals outside cleanup jumps so the warnings-as-errors C++ CI build succeeds. Assisted-by: codex:gpt-5

Youw · 2026-07-30T18:41:37Z

Codex updated the PR branch and pushed a186873:

Merged current master (518fbd1) and resolved the Autotools/build-system conflicts.
Fixed the FreeBSD hidraw backend findings around enumeration/list ownership, allocation and handle cleanup, bus/device metadata, report-ID/report-descriptor handling, error propagation, read-only enumeration, and C++ compatibility.
Integrated and exercised both FreeBSD backends through Autotools, CMake, Meson, manual builds, and pkg-config; added a warnings-as-errors C++ build for the new backend.
Added runtime pkg-config consumers plus installed shared/static CMake export consumer tests for both hidapi::hidraw and hidapi::libusb, following the pattern from cmake: provide generic hidapi pkg-config alias #831.
Ran a fresh read-only Fable 5 review and addressed the new actionable findings.

Validation completed locally across Autotools, CMake shared/static, Meson, pkg-config, and installed export consumers. All PR checks are now green, including the native FreeBSD job and AppVeyor.

Related to #274. Fixes #543.

Generated by Codex (GPT-5).

Youw · 2026-07-30T22:22:27Z

Now someone could test and tell if there anything else left to fix - that would be helpful to move this forward.

mcuee · 2026-07-30T23:11:47Z

Now someone could test and tell if there anything else left to fix - that would be helpful to move this forward.

Yes I will test over the weekend.

mcuee · 2026-07-30T23:13:07Z

@aokblast and @cederom

Please carry out the test on your FreeBSD setup as well. Thanks.

mcuee · 2026-08-07T02:17:43Z

Now someone could test and tell if there anything else left to fix - that would be helpful to move this forward.
Yes I will test over the weekend.

Sorry I was busy. I will try to do it this weekend or next week.

Youw self-requested a review March 27, 2025 10:33

Youw added enhancement New feature or request bsd FreeBSD, NetBSD, OpenBSD, etc labels Mar 27, 2025