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.\" $FreeBSD$ 31.\" 32.Dd August 6, 2023 33.Dt HIDRAW 4 34.Os 35.Sh NAME 36.Nm hidraw 37.Nd Raw Access to HID devices 38.Sh SYNOPSIS 39To compile this driver into the kernel, 40place the following line in your 41kernel configuration file: 42.Bd -ragged -offset indent 43.Cd "device hidraw" 44.Cd "device hid" 45.Cd "device hidbus" 46.Ed 47.Pp 48Alternatively, to load the driver as a 49module at boot time, place the following line in 50.Xr loader.conf 5 : 51.Bd -literal -offset indent 52hidraw_load="YES" 53.Ed 54.Sh DESCRIPTION 55The 56.Nm 57driver provides a raw interface to Human Interface Devices (HIDs). 58The reports are sent to and received from the device unmodified. 59.Pp 60The device handles 2 sets of 61.Xr ioctl 2 62calls: 63.Pp 64.Fx 65.Xr uhid 4 66\-compatible calls: 67.Bl -tag -width indent 68.It Dv HIDRAW_GET_REPORT_ID Pq Vt int 69Get the report identifier used by this HID report. 70.It Dv HIDRAW_GET_REPORT_DESC Pq Vt "struct hidraw_gen_descriptor" 71Get the HID report descriptor. 72Copies a maximum of 73.Va hgd_maxlen 74bytes of the report descriptor data into the memory 75specified by 76.Va hgd_data . 77Upon return 78.Va hgd_actlen 79is set to the number of bytes copied. 80Using 81this descriptor the exact layout and meaning of data to/from 82the device can be found. 83The report descriptor is delivered 84without any processing. 85.Bd -literal 86struct hidraw_gen_descriptor { 87 void *hgd_data; 88 uint16_t hgd_maxlen; 89 uint16_t hgd_actlen; 90 uint8_t hgd_report_type; 91 ... 92}; 93.Ed 94.It Dv HIDRAW_SET_IMMED Pq Vt int 95Sets the device in a mode where each 96.Xr read 2 97will return the current value of the input report. 98Normally 99a 100.Xr read 2 101will only return the data that the device reports on its 102interrupt pipe. 103This call may fail if the device does not support 104this feature. 105.It Dv HIDRAW_GET_REPORT Pq Vt "struct hidraw_gen_descriptor" 106Get a report from the device without waiting for data on 107the interrupt pipe. 108Copies a maximum of 109.Va hgd_maxlen 110bytes of the report data into the memory specified by 111.Va hgd_data . 112Upon return 113.Va hgd_actlen 114is set to the number of bytes copied. 115The 116.Va hgd_report_type 117field indicates which report is requested. 118It should be 119.Dv HID_INPUT_REPORT , 120.Dv HID_OUTPUT_REPORT , 121or 122.Dv HID_FEATURE_REPORT . 123On a device which uses numbered reports, the first byte of the returned data 124is the report number. 125The report data begins from the second byte. 126For devices which do not use numbered reports, the report data begins at the 127first byte. 128This call may fail if the device does not support this feature. 129.It Dv HIDRAW_SET_REPORT Pq Vt "struct hidraw_gen_descriptor" 130Set a report in the device. 131The 132.Va hgd_report_type 133field indicates which report is to be set. 134It should be 135.Dv HID_INPUT_REPORT , 136.Dv HID_OUTPUT_REPORT , 137or 138.Dv HID_FEATURE_REPORT . 139The value of the report is specified by the 140.Va hgd_data 141and the 142.Va hgd_maxlen 143fields. 144On a device which uses numbered reports, the first byte of data to be sent is 145the report number. 146The report data begins from the second byte. 147For devices which do not use numbered reports, the report data begins at the 148first byte. 149This call may fail if the device does not support this feature. 150.It Dv HIDRAW_GET_DEVICEINFO Pq Vt "struct hidraw_device_info" 151Returns information about the device, like vendor ID and product ID. 152This call will not issue any hardware transfers. 153.El 154.Pp 155Linux 156.Nm 157\-compatible calls: 158.Bl -tag -width indent 159.It Dv HIDIOCGRDESCSIZE Pq Vt int 160Get the HID report descriptor size. 161Returns the size of the device report descriptor to use with 162.Dv HIDIOCGRDESC 163.Xr ioctl 2 . 164.It Dv HIDIOCGRDESC Pq Vt "struct hidraw_report_descriptor" 165Get the HID report descriptor. 166Copies a maximum of 167.Va size 168bytes of the report descriptor data into the memory 169specified by 170.Va value . 171.Bd -literal 172struct hidraw_report_descriptor { 173 uint32_t size; 174 uint8_t value[HID_MAX_DESCRIPTOR_SIZE]; 175}; 176.Ed 177.It Dv HIDIOCGRAWINFO Pq Vt "struct hidraw_devinfo" 178Get structure containing the bus type, the vendor ID (VID), and product ID 179(PID) of the device. 180The bus type can be one of: 181.Dv BUS_USB 182or 183.Dv BUS_I2C 184which are defined in dev/evdev/input.h. 185.Bd -literal 186struct hidraw_devinfo { 187 uint32_t bustype; 188 int16_t vendor; 189 int16_t product; 190}; 191.Ed 192.It Dv HIDIOCGRAWNAME(len) Pq Vt "char[] buf" 193Get device description. 194Copies a maximum of 195.Va len 196bytes of the device description previously set with 197.Xr device_set_desc 9 198procedure into the memory 199specified by 200.Va buf . 201.It Dv HIDIOCGRAWPHYS(len) Pq Vt "char[] buf" 202Get the newbus path to the device. 203.\For Bluetooth devices, it returns the hardware (MAC) address of the device. 204Copies a maximum of 205.Va len 206bytes of the newbus device path 207into the memory 208specified by 209.Va buf . 210.It Dv HIDIOCGFEATURE(len) Pq Vt "void[] buf" 211Get a feature report from the device. 212Copies a maximum of 213.Va len 214bytes of the feature 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" 223Set a feature Report in the device. 224The value of the report is specified by the 225.Va buf 226and the 227.Va len 228parameters. 229Set the first byte of the supplied buffer to the report number. 230For devices which do not use numbered reports, set the first byte to 0. 231The report data begins in the second byte. 232Make sure to set len accordingly, to one more than the length of the report 233(to account for the report number). 234This call may fail if the device does not support this feature. 235.El 236.Pp 237Use 238.Xr read 2 239to get data from the device. 240Data should be read in chunks of the 241size prescribed by the report descriptor. 242On a device which uses numbered reports, the first byte of the returned data 243is the report number. 244The report data begins from the second byte. 245For devices which do not use numbered reports, the report data begins at the 246first byte. 247.Pp 248Use 249.Xr write 2 250to send data to the device. 251Data should be written in chunks of the 252size prescribed by the report descriptor. 253The first byte of the buffer passed to 254.Xr write 2 255should be set to the report number. 256If the device does not use numbered reports, there are 2 operation modes: 257.Nm 258mode and 259.Xr uhid 4 260mode. 261In the 262.Nm 263mode, the first byte should be set to 0 and the report data itself should 264begin at the second byte. 265In the 266.Xr uhid 4 267mode, the report data should begin at the first byte. 268The modes can be switched with issuing one of 269.Dv HIDIOCGRDESC 270or 271.Dv HID_GET_REPORT_DESC 272.Xr ioctl 2 273accordingly. 274Default mode is 275.Nm . 276.Sh SYSCTL VARIABLES 277The following variables are available as both 278.Xr sysctl 8 279variables and 280.Xr loader 8 281tunables: 282.Bl -tag -width indent 283.It Va hw.hid.hidraw.debug 284Debug output level, where 0 is debugging disabled and larger values increase 285debug message verbosity. 286Default is 0. 287.El 288.Sh FILES 289.Bl -tag -width ".Pa /dev/hidraw?" 290.It Pa /dev/hidraw? 291.El 292.Sh SEE ALSO 293.Xr usbhidctl 1 , 294.Xr hid 4 , 295.Xr hidbus 4 , 296.Xr uhid 4 297.Sh HISTORY 298The 299.Xr uhid 4 300driver 301appeared in 302.Nx 1.4 . 303.Nm 304protocol support was added in 305.Fx 13 306by 307.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . 308This manual page was adopted from 309.Nx 310by 311.An Tom Rhodes Aq Mt trhodes@FreeBSD.org 312in April 2002. 313