Something went wrong. Try again.
A Zig library for talking to USB and Bluetooth HID devices on Linux, FreeBSD, Windows and macOS, without linking the C hidapi
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305// SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! The parts of the kernel's `hidraw` interface this library needs: the ioctl//! request numbers and the structures they exchange.//!//! There is no syscall wrapper here. `std.Io.Operation` has a//! `device_io_control` tag which is `ioctl` on POSIX and//! `NtDeviceIoControlFile` on Windows, so the request goes through the//! caller's `Io` -- cancelable, and the same call the Windows backend will//! make -- and this file is left with the numbers.//!//! The declarations mirror `uapi/linux/hidraw.h`, and the comments on the//! request numbers are the kernel's own text from//! https://docs.kernel.org/hid/hidraw.html.//!//! Nothing outside the Linux backend imports this file. Two of its//! declarations nonetheless reach `Device`'s callers, re-exported by//! `backend/linux.zig` under portable names: `BUS`, as the type of the bus a//! device is attached to, and `HID_MAX_DESCRIPTOR_SIZE`, as a buffer size that//! always suffices. `Size` is the bound a buffer length has to fit.//!//! Requests that carry a caller supplied buffer are functions rather than//! constants, because the buffer length is encoded in the request number//! itself. They take that length as a `Size`, which is narrower than the//! `usize` a caller usually has in hand, so the narrowing and the decision of//! what to do about a buffer too large to name belong to the caller.
const std = @import("std");const linux = std.os.linux;
/// The type of the length field of a request number: 14 bits on most/// architectures, 13 bits on the ones that spend an extra bit on the/// direction. Following the target rather than hardcoding a width is the/// whole reason this is taken from `linux.IOCTL` rather than written out.const Size = @FieldType(linux.IOCTL.Request, "size");
/// The largest buffer any of the requests below can name.////// The shared `hidraw` backend carries this in its request table, because/// FreeBSD's is 13 bits where most of Linux's is 14, and a caller's buffer/// has to be clamped to whichever applies.pub const max_len: u16 = std.math.maxInt(Size);
/// The bus a device is attached to, as the `BUS_*` values of/// `uapi/linux/input.h`.////// Non-exhaustive, because the kernel gains new bus types over time and may/// report one this list does not name.pub const BUS = enum(u32) { PCI = 0x01, ISAPNP = 0x02, USB = 0x03, HIL = 0x04, BLUETOOTH = 0x05, VIRTUAL = 0x06, ISA = 0x10, I8042 = 0x11, XTKBD = 0x12, RS232 = 0x13, GAMEPORT = 0x14, PARPORT = 0x15, AMIGA = 0x16, ADB = 0x17, I2C = 0x18, HOST = 0x19, GSC = 0x1A, ATARI = 0x1B, SPI = 0x1C, RMI = 0x1D, CEC = 0x1E, INTEL_ISHTP = 0x1F, AMD_SFH = 0x20, _,};
/// What `HIDIOCGRAWINFO` fills in, laid out as `struct hidraw_devinfo`.////// The kernel declares the vendor and product fields signed. They are the/// same bits either way, and a VID or PID reads as an unsigned number, so they/// are `u16` here.pub const hidraw_devinfo = extern struct { bustype: BUS, vendor: u16, product: u16,
/// A zeroed value to hand to the ioctl. /// /// Zero is not one of the `BUS_*` values, which only a non-exhaustive /// `BUS` can represent; a device that answers always overwrites it. pub const init: hidraw_devinfo = .{ .bustype = @fromBackingInt(0), .vendor = 0, .product = 0, };
comptime { // The kernel copies this structure in and out by size, so a layout // that drifts from the header has to fail the build rather than // quietly exchange the wrong bytes. std.debug.assert(@sizeOf(hidraw_devinfo) == 8); }};
/// The largest report descriptor the kernel will hand out, so a buffer this/// size always fits one.pub const HID_MAX_DESCRIPTOR_SIZE = 4096;
/// What `HIDIOCGRDESC` fills in, laid out as/// `struct hidraw_report_descriptor`.////// The buffer is a fixed `HID_MAX_DESCRIPTOR_SIZE` bytes rather than a/// pointer, so a value of this type is over 4 KiB and is worth keeping off a/// small stack.pub const hidraw_report_descriptor = extern struct { size: u32, value: [HID_MAX_DESCRIPTOR_SIZE]u8,
/// A zeroed descriptor asking for `size` bytes. /// /// `HIDIOCGRDESC` copies out only as many bytes as this says, so `size` /// has to be set before the call, from `HIDIOCGRDESCSIZE`. pub fn init(size: u32) hidraw_report_descriptor { return .{ .size = size, .value = @splat(0), }; }};
/// This ioctl will get the size of the device’s report descriptor.pub const HIDIOCGRDESCSIZE = linux.IOCTL.IOR('H', 0x01, u32);
/// This ioctl returns the device’s report descriptor using a/// hidraw_report_descriptor struct. Make sure to set the size field of the/// hidraw_report_descriptor struct to the size returned from HIDIOCGRDESCSIZE.pub const HIDIOCGRDESC = linux.IOCTL.IOR('H', 0x02, hidraw_report_descriptor);
/// This ioctl will return a hidraw_devinfo struct containing the bus type, the/// vendor ID (VID), and product ID (PID) of the device. The bus type can be/// one of:////// - BUS_USB/// - BUS_HIL/// - BUS_BLUETOOTH/// - BUS_VIRTUAL////// which are defined in uapi/linux/input.h.pub const HIDIOCGRAWINFO = linux.IOCTL.IOR('H', 0x03, hidraw_devinfo);
// The direction bits of an ioctl request number, named from userspace's point// of view: `read` means the kernel writes into the caller's buffer. They match// the encoding `std.os.linux.IOCTL` uses on x86, ARM, RISC-V and the rest of// the common architectures. MIPS, PowerPC and SPARC spend three bits on the// direction and give the write bit a different value, so unlike `Size`, which// follows whatever the target uses, these do not, and the requests built below// would be wrong there.const read = 2;const write = 1;
/// This ioctl returns a string containing the vendor and product strings of the/// device. The returned string is Unicode, UTF-8 encoded.pub fn HIDIOCGRAWNAME(len: u16) u32 { const request: linux.IOCTL.Request = .{ .io_type = 'H', .nr = 0x04, .dir = read, .size = @intCast(@min(len, max_len)), }; return @bitCast(request);}
/// This ioctl returns a string representing the physical address of the/// device. For USB devices, the string contains the physical path to the device/// (the USB controller, hubs, ports, etc). For Bluetooth devices, the string/// contains the hardware (MAC) address of the device.pub fn HIDIOCGRAWPHYS(len: u16) u32 { const request: linux.IOCTL.Request = .{ .io_type = 'H', .nr = 0x05, .dir = read, .size = @intCast(@min(len, max_len)), }; return @bitCast(request);}
/// This ioctl will send a feature report to the device. Per the HID/// specification, feature reports are always sent using the control endpoint./// Set the first byte of the supplied buffer to the report number. For devices/// which do not use numbered reports, set the first byte to 0. The report data/// begins in the second byte. Make sure to set len accordingly, to one more/// than the length of the report (to account for the report number).pub fn HIDIOCSFEATURE(len: u16) u32 { const request: linux.IOCTL.Request = .{ .io_type = 'H', .nr = 0x06, .dir = read | write, .size = @intCast(@min(len, max_len)), }; return @bitCast(request);}
/// This ioctl will request a feature report from the device using the control/// endpoint. The first byte of the supplied buffer should be set to the report/// number of the requested report. For devices which do not use numbered/// reports, set the first byte to 0. The returned report buffer will contain/// the report number in the first byte, followed by the report data read from/// the device. For devices which do not use numbered reports, the report data/// will begin at the first byte of the returned buffer.pub fn HIDIOCGFEATURE(len: u16) u32 { const request: linux.IOCTL.Request = .{ .io_type = 'H', .nr = 0x07, .dir = read | write, .size = @intCast(@min(len, max_len)), }; return @bitCast(request);}
/// This ioctl returns the kernel's `uniq` string for the device, which usbhid/// fills in from the device's serial number and the Bluetooth transport fills/// in with the hardware (MAC) address. Devices that report neither leave it/// empty.////// Unlike the comments above, this one is not the kernel's own text: the/// hidraw documentation does not cover this request.pub fn HIDIOCGRAWUNIQ(len: u16) u32 { const request: linux.IOCTL.Request = .{ .io_type = 'H', .nr = 0x08, .dir = read, .size = @intCast(@min(len, max_len)), }; return @bitCast(request);}
/// This ioctl will send an input report to the device, using the control/// endpoint. In most cases, setting an input HID report on a device is/// meaningless and has no effect, but some devices may choose to use this to/// set or reset an initial state of a report. The format of the buffer issued/// with this report is identical to that of HIDIOCSFEATURE.pub fn HIDIOCSINPUT(len: u16) u32 { const request: linux.IOCTL.Request = .{ .io_type = 'H', .nr = 0x09, .dir = read | write, .size = @intCast(@min(len, max_len)), }; return @bitCast(request);}
/// This ioctl will request an input report from the device using the control/// endpoint. This is slower on most devices where a dedicated In endpoint/// exists for regular input reports, but allows the host to request the value/// of a specific report number. Typically, this is used to request the initial/// states of an input report of a device, before an application listens for/// normal reports via the regular device read() interface. The format of the/// buffer issued with this report is identical to that of HIDIOCGFEATURE.pub fn HIDIOCGINPUT(len: u16) u32 { const request: linux.IOCTL.Request = .{ .io_type = 'H', .nr = 0x0A, .dir = read | write, .size = @intCast(@min(len, max_len)), }; return @bitCast(request);}
/// This ioctl will send an output report to the device, using the control/// endpoint. This is slower on most devices where a dedicated Out endpoint/// exists for regular output reports, but is added for completeness. Typically,/// this is used to set the initial states of an output report of a device,/// before an application sends updates via the regular device write()/// interface. The format of the buffer issued with this report is identical to/// that of HIDIOCSFEATURE.pub fn HIDIOCSOUTPUT(len: u16) u32 { const request: linux.IOCTL.Request = .{ .io_type = 'H', .nr = 0x0B, .dir = read | write, .size = @intCast(@min(len, max_len)), }; return @bitCast(request);}
/// This ioctl will request an output report from the device using the control/// endpoint. Typically, this is used to retrieve the initial state of an/// output report of a device, before an application updates it as necessary/// either via a HIDIOCSOUTPUT request, or the regular device write() interface./// The format of the buffer issued with this report is identical to that of/// HIDIOCGFEATURE.pub fn HIDIOCGOUTPUT(len: u16) u32 { const request: linux.IOCTL.Request = .{ .io_type = 'H', .nr = 0x0C, .dir = read | write, .size = @intCast(@min(len, max_len)), }; return @bitCast(request);}
test { std.testing.refAllDecls(@This());}