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 July 1, 2018 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 HID_GET_REPORT_ID Pq Vt int 69Get the report identifier used by this HID report. 70.It Dv HID_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 HID_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 HID_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 HID_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.El 151.Pp 152Linux 153.Nm 154\-compatible calls: 155.Bl -tag -width indent 156.It Dv HIDIOCGRDESCSIZE Pq Vt int 157Get the HID report descriptor size. 158Returns the size of the device report descriptor to use with 159.Dv HIDIOCGRDESC 160.Xr ioctl 2 . 161.It Dv HIDIOCGRDESC Pq Vt "struct hidraw_report_descriptor" 162Get the HID report descriptor. 163Copies a maximum of 164.Va size 165bytes of the report descriptor data into the memory 166specified by 167.Va value . 168.Bd -literal 169struct hidraw_report_descriptor { 170 uint32_t size; 171 uint8_t value[HID_MAX_DESCRIPTOR_SIZE]; 172}; 173.Ed 174.It Dv HIDIOCGRAWINFO Pq Vt "struct hidraw_devinfo" 175Get structure containing the bus type, the vendor ID (VID), and product ID 176(PID) of the device. 177The bus type can be one of: 178.Dv BUS_USB 179or 180.Dv BUS_I2C 181which are defined in dev/evdev/input.h. 182.Bd -literal 183struct hidraw_devinfo { 184 uint32_t bustype; 185 int16_t vendor; 186 int16_t product; 187}; 188.Ed 189.It Dv HIDIOCGRAWNAME(len) Pq Vt "char[] buf" 190Get device description. 191Copies a maximum of 192.Va len 193bytes of the device description previously set with 194.Xr device_set_desc 9 195procedure into the memory 196specified by 197.Va buf . 198.It Dv HIDIOCGRAWPHYS(len) Pq Vt "char[] buf" 199Get the newbus path to the device. 200.\For Bluetooth devices, it returns the hardware (MAC) address of the device. 201Copies a maximum of 202.Va len 203bytes of the newbus device path 204into the memory 205specified by 206.Va buf . 207.It Dv HIDIOCGFEATURE(len) Pq Vt "void[] buf" 208Get a feature report from the device. 209Copies a maximum of 210.Va len 211bytes of the feature report data into the memory specified by 212.Va buf . 213The first byte of the supplied buffer should be set to the report 214number of the requested report. 215For devices which do not use numbered reports, set the first byte to 0. 216The report will be returned starting at the first byte of the buffer 217(ie: the report number is not returned). 218This call may fail if the device does not support this feature. 219.It Dv HIDIOCSFEATURE(len) Pq Vt "void[] buf" 220Set a feature Report in the device. 221The value of the report is specified by the 222.Va buf 223and the 224.Va len 225parameters. 226Set the first byte of the supplied buffer to the report number. 227For devices which do not use numbered reports, set the first byte to 0. 228The report data begins in the second byte. 229Make sure to set len accordingly, to one more than the length of the report 230(to account for the report number). 231This call may fail if the device does not support this feature. 232.El 233.Pp 234Use 235.Xr read 2 236to get data from the device. 237Data should be read in chunks of the 238size prescribed by the report descriptor. 239On a device which uses numbered reports, the first byte of the returned data 240is the report number. 241The report data begins from the second byte. 242For devices which do not use numbered reports, the report data begins at the 243first byte. 244.Pp 245Use 246.Xr write 2 247to send data to the device. 248Data should be written in chunks of the 249size prescribed by the report descriptor. 250The first byte of the buffer passed to 251.Xr write 2 252should be set to the report number. 253If the device does not use numbered reports, there are 2 operation modes: 254.Nm 255mode and 256.Xr uhid 4 257mode. 258In the 259.Nm 260mode, the first byte should be set to 0 and the report data itself should 261begin at the second byte. 262In the 263.Xr uhid 4 264mode, the report data should begin at the first byte. 265The modes can be switched with issuing one of 266.Dv HIDIOCGRDESC 267or 268.Dv HID_GET_REPORT_DESC 269.Xr ioctl 2 270accordingly. 271Default mode is 272.Nm . 273.Sh SYSCTL VARIABLES 274The following variables are available as both 275.Xr sysctl 8 276variables and 277.Xr loader 8 278tunables: 279.Bl -tag -width indent 280.It Va hw.hid.hidraw.debug 281Debug output level, where 0 is debugging disabled and larger values increase 282debug message verbosity. 283Default is 0. 284.El 285.Sh FILES 286.Bl -tag -width ".Pa /dev/hidraw?" 287.It Pa /dev/hidraw? 288.El 289.Sh SEE ALSO 290.Xr usbhidctl 1 , 291.Xr hid 4 , 292.Xr hidbus 4 , 293.Xr uhid 4 294.Sh HISTORY 295The 296.Xr uhid 4 297driver 298appeared in 299.Nx 1.4 . 300.Nm 301protocol support was added in 302.Fx 13 303by 304.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . 305This manual page was adopted from 306.Nx 307by 308.An Tom Rhodes Aq Mt trhodes@FreeBSD.org 309in April 2002. 310