Rename libusb to libusbhid, a better name, per NetBSD

1 files changed, 213 insertions, 0 deletions

diff --git a/lib/libusbhid/usbhid.3 b/lib/libusbhid/usbhid.3
new file mode 100644
index 00000000000..a31e261b118
--- /dev/null
+++ b/lib/libusbhid/usbhid.3
@@ -0,0 +1,213 @@
+.\"	$OpenBSD: usbhid.3,v 1.1 2001/12/30 07:04:38 pvalchev Exp $
+.\"	$NetBSD: usb.3,v 1.14 2001/04/09 12:09:49 wiz 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.
+.\"
+.Dd May 11, 1999
+.Dt USBHID 3
+.Os
+.Sh NAME
+.Nm usbhid ,
+.Nm hid_get_report_desc ,
+.Nm hid_use_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 SYNOPSIS
+.Fd #include <usbhid.h>
+.Ft report_desc_t
+.Fn hid_get_report_desc "int file"
+.Ft report_desc_t
+.Fn hid_use_report_desc "unsigned char *data" "unsigned int size"
+.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 int
+.Fn hid_parse_usage_page "const char *"
+.Ft char *
+.Fn hid_parse_usage_in_page "const char *"
+.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 in 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. Alternatively a data buffer containing the report descriptor can be
+passed into
+.Fn hid_use_report_desc .
+The data is copied into an internal structure. 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.
+If
+.Fn hid_dispose_report_desc
+fails it will return
+.Fa NULL .
+.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 or-ing 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 <usbhid.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.
+.Pp
+The functions
+.Fn hid_parse_usage_page
+and
+.Fn hid_parse_usage_in_page
+are the inverses of
+.Fn hid_usage_page
+and
+.Fn hid_usage_in_page .
+They take a usage string and return the number of the usage, or -1
+if it cannot be found.
+.Pp
+Before any 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 EXAMPLES
+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.html
+.Pp
+.Xr uhid 4 ,
+.Xr usb 4
+.Sh HISTORY
+The
+.Nm
+library first appeared in
+.Ox 3.0 .