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