1.\" $NetBSD: uhid.4,v 1.13 2001/12/29 14:41:59 augustss Exp $ 2.\" 3.\" Copyright (c) 1999, 2001 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Lennart Augustsson. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd April 27, 2025 31.Dt HIDRAW 4 32.Os 33.Sh NAME 34.Nm hidraw 35.Nd Raw Access to HID devices 36.Sh SYNOPSIS 37To compile this driver into the kernel, 38place the following line in your 39kernel configuration file: 40.Bd -ragged -offset indent 41.Cd "device hidraw" 42.Cd "device hid" 43.Cd "device hidbus" 44.Ed 45.Pp 46Alternatively, to load the driver as a 47module at boot time, place the following line in 48.Xr loader.conf 5 : 49.Bd -literal -offset indent 50hidraw_load="YES" 51.Ed 52.Sh DESCRIPTION 53The 54.Nm 55driver provides a raw interface to Human Interface Devices (HIDs). 56The reports are sent to and received from the device unmodified. 57.Pp 58The device handles 2 sets of 59.Xr ioctl 2 60calls: 61.Pp 62.Fx 63.Xr uhid 4 64\-compatible calls: 65.Bl -tag -width indent 66.It Dv HIDRAW_GET_REPORT_ID Pq Vt int 67Get the report identifier used by this HID report. 68.It Dv HIDRAW_GET_REPORT_DESC Pq Vt "struct hidraw_gen_descriptor" 69Get the HID report descriptor. 70Copies a maximum of 71.Va hgd_maxlen 72bytes of the report descriptor data into the memory 73specified by 74.Va hgd_data . 75Upon return 76.Va hgd_actlen 77is set to the number of bytes copied. 78Using 79this descriptor the exact layout and meaning of data to/from 80the device can be found. 81The report descriptor is delivered 82without any processing. 83.Bd -literal 84struct hidraw_gen_descriptor { 85 void *hgd_data; 86 uint16_t hgd_maxlen; 87 uint16_t hgd_actlen; 88 uint8_t hgd_report_type; 89 ... 90}; 91.Ed 92.It Dv HIDRAW_SET_IMMED Pq Vt int 93Sets the device in a mode where each 94.Xr read 2 95will return the current value of the input report. 96Normally 97a 98.Xr read 2 99will only return the data that the device reports on its 100interrupt pipe. 101This call may fail if the device does not support 102this feature. 103.It Dv HIDRAW_GET_REPORT Pq Vt "struct hidraw_gen_descriptor" 104Get a report from the device without waiting for data on 105the interrupt pipe. 106Copies a maximum of 107.Va hgd_maxlen 108bytes of the report data into the memory specified by 109.Va hgd_data . 110Upon return 111.Va hgd_actlen 112is set to the number of bytes copied. 113The 114.Va hgd_report_type 115field indicates which report is requested. 116It should be 117.Dv HID_INPUT_REPORT , 118.Dv HID_OUTPUT_REPORT , 119or 120.Dv HID_FEATURE_REPORT . 121On a device which uses numbered reports, the first byte of the returned data 122is the report number. 123The report data begins from the second byte. 124For devices which do not use numbered reports, the report data begins at the 125first byte. 126This call may fail if the device does not support this feature. 127.It Dv HIDRAW_SET_REPORT Pq Vt "struct hidraw_gen_descriptor" 128Set a report in the device. 129The 130.Va hgd_report_type 131field indicates which report is to be set. 132It should be 133.Dv HID_INPUT_REPORT , 134.Dv HID_OUTPUT_REPORT , 135or 136.Dv HID_FEATURE_REPORT . 137The value of the report is specified by the 138.Va hgd_data 139and the 140.Va hgd_maxlen 141fields. 142On a device which uses numbered reports, the first byte of data to be sent is 143the report number. 144The report data begins from the second byte. 145For devices which do not use numbered reports, the report data begins at the 146first byte. 147This call may fail if the device does not support this feature. 148.It Dv HIDRAW_GET_DEVICEINFO Pq Vt "struct hidraw_device_info" 149Returns information about the device, like vendor ID and product ID. 150This call will not issue any hardware transfers. 151.El 152.Pp 153Linux 154.Nm 155\-compatible calls: 156.Bl -tag -width indent 157.It Dv HIDIOCGRDESCSIZE Pq Vt int 158Get the HID report descriptor size. 159Returns the size of the device report descriptor to use with 160.Dv HIDIOCGRDESC 161.Xr ioctl 2 . 162.It Dv HIDIOCGRDESC Pq Vt "struct hidraw_report_descriptor" 163Get the HID report descriptor. 164Copies a maximum of 165.Va size 166bytes of the report descriptor data into the memory 167specified by 168.Va value . 169.Bd -literal 170struct hidraw_report_descriptor { 171 uint32_t size; 172 uint8_t value[HID_MAX_DESCRIPTOR_SIZE]; 173}; 174.Ed 175.It Dv HIDIOCGRAWINFO Pq Vt "struct hidraw_devinfo" 176Get structure containing the bus type, the vendor ID (VID), and product ID 177(PID) of the device. 178The bus type can be one of: 179.Dv BUS_USB 180or 181.Dv BUS_I2C 182which are defined in dev/evdev/input.h. 183.Bd -literal 184struct hidraw_devinfo { 185 uint32_t bustype; 186 int16_t vendor; 187 int16_t product; 188}; 189.Ed 190.It Dv HIDIOCGRAWNAME(len) Pq Vt "char[] buf" 191Get device description. 192Copies a maximum of 193.Va len 194bytes of the device description previously set with 195.Xr device_set_desc 9 196procedure into the memory 197specified by 198.Va buf . 199.It Dv HIDIOCGRAWPHYS(len) Pq Vt "char[] buf" 200Get the newbus path to the device. 201.\"For Bluetooth devices, it returns the hardware (MAC) address of the device. 202Copies a maximum of 203.Va len 204bytes of the newbus device path 205into the memory 206specified by 207.Va buf . 208.It Dv HIDIOCGFEATURE(len) Pq Vt "void[] buf" 209.It Dv HIDIOCGINPUT(len) Pq Vt "void[] buf" 210.It Dv HIDIOCGOUTPUT(len) Pq Vt "void[] buf" 211Get respectively a feature, input or output report from the device. 212Copies a maximum of 213.Va len 214bytes of the report data into the memory specified by 215.Va buf . 216The first byte of the supplied buffer should be set to the report 217number of the requested report. 218For devices which do not use numbered reports, set the first byte to 0. 219The report will be returned starting at the first byte of the buffer 220(ie: the report number is not returned). 221This call may fail if the device does not support this feature. 222.It Dv HIDIOCSFEATURE(len) Pq Vt "void[] buf" 223.It Dv HIDIOCSINPUT(len) Pq Vt "void[] buf" 224.It Dv HIDIOCSOUTPUT(len) Pq Vt "void[] buf" 225Set respectively a feature, input or output Report in the device. 226The value of the report is specified by the 227.Va buf 228and the 229.Va len 230parameters. 231Set the first byte of the supplied buffer to the report number. 232For devices which do not use numbered reports, set the first byte to 0. 233The report data begins in the second byte. 234Make sure to set len accordingly, to one more than the length of the report 235(to account for the report number). 236This call may fail if the device does not support this feature. 237.El 238.Pp 239Use 240.Xr read 2 241to get data from the device. 242Data should be read in chunks of the 243size prescribed by the report descriptor. 244On a device which uses numbered reports, the first byte of the returned data 245is the report number. 246The report data begins from the second byte. 247For devices which do not use numbered reports, the report data begins at the 248first byte. 249.Pp 250Use 251.Xr write 2 252to send data to the device. 253Data should be written in chunks of the 254size prescribed by the report descriptor. 255The first byte of the buffer passed to 256.Xr write 2 257should be set to the report number. 258If the device does not use numbered reports, there are 2 operation modes: 259.Nm 260mode and 261.Xr uhid 4 262mode. 263In the 264.Nm 265mode, the first byte should be set to 0 and the report data itself should 266begin at the second byte. 267In the 268.Xr uhid 4 269mode, the report data should begin at the first byte. 270The modes can be switched with issuing one of 271.Dv HIDIOCGRDESC 272or 273.Dv HID_GET_REPORT_DESC 274.Xr ioctl 2 275accordingly. 276Default mode is 277.Nm . 278.Sh SYSCTL VARIABLES 279The following variables are available as both 280.Xr sysctl 8 281variables and 282.Xr loader 8 283tunables: 284.Bl -tag -width indent 285.It Va hw.hid.hidraw.debug 286Debug output level, where 0 is debugging disabled and larger values increase 287debug message verbosity. 288Default is 0. 289.El 290.Sh FILES 291.Bl -tag -width ".Pa /dev/hidraw?" 292.It Pa /dev/hidraw? 293.El 294.Sh SEE ALSO 295.Xr usbhidctl 1 , 296.Xr hid 4 , 297.Xr hidbus 4 , 298.Xr uhid 4 299.Sh HISTORY 300The 301.Xr uhid 4 302driver 303appeared in 304.Nx 1.4 . 305.Nm 306protocol support was added in 307.Fx 13 308by 309.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . 310This manual page was adopted from 311.Nx 312by 313.An Tom Rhodes Aq Mt trhodes@FreeBSD.org 314in April 2002. 315