diff options
Diffstat (limited to 'hw/xfree86/os-support/bsd/libusb/usb.3')
| -rw-r--r-- | hw/xfree86/os-support/bsd/libusb/usb.3 | 191 |
1 files changed, 191 insertions, 0 deletions
diff --git a/hw/xfree86/os-support/bsd/libusb/usb.3 b/hw/xfree86/os-support/bsd/libusb/usb.3 new file mode 100644 index 000000000..f88a28cd6 --- /dev/null +++ b/hw/xfree86/os-support/bsd/libusb/usb.3 @@ -0,0 +1,191 @@ +.\" $NetBSD: usb.3,v 1.9 1999/11/08 22:33:40 augustss Exp $ +.\" +.\" Copyright (c) 1999 Lennart Augustsson <augustss@netbsd.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $XFree86: xc/programs/Xserver/hw/xfree86/os-support/bsd/libusb/usb.3,v 1.1 2000/02/11 18:06:50 dawes Exp $ +.\" +.Dd May 11, 1999 +.Dt USB 3 +.Os +.Sh NAME +.Nm usb , +.Nm hid_get_report_desc , +.Nm hid_dispose_report_desc , +.Nm hid_start_parse , +.Nm hid_end_parse , +.Nm hid_get_item , +.Nm hid_report_size , +.Nm hid_locate , +.Nm hid_usage_page , +.Nm hid_usage_in_page , +.Nm hid_init , +.Nm hid_get_data , +.Nm hid_set_data +.Nd USB HID access routines +.Sh LIBRARY +.Lb libusb +.Sh SYNOPSIS +.Fd #include <usb.h> +.Ft report_desc_t +.Fn hid_get_report_desc "int file" +.Ft void +.Fn hid_dispose_report_desc "report_desc_t d" +.Ft hid_data_t +.Fn hid_start_parse "report_desc_t d" "int kindset" +.Ft void +.Fn hid_end_parse "hid_data_t s" +.Ft int +.Fn hid_get_item "hid_data_t s" "hid_item_t *h" +.Ft int +.Fn hid_report_size "report_desc_t d" "hid_kind_t k" "int *idp" +.Ft int +.Fn hid_locate "report_desc_t d" "u_int usage" "hid_kind_t k" "hid_item_t *h" +.Ft char * +.Fn hid_usage_page "int i" +.Ft char * +.Fn hid_usage_in_page "u_int u" +.Ft void +.Fn hid_init "char *file" +.Ft int +.Fn hid_get_data "void *data" "hid_item_t *h" +.Ft void +.Fn hid_set_data "void *data" "hid_item_t *h" "u_int data" +.Sh DESCRIPTION +The +.Nm +library provides routines to extract data from USB Human Interface Devices. +.Ss INTRODUCTION +USB HID devices send and receive data layed out a device dependent +way. The +.Nm +library contains routines to extract the +.Em report descriptor +which contains the data layout information and then use this information. +.Pp +The routines can be divided into four parts: extraction of the descriptor, +parsing of the descriptor, translating to/from symbolic names, and +data manipulation. +.Ss DESCRIPTOR FUNCTIONS +A report descriptor can be obtained by calling +.Fn hid_get_report_desc +with a file descriptor obtained by opening a +.Xr uhid 4 +device. +When the report descriptor is no longer needed it should be freed +by calling +.Fn hid_dispose_report_desc . +The type +.Fa report_desc_t +is opaque and should be used when calling the parsing functions. +.Ss DESCRIPTOR PARSING FUNCTIONS +To parse the report descriptor the +.Fn hid_start_parse +function should be called with a report descriptor and a set that +describes which items that are interesting. The set is obtained +by oring together values +.Fa "(1 << k)" +where +.Fa k +is an item of type +.Fa hid_kind_t . +The function returns +.Fa NULL +if the initialization fails, otherwise an opaque value to be used +in subsequent calls. +After parsing the +.Fn hid_end_parse +function should be called to free internal data structures. +.Pp +To iterate through all the items in the report descriptor +.Fn hid_get_item +should be called while it returns a value greater than 0. +When the report descriptor ends it will returns 0; a syntax +error within the report descriptor will cause a return value less +than 0. +The struct pointed to by +.Fa h +will be filled with the relevant data for the item. +The definition of +.Fa hid_item_t +can be found in +.Pa <usb.h> +and the meaning of the components in the USB HID documentation. +.Pp +Data should be read/written to the device in the size of +the report. The size of a report (of a certain kind) can be +computed by the +.Fn hid_report_size +function. If the report is prefixed by an ID byte it is +stored at +.Fa idp , +otherwise it will contain 0. +.Pp +To locate a single item the +.Fn hid_locate +function can be used. It should be given the usage code of +the item and its kind and it will fill the item and return +non-zero if the item was found. +.Pp +.Ss NAME TRANSLATION FUNCTIONS +The function +.Fn hid_usage_page +will return the symbolic name of a usage page, and the function +.Fn hid_usage_in_page +will return the symbolic name of the usage within the page. +Both these functions may return a pointer to static data. +Before either of these functions can be called the usage table +must be parsed, this is done by calling +.Fn hid_init +with the name of the table. Passing +.Fa NULL +to this function will cause it to use the default table. +.Ss DATA EXTRACTION FUNCTIONS +Given the data obtained from a HID device and an item in the +report descriptor the +.Fn hid_get_data +function extracts the value of the item. +Conversely +.Fn hid_set_data +can be used to put data into a report (which must be zeroed first). +.Sh EXAMPLE +Not yet. +.Sh FILES +.Pa /usr/share/misc/usb_hid_usages +The default HID usage table. +.Sh BUGS +This man page is woefully incomplete. +.Sh SEE ALSO +The +.Tn USB +specifications can be found at +.Dv http://www.usb.org/developers/docs.htm . +.Pp +.Xr hid 4 , +.Xr usb 4 . +.Sh HISTORY +The +.Nm +library first appeared in +.Nx 1.5 . |