share/man/man4/hidraw.4

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