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 August 6, 2023 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" 209Get a feature report from the device. 210Copies a maximum of 211.Va len 212bytes of the feature report data into the memory specified by 213.Va buf . 214The first byte of the supplied buffer should be set to the report 215number of the requested report. 216For devices which do not use numbered reports, set the first byte to 0. 217The report will be returned starting at the first byte of the buffer 218(ie: the report number is not returned). 219This call may fail if the device does not support this feature. 220.It Dv HIDIOCSFEATURE(len) Pq Vt "void[] buf" 221Set a feature Report in the device. 222The value of the report is specified by the 223.Va buf 224and the 225.Va len 226parameters. 227Set the first byte of the supplied buffer to the report number. 228For devices which do not use numbered reports, set the first byte to 0. 229The report data begins in the second byte. 230Make sure to set len accordingly, to one more than the length of the report 231(to account for the report number). 232This call may fail if the device does not support this feature. 233.El 234.Pp 235Use 236.Xr read 2 237to get data from the device. 238Data should be read in chunks of the 239size prescribed by the report descriptor. 240On a device which uses numbered reports, the first byte of the returned data 241is the report number. 242The report data begins from the second byte. 243For devices which do not use numbered reports, the report data begins at the 244first byte. 245.Pp 246Use 247.Xr write 2 248to send data to the device. 249Data should be written in chunks of the 250size prescribed by the report descriptor. 251The first byte of the buffer passed to 252.Xr write 2 253should be set to the report number. 254If the device does not use numbered reports, there are 2 operation modes: 255.Nm 256mode and 257.Xr uhid 4 258mode. 259In the 260.Nm 261mode, the first byte should be set to 0 and the report data itself should 262begin at the second byte. 263In the 264.Xr uhid 4 265mode, the report data should begin at the first byte. 266The modes can be switched with issuing one of 267.Dv HIDIOCGRDESC 268or 269.Dv HID_GET_REPORT_DESC 270.Xr ioctl 2 271accordingly. 272Default mode is 273.Nm . 274.Sh SYSCTL VARIABLES 275The following variables are available as both 276.Xr sysctl 8 277variables and 278.Xr loader 8 279tunables: 280.Bl -tag -width indent 281.It Va hw.hid.hidraw.debug 282Debug output level, where 0 is debugging disabled and larger values increase 283debug message verbosity. 284Default is 0. 285.El 286.Sh FILES 287.Bl -tag -width ".Pa /dev/hidraw?" 288.It Pa /dev/hidraw? 289.El 290.Sh SEE ALSO 291.Xr usbhidctl 1 , 292.Xr hid 4 , 293.Xr hidbus 4 , 294.Xr uhid 4 295.Sh HISTORY 296The 297.Xr uhid 4 298driver 299appeared in 300.Nx 1.4 . 301.Nm 302protocol support was added in 303.Fx 13 304by 305.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . 306This manual page was adopted from 307.Nx 308by 309.An Tom Rhodes Aq Mt trhodes@FreeBSD.org 310in April 2002. 311