usr/src/man/man7d/hid.7d

   1 '\" te
   2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   4 .\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
   5 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH HID 7D "Aug 21, 2009"
   7 .SH NAME
   8 hid \- Human interface device (HID) class driver
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBkeyboard@unit-address\fR
  13 \fBmouse@unit-address\fR
  14 \fBinput@unit-address:consumer_control\fR
  15 \fB#include <sys/hid.h>\fR
  16 \fBint ioctl(int fildes, int command, ... /*arg*/);\fR
  17 .fi
  18
  19 .SH DESCRIPTION
  20 .sp
  21 .LP
  22 The \fBhid\fR driver is a USBA (Solaris USB Architecture) compliant client
  23 driver that supports the \fIHuman Interface Device Class (HID) 1.0\fR
  24 specification. The Human Interface Device (HID) class encompasses devices
  25 controlled by humans to operate computer systems. Typical examples of HID
  26 devices include keyboards, mice, trackballs, and joysticks. HID also covers
  27 front-panel controls such as knobs, switches, and buttons. A USB device with
  28 multiple interfaces may have one interface for audio and a HID interface to
  29 define the buttons that control the audio.
  30 .sp
  31 .LP
  32 The \fBhid\fR driver is general and primarily handles the USB functionality of
  33 the device and generic HID functionality. For example, HID interfaces are
  34 required to have an interrupt pipe for the device to send data packets, and the
  35 \fBhid\fR driver opens the pipe to the interrupt endpoint and starts polling.
  36 The \fBhid\fR driver is also responsible for managing the device through the
  37 default control pipe. In addition to being a USB client driver, the \fBhid\fR
  38 driver is also a STREAMS driver so that modules may be pushed on top of it.
  39 .sp
  40 .LP
  41 The HID specification is flexible, and HID devices dynamically describe their
  42 packets and other parameters through a HID report descriptor. The HID parser is
  43 a misc module that parses the HID report descriptor and creates a database of
  44 information about the device. The \fBhid\fR driver queries the HID parser to
  45 find out the type and characteristics of the HID device. The HID specification
  46 predefines packet formats for the boot protocol keyboard and mouse.
  47 .SH IOCTLS
  48 .sp
  49 .ne 2
  50 .na
  51 \fB\fBHIDIOCKMGDIRECT\fR\fR
  52 .ad
  53 .RS 19n
  54 This ioctl should only be addressed to a USB keyboard or mouse device. The
  55 \fBhid\fR driver maintains two streams for each USB keyboard/mouse instance: an
  56 internal one for the use of the kernel and an external one for the use of user
  57 applications. This ioctl returns the information of which stream gets the input
  58 for the moment.
  59 .sp
  60 \fIarg\fR must point to a variable of \fBint\fR type. Upon return, \fB0\fR
  61 means the internal stream gets the input, \fB1\fR means the external stream
  62 gets the input.
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fBHIDIOCKMSDIRECT\fR\fR
  69 .ad
  70 .RS 19n
  71 This ioctl should only be addressed to a USB keyboard or mouse device. The hid
  72 driver maintains two streams for each USB keyboard/mouse instance: an internal
  73 one for the use of the kernel and an external one for the use of user
  74 applications. This ioctl sets which stream should get the input for the moment.
  75 .sp
  76 \fIarg\fR must point to a variable of \fBint\fR type. The argument \fB0\fR
  77 means the internal stream gets the input, \fB1\fR means the external stream
  78 gets the input.
  79 .RE
  80
  81 .SH FILES
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fB/kernel/drv/hid\fR\fR
  86 .ad
  87 .sp .6
  88 .RS 4n
  89 32-bit x86 ELF kernel hid module
  90 .RE
  91
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fB/kernel/drv/amd64/hid\fR\fR
  96 .ad
  97 .sp .6
  98 .RS 4n
  99 64-bit x86 ELF kernel hid module
 100 .RE
 101
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fB/kernel/drv/sparcv9/hid\fR\fR
 106 .ad
 107 .sp .6
 108 .RS 4n
 109 64-bit SPARC ELF kernel hid module
 110 .RE
 111
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fB/kernel/misc/hidparser\fR\fR
 116 .ad
 117 .sp .6
 118 .RS 4n
 119 32-bit x86 ELF kernel hidparser module
 120 .RE
 121
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fB/kernel/misc/amd64/hidparser\fR\fR
 126 .ad
 127 .sp .6
 128 .RS 4n
 129 64-bit x86 ELF kernel hidparser module
 130 .RE
 131
 132 .sp
 133 .ne 2
 134 .na
 135 \fB\fB/kernel/misc/sparcv9/hidparser\fR\fR
 136 .ad
 137 .sp .6
 138 .RS 4n
 139 64-bit SPARC ELF kernel hidparser module
 140 .RE
 141
 142 .SH ATTRIBUTES
 143 .sp
 144 .LP
 145 See \fBattributes\fR(5) for descriptions of the following attributes:
 146 .sp
 147
 148 .sp
 149 .TS
 150 box;
 151 c | c
 152 l | l .
 153 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 154 _
 155 Architecture    SPARC, x86, PCI-based systems
 156 .TE
 157
 158 .SH SEE ALSO
 159 .sp
 160 .LP
 161 \fBcfgadm_usb\fR(1M), \fBattributes\fR(5), \fBusba\fR(7D), \fBvirtualkm\fR(7D)
 162 .sp
 163 .LP
 164 \fIWriting Device Drivers\fR
 165 .sp
 166 .LP
 167 \fISTREAMS Programming Guide\fR
 168 .sp
 169 .LP
 170 \fIUniversal Serial Bus Specification 1.0 and 1.1\fR
 171 .sp
 172 .LP
 173 \fIDevice Class Definition for Human Interface Devices (HID) 1.1\fR
 174 .sp
 175 .LP
 176 \fISystem Administration Guide: Basic Administration\fR
 177 .sp
 178 .LP
 179 \fIhttp://www.sun.com\fR
 180 .SH DIAGNOSTICS
 181 .sp
 182 .ne 2
 183 .na
 184 \fBhid_attach: Unsupported HID device.\fR
 185 .ad
 186 .sp .6
 187 .RS 4n
 188 The device requires a protocol not supported by the hid driver.
 189 .RE
 190
 191 .sp
 192 .ne 2
 193 .na
 194 \fBParsing of hid descriptor failed.\fR
 195 .ad
 196 .sp .6
 197 .RS 4n
 198 The HID report descriptor cannot be parsed correctly. The device cannot be
 199 supported by the hid driver.
 200 .RE
 201
 202 .sp
 203 .ne 2
 204 .na
 205 \fBInvalid report descriptor.\fR
 206 .ad
 207 .sp .6
 208 .RS 4n
 209 The HID report descriptor is invalid. The device cannot be supported by the hid
 210 driver.
 211 .RE
 212
 213 .sp
 214 .LP
 215 The following messages may be logged into the system log. They are formatted in
 216 the following manner:
 217 .sp
 218 .in +2
 219 .nf
 220 <device path><hid<instance number>): message...
 221 .fi
 222 .in -2
 223 .sp
 224
 225 .sp
 226 .ne 2
 227 .na
 228 \fBhid_attach: Unsupported HID device.\fR
 229 .ad
 230 .sp .6
 231 .RS 4n
 232 The device cannot be supported by this version of the HID driver.
 233 .RE
 234
 235 .sp
 236 .ne 2
 237 .na
 238 \fBParsing of HID descriptor failed.\fR
 239 .ad
 240 .sp .6
 241 .RS 4n
 242 The device cannot be supported by this version of the HID driver.
 243 .RE
 244
 245 .sp
 246 .ne 2
 247 .na
 248 \fBInvalid report descriptor.\fR
 249 .ad
 250 .sp .6
 251 .RS 4n
 252 The device cannot be supported by this version of the HID driver.
 253 .RE
 254
 255 .SH NOTES
 256 .sp
 257 .LP
 258 The hid driver currently supports only keyboard, mouse and audio HID control
 259 devices.
 260 .sp
 261 .LP
 262 Normally a mouse is not power managed and consquently, screen darkening can be
 263 undone with a mouse movement. If power management of the mouse is required, add
 264 the following line to \fBhid.conf\fR then reboot the system:
 265 .sp
 266 .in +2
 267 .nf
 268 hid-mouse-pm-enable;
 269 .fi
 270 .in -2
 271
 272 .sp
 273 .LP
 274 Modern mice that are power managed require a 'click' to wake up. Occasionally,
 275 this may cause unexpected results.