share/man/man4/uhid.4

   1 .\" $NetBSD: uhid.4,v 1.19 2005/11/23 08:56:08 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 .Dd November 22, 2005
  31 .Dt UHID 4
  32 .Os
  33 .Sh NAME
  34 .Nm uhid
  35 .Nd USB generic HID support
  36 .Sh SYNOPSIS
  37 .Cd "uhid* at uhidev? reportid ? flags N"
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 driver provides support for all HID (Human Interface Device) interfaces
  42 in USB devices that do not have a special driver.
  43 .Pp
  44 Normally the
  45 .Nm
  46 driver is used when no other HID driver attaches to a device.
  47 If
  48 .Dq flags 1
  49 is specified, the
  50 .Nm
  51 driver will instead attach with a very high priority and always be used.
  52 Together with the
  53 .Cd vendor
  54 and
  55 .Cd product
  56 locators on the
  57 .Xr uhidev 4
  58 driver this can be used to force the
  59 .Nm
  60 driver to be used for a certain device.
  61 .Pp
  62 The device handles the following
  63 .Xr ioctl 2
  64 calls:
  65 .Pp
  66 .Bl -tag -width indent
  67 .It Dv USB_GET_REPORT_ID (int)
  68 Get the report identifier used by this HID report.
  69 .It Dv USB_GET_REPORT_DESC (struct usb_ctl_report_desc)
  70 Get the HID report descriptor.
  71 Using this descriptor the exact layout and meaning of data to/from
  72 the device can be found.
  73 The report descriptor is delivered without any processing.
  74 .Bd -literal
  75 struct usb_ctl_report_desc {
  76     int     ucrd_size;
  77     u_char  ucrd_data[1024];    /* filled data size will vary */
  78 };
  79 .Ed
  80 .It Dv USB_SET_IMMED (int)
  81 Sets the device in a mode where each
  82 .Xr read 2
  83 will return the current value of the input report.
  84 Normally a
  85 .Xr read 2
  86 will only return the data that the device reports on its
  87 interrupt pipe.
  88 This call may fail if the device does not support this feature.
  89 .It Dv USB_GET_REPORT (struct usb_ctl_report)
  90 Get a report from the device without waiting for data on
  91 the interrupt pipe.
  92 The
  93 .Dv report
  94 field indicates which report is requested.
  95 It should be
  96 .Dv UHID_INPUT_REPORT ,
  97 .Dv UHID_OUTPUT_REPORT ,
  98 or
  99 .Dv UHID_FEATURE_REPORT .
 100 This call may fail if the device does not support this feature.
 101 .Bd -literal
 102 struct usb_ctl_report {
 103         int     ucr_report;
 104         u_char  ucr_data[1024]; /* used data size will vary */
 105 };
 106 .Ed
 107 .It Dv USB_SET_REPORT (struct usb_ctl_report)
 108 Set a report in the device.
 109 The
 110 .Dv report
 111 field indicates which report is to be set.
 112 It should be
 113 .Dv UHID_INPUT_REPORT ,
 114 .Dv UHID_OUTPUT_REPORT ,
 115 or
 116 .Dv UHID_FEATURE_REPORT .
 117 This call may fail if the device does not support this feature.
 118 .It Dv USB_GET_DEVICEINFO (struct usb_device_info)
 119 Get an information summary for the device.
 120 This call will not issue any USB transactions.
 121 .It Dv USB_GET_STRING_DESC (struct usb_string_desc)
 122 Get a string descriptor for the given language id and
 123 string index.
 124 .Bd -literal
 125 struct usb_string_desc {
 126         int     usd_string_index;
 127         int     usd_language_id;
 128         usb_string_descriptor_t usd_desc;
 129 };
 130 .Ed
 131 .El
 132 .Pp
 133 Use
 134 .Xr read 2
 135 to get data from the device.
 136 Data should be read in chunks of the size prescribed by the report
 137 descriptor.
 138 .Pp
 139 Use
 140 .Xr write 2
 141 send data to the device.
 142 Data should be written in chunks of the size prescribed by the
 143 report descriptor.
 144 .Sh FILES
 145 .Bl -tag -width Pa
 146 .It Pa /dev/uhid?
 147 .El
 148 .Sh SEE ALSO
 149 .Xr usbhidaction 1 ,
 150 .Xr usbhidctl 1 ,
 151 .Xr uhidev 4 ,
 152 .Xr usb 4
 153 .Sh HISTORY
 154 The
 155 .Nm
 156 driver
 157 appeared in
 158 .Nx 1.4 .
 159 Support for the
 160 .Dv USB_GET_DEVICEINFO
 161 and
 162 .Dv USB_GET_STRING_DESC
 163 ioctls appeared in
 164 .Nx 2.0 .