1.\" $NetBSD: usb.3,v 1.13 2000/09/24 02:17:52 augustss Exp $ 2.\" 3.\" Copyright (c) 1999, 2001 Lennart Augustsson <augustss@NetBSD.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd January 27, 2009 30.Dt USBHID 3 31.Os 32.Sh NAME 33.Nm usbhid , 34.Nm hid_get_report_desc , 35.Nm hid_get_report_id , 36.Nm hid_use_report_desc , 37.Nm hid_dispose_report_desc , 38.Nm hid_start_parse , 39.Nm hid_end_parse , 40.Nm hid_get_item , 41.Nm hid_report_size , 42.Nm hid_locate , 43.Nm hid_usage_page , 44.Nm hid_usage_in_page , 45.Nm hid_init , 46.Nm hid_get_data , 47.Nm hid_set_data , 48.Nm hid_get_report , 49.Nm hid_set_report 50.Nd USB HID access routines 51.Sh LIBRARY 52.Lb libusbhid 53.Sh SYNOPSIS 54.In usbhid.h 55.Ft report_desc_t 56.Fn hid_get_report_desc "int file" 57.Ft int 58.Fn hid_get_report_id "int file" 59.Ft int 60.Fn hid_set_immed "int fd" "int enable" 61.Ft report_desc_t 62.Fn hid_use_report_desc "unsigned char *data" "unsigned int size" 63.Ft void 64.Fn hid_dispose_report_desc "report_desc_t d" 65.Ft hid_data_t 66.Fn hid_start_parse "report_desc_t d" "int kindset" "int id" 67.Ft void 68.Fn hid_end_parse "hid_data_t s" 69.Ft int 70.Fn hid_get_item "hid_data_t s" "hid_item_t *h" 71.Ft int 72.Fn hid_report_size "report_desc_t d" "hid_kind_t k" "int id" 73.Ft int 74.Fn hid_locate "report_desc_t d" "u_int usage" "hid_kind_t k" "hid_item_t *h" "int id" 75.Ft "const char *" 76.Fn hid_usage_page "int i" 77.Ft "const char *" 78.Fn hid_usage_in_page "u_int u" 79.Ft int 80.Fn hid_parse_usage_page "const char *" 81.Ft int 82.Fn hid_parse_usage_in_page "const char *" 83.Ft void 84.Fn hid_init "const char *file" 85.Ft int 86.Fn hid_get_data "const void *data" "const hid_item_t *h" 87.Ft void 88.Fn hid_set_data "void *buf" "const hid_item_t *h" "int data" 89.Ft int 90.Fn hid_get_report "int fd" "enum hid_kind k" "unsigned char *data" "unsigned int size" 91.Ft int 92.Fn hid_set_report "int fd" "enum hid_kind k" "unsigned char *data" "unsigned int size" 93.Sh DESCRIPTION 94The 95.Nm 96library provides routines to extract data from USB Human Interface Devices. 97.Ss Introduction 98USB HID devices send and receive data laid out in a device dependent way. 99The 100.Nm 101library contains routines to extract the 102.Em "report descriptor" 103which contains the data layout information and then use this information. 104.Pp 105The routines can be divided into four parts: extraction of the descriptor, 106parsing of the descriptor, translating to/from symbolic names, and 107data manipulation. 108.Ss Synchronous HID operation 109Synchronous HID operation can be enabled or disabled by a call to 110.Fn hid_set_immed . 111If the second argument is zero synchronous HID operation is disabled. 112Else synchronous HID operation is enabled. 113The function returns a negative value on failure. 114.Pp 115.Fn hid_get_report 116and 117.Fn hid_set_report 118functions allow to synchronously get and set specific report if device 119supports it. 120For devices with multiple report IDs, wanted ID should be provided in the 121first byte of the buffer for both get and set. 122.Ss Descriptor Functions 123The report descriptor ID can be obtained by calling 124.Fn hid_get_report_id . 125A report descriptor can be obtained by calling 126.Fn hid_get_report_desc 127with a file descriptor obtained by opening a 128.Xr uhid 4 129device. 130Alternatively a data buffer containing the report descriptor can be 131passed into 132.Fn hid_use_report_desc . 133The data is copied into an internal structure. 134When the report descriptor 135is no longer needed it should be freed by calling 136.Fn hid_dispose_report_desc . 137The type 138.Vt report_desc_t 139is opaque and should be used when calling the parsing functions. 140If 141.Fn hid_dispose_report_desc 142fails it will return 143.Dv NULL . 144.Ss Descriptor Parsing Functions 145To parse the report descriptor the 146.Fn hid_start_parse 147function should be called with a report descriptor, a set that 148describes which items that are interesting, and the desired report 149ID (or -1 to obtain items of all report IDs). 150The set is obtained by OR-ing together values 151.Fa "(1 << k)" 152where 153.Fa k 154is an item of type 155.Vt hid_kind_t . 156The function returns 157.Dv NULL 158if the initialization fails, otherwise an opaque value to be used 159in subsequent calls. 160After parsing the 161.Fn hid_end_parse 162function should be called to free internal data structures. 163.Pp 164To iterate through all the items in the report descriptor 165.Fn hid_get_item 166should be called while it returns a value greater than 0. 167When the report descriptor ends it will returns 0; a syntax 168error within the report descriptor will cause a return value less 169than 0. 170The struct pointed to by 171.Fa h 172will be filled with the relevant data for the item. 173The definition of 174.Vt hid_item_t 175can be found in 176.In usbhid.h 177and the meaning of the components in the USB HID documentation. 178.Pp 179Data should be read/written to the device in the size of 180the report. 181The size of a report (of a certain kind) can be computed by the 182.Fn hid_report_size 183function. 184If the report is prefixed by an ID byte it is given by 185.Fa id . 186.Pp 187To locate a single item the 188.Fn hid_locate 189function can be used. 190It should be given the usage code of 191the item and its kind and it will fill the item and return 192non-zero if the item was found. 193.Ss Name Translation Functions 194The function 195.Fn hid_usage_page 196will return the symbolic name of a usage page, and the function 197.Fn hid_usage_in_page 198will return the symbolic name of the usage within the page. 199Both these functions may return a pointer to static data. 200.Pp 201The functions 202.Fn hid_parse_usage_page 203and 204.Fn hid_parse_usage_in_page 205are the inverses of 206.Fn hid_usage_page 207and 208.Fn hid_usage_in_page . 209They take a usage string and return the number of the usage, or \-1 210if it cannot be found. 211.Pp 212Before any of these functions can be called the usage table 213must be parsed, this is done by calling 214.Fn hid_init 215with the name of the table. 216Passing 217.Dv NULL 218to this function will cause it to use the default table. 219.Ss Data Extraction Functions 220Given the data obtained from a HID device and an item in the 221report descriptor the 222.Fn hid_get_data 223function extracts the value of the item. 224Conversely 225.Fn hid_set_data 226can be used to put data into a report (which must be zeroed first). 227.Sh FILES 228.Bl -tag -width ".Pa /usr/share/misc/usb_hid_usages" 229.It Pa /usr/share/misc/usb_hid_usages 230The default HID usage table. 231.El 232.Sh EXAMPLES 233Not yet. 234.Sh SEE ALSO 235The 236.Tn USB 237specifications can be found at 238.Pa http://www.usb.org/developers/docs/ . 239.Pp 240.Xr uhid 4 , 241.Xr usb 4 242.Sh HISTORY 243The 244.Nm 245library first appeared in 246.Nx 1.5 . 247.Sh BUGS 248This man page is woefully incomplete. 249