summaryrefslogtreecommitdiff
path: root/hw/xfree86/os-support/bsd/libusb/usb.3
diff options
context:
space:
mode:
Diffstat (limited to 'hw/xfree86/os-support/bsd/libusb/usb.3')
-rw-r--r--hw/xfree86/os-support/bsd/libusb/usb.3191
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 .