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.Nd USB HID access routines 49.Sh LIBRARY 50.Lb libusbhid 51.Sh SYNOPSIS 52.In usbhid.h 53.Ft report_desc_t 54.Fn hid_get_report_desc "int file" 55.Ft int 56.Fn hid_get_report_id "int file" 57.Ft int 58.Fn hid_set_immed "int fd" "int enable" 59.Ft report_desc_t 60.Fn hid_use_report_desc "unsigned char *data" "unsigned int size" 61.Ft void 62.Fn hid_dispose_report_desc "report_desc_t d" 63.Ft hid_data_t 64.Fn hid_start_parse "report_desc_t d" "int kindset" "int id" 65.Ft void 66.Fn hid_end_parse "hid_data_t s" 67.Ft int 68.Fn hid_get_item "hid_data_t s" "hid_item_t *h" 69.Ft int 70.Fn hid_report_size "report_desc_t d" "hid_kind_t k" "int id" 71.Ft int 72.Fn hid_locate "report_desc_t d" "u_int usage" "hid_kind_t k" "hid_item_t *h" "int id" 73.Ft "const char *" 74.Fn hid_usage_page "int i" 75.Ft "const char *" 76.Fn hid_usage_in_page "u_int u" 77.Ft int 78.Fn hid_parse_usage_page "const char *" 79.Ft int 80.Fn hid_parse_usage_in_page "const char *" 81.Ft void 82.Fn hid_init "const char *file" 83.Ft int 84.Fn hid_get_data "const void *data" "const hid_item_t *h" 85.Ft void 86.Fn hid_set_data "void *buf" "const hid_item_t *h" "int data" 87.Sh DESCRIPTION 88The 89.Nm 90library provides routines to extract data from USB Human Interface Devices. 91.Ss Introduction 92USB HID devices send and receive data layed out in a device dependent way. 93The 94.Nm 95library contains routines to extract the 96.Em "report descriptor" 97which contains the data layout information and then use this information. 98.Pp 99The routines can be divided into four parts: extraction of the descriptor, 100parsing of the descriptor, translating to/from symbolic names, and 101data manipulation. 102.Ss Synchronous HID operation 103Synchronous HID operation can be enabled or disabled by a call to 104.Fn hid_set_immed . 105If the second argument is zero synchronous HID operation is disabled. 106Else synchronous HID operation is enabled. 107The function returns a negative value on failure. 108.Ss Descriptor Functions 109The report descriptor ID can be obtained by calling 110.Fn hid_get_report_id . 111A report descriptor can be obtained by calling 112.Fn hid_get_report_desc 113with a file descriptor obtained by opening a 114.Xr uhid 4 115device. 116Alternatively a data buffer containing the report descriptor can be 117passed into 118.Fn hid_use_report_desc . 119The data is copied into an internal structure. 120When the report descriptor 121is no longer needed it should be freed by calling 122.Fn hid_dispose_report_desc . 123The type 124.Vt report_desc_t 125is opaque and should be used when calling the parsing functions. 126If 127.Fn hid_dispose_report_desc 128fails it will return 129.Dv NULL . 130.Ss Descriptor Parsing Functions 131To parse the report descriptor the 132.Fn hid_start_parse 133function should be called with a report descriptor and a set that 134describes which items that are interesting. 135The set is obtained by OR-ing together values 136.Fa "(1 << k)" 137where 138.Fa k 139is an item of type 140.Vt hid_kind_t . 141The report ID (if present) is given by 142.Fa id . 143The function returns 144.Dv NULL 145if the initialization fails, otherwise an opaque value to be used 146in subsequent calls. 147After parsing the 148.Fn hid_end_parse 149function should be called to free internal data structures. 150.Pp 151To iterate through all the items in the report descriptor 152.Fn hid_get_item 153should be called while it returns a value greater than 0. 154When the report descriptor ends it will returns 0; a syntax 155error within the report descriptor will cause a return value less 156than 0. 157The struct pointed to by 158.Fa h 159will be filled with the relevant data for the item. 160The definition of 161.Vt hid_item_t 162can be found in 163.In usbhid.h 164and the meaning of the components in the USB HID documentation. 165.Pp 166Data should be read/written to the device in the size of 167the report. 168The size of a report (of a certain kind) can be computed by the 169.Fn hid_report_size 170function. 171If the report is prefixed by an ID byte it is given by 172.Fa id . 173.Pp 174To locate a single item the 175.Fn hid_locate 176function can be used. 177It should be given the usage code of 178the item and its kind and it will fill the item and return 179non-zero if the item was found. 180.Ss Name Translation Functions 181The function 182.Fn hid_usage_page 183will return the symbolic name of a usage page, and the function 184.Fn hid_usage_in_page 185will return the symbolic name of the usage within the page. 186Both these functions may return a pointer to static data. 187.Pp 188The functions 189.Fn hid_parse_usage_page 190and 191.Fn hid_parse_usage_in_page 192are the inverses of 193.Fn hid_usage_page 194and 195.Fn hid_usage_in_page . 196They take a usage string and return the number of the usage, or \-1 197if it cannot be found. 198.Pp 199Before any of these functions can be called the usage table 200must be parsed, this is done by calling 201.Fn hid_init 202with the name of the table. 203Passing 204.Dv NULL 205to this function will cause it to use the default table. 206.Ss Data Extraction Functions 207Given the data obtained from a HID device and an item in the 208report descriptor the 209.Fn hid_get_data 210function extracts the value of the item. 211Conversely 212.Fn hid_set_data 213can be used to put data into a report (which must be zeroed first). 214.Sh FILES 215.Bl -tag -width ".Pa /usr/share/misc/usb_hid_usages" 216.It Pa /usr/share/misc/usb_hid_usages 217The default HID usage table. 218.El 219.Sh EXAMPLES 220Not yet. 221.Sh SEE ALSO 222The 223.Tn USB 224specifications can be found at 225.Pa http://www.usb.org/developers/docs/ . 226.Pp 227.Xr uhid 4 , 228.Xr usb 4 229.Sh HISTORY 230The 231.Nm 232library first appeared in 233.Nx 1.5 . 234.Sh BUGS 235This man page is woefully incomplete. 236