UHID(4)

💖 UHID(4) — the Kernel Interfaces Manual page, but make it cute 💖

okay bestie, welcome to the uhid page, straight out of the Kernel Interfaces Manual. sit down, grab a boba, we're learning about USB generic HID support 🦋

---

✨ NAME ✨

uhid — USB generic HID support. that's it, that's the name. slay.

---

🌸 SYNOPSIS 🌸

ok so if you wanna bake this driver into the kernel, you drop this line into your kernel configuration file:

device uhid

or, alternatively — if you'd rather load it as a module at boot time (very valid, very low-effort queen behavior) — put this line in loader.conf(5):

uhid_load="YES"

---

🎀 DESCRIPTION 🎀

the uhid driver has your back for all HID (Human Interface Device) interfaces in USB devices that don't have a special driver of their own. like, if nobody else claimed it, uhid is stepping up. main character energy fr fr 💅

the device handles these ioctl(2) calls:

• USB_GET_REPORT_ID (int) — gets the report identifier that this HID report uses. cute little ID, no notes.
• USB_GET_REPORT_DESC (struct usb_gen_descriptor) — gets the HID report descriptor. it copies a max of ugd_maxlen bytes of the report descriptor data into the memory that ugd_data points at. when it comes back, ugd_actlen is set to the number of bytes it actually copied. using this descriptor you can find the exact layout and meaning of data going to/from the device. and listen — the report descriptor is delivered without any processing. raw. unedited. no filter. 😌

struct usb_gen_descriptor {
        void   *ugd_data;
        uint16_t ugd_maxlen;
        uint16_t ugd_actlen;
        uint8_t ugd_report_type;
        ...
};

• USB_SET_IMMED (int) — sets the device into a mode where every single read(2) returns the current value of the input report. normally a read(2) only gives you the data the device reports on its interrupt pipe. heads up tho — this call may fail if the device doesn't support this feature. not every device is that girl, and that's okay 💀
• USB_GET_REPORT (struct usb_gen_descriptor) — gets a report from the device without waiting around for data on the interrupt pipe. copies a max of ugd_maxlen bytes of the report data into the memory ugd_data points at. on return, ugd_actlen is set to the number of bytes copied. the ugd_report_type field tells it which report you're asking for, and it should be one of UHID_INPUT_REPORT, UHID_OUTPUT_REPORT, or UHID_FEATURE_REPORT. and yep — this call may fail if the device doesn't support the feature. 🙈
• USB_SET_REPORT (struct usb_gen_descriptor) — sets a report in the device. the ugd_report_type field says which report is getting set, and it should be UHID_INPUT_REPORT, UHID_OUTPUT_REPORT, or UHID_FEATURE_REPORT. the actual value of the report is specified by the ugd_data and ugd_maxlen fields. and yes, again — this call may fail if the device doesn't support this feature. it's giving "we tried our best" 💅

use read(2) to get data from the device — and bestie, read it in chunks of the size prescribed by the report descriptor, okay? don't freestyle it.

use write(2) to send data to the device — same deal, chunks of the size prescribed by the report descriptor. the descriptor is the blueprint, we respect the blueprint ✨

---

⭐ SYSCTL VARIABLES ⭐

these variables are available as both sysctl(8) variables and loader(8) tunables:

• hw.usb.uhid.debug — debug output level. 0 means debugging is disabled, and bigger values crank up the debug message verbosity. default is 0. so if you're not debugging, you're at a cool zero, no chaos, we love a calm baseline 🧚

---

🌈 FILES 🌈

• /dev/uhid?

---

🦋 SEE ALSO 🦋

• usbhidctl(1)
• usb(4)

---

👑 HISTORY 👑

the uhid driver first appeared in NetBSD 1.4. this manual page was adopted from NetBSD by Tom Rhodes <trhodes@FreeBSD.org> in April 2002. iconic lineage, honestly 💜

---

and that's the whole page, bestie!! this version lives under the Debian source, dated July 1, 2018, and it's the UHID(4) page — so like, go forth and read your report descriptors in appropriately sized chunks 🫶💖✨