[src/trunk]: src/lib/libusb Update the man page and rename one functions.

[augustss <augustss%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/33ec3b23d032
branches:  trunk
changeset: 472910:33ec3b23d032
user:      augustss <augustss%NetBSD.org@localhost>
date:      Wed May 12 00:04:49 1999 +0000

description:
Update the man page and rename one functions.

diffstat:

 lib/libusb/data.c  |   30 ++++++++++--
 lib/libusb/parse.c |   22 ++++++++-
 lib/libusb/usb.3   |  132 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 lib/libusb/usb.h   |   10 ++-
 4 files changed, 182 insertions(+), 12 deletions(-)

diffs (279 lines):

diff -r c2681139b520 -r 33ec3b23d032 lib/libusb/data.c
--- a/lib/libusb/data.c Tue May 11 22:39:05 1999 +0000
+++ b/lib/libusb/data.c Wed May 12 00:04:49 1999 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: data.c,v 1.2 1999/05/11 21:15:46 augustss Exp $        */
+/*     $NetBSD: data.c,v 1.3 1999/05/12 00:04:49 augustss Exp $        */
 
 /*
  * Copyright (c) 1999 Lennart Augustsson <augustss%netbsd.org@localhost>
@@ -29,13 +29,13 @@
 #include <stdlib.h>
 #include "usb.h"
 
-unsigned int
-getdata(void *p, hid_item_t *h)
+int
+get_data(void *p, hid_item_t *h)
 {
        unsigned char *buf = p;
        unsigned int hpos = h->pos;     /* bit position of data */
        unsigned int hsize = h->report_size; /* bit length of data */
-       unsigned int data;
+       int data;
        int i, end, offs;
 
        if (hsize == 0)
@@ -50,7 +50,27 @@
        if (h->logical_minimum < 0) {
                /* Need to sign extend */
                hsize = sizeof data * 8 - hsize;
-               data = ((int)data << hsize) >> hsize;
+               data = (data << hsize) >> hsize;
        }
        return (data);
 }
+
+void
+set_data(void *p, hid_item_t *h, int data)
+{
+       unsigned char *buf = p;
+       unsigned int hpos = h->pos;     /* bit position of data */
+       unsigned int hsize = h->report_size; /* bit length of data */
+       int i, end, offs;
+
+       if (hsize != 32)
+               data &= (1 << hsize) - 1;
+       data <<= (hpos % 8);
+
+       offs = hpos / 8;
+       end = (hpos + hsize) / 8 - offs;
+       data = 0;
+       for (i = 0; i <= end; i++)
+               buf[offs + i] |= (data >> (i*8)) & 0xff;
+}
+
diff -r c2681139b520 -r 33ec3b23d032 lib/libusb/parse.c
--- a/lib/libusb/parse.c        Tue May 11 22:39:05 1999 +0000
+++ b/lib/libusb/parse.c        Wed May 12 00:04:49 1999 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: parse.c,v 1.2 1999/05/11 21:15:46 augustss Exp $       */
+/*     $NetBSD: parse.c,v 1.3 1999/05/12 00:04:49 augustss Exp $       */
 
 /*
  * Copyright (c) 1999 Lennart Augustsson <augustss%netbsd.org@localhost>
@@ -356,3 +356,23 @@
        size = h.pos + id;
        return ((size + 7) / 8);
 }
+
+int
+hid_locate(desc, u, k, h)
+       report_desc_t desc;
+       unsigned int u;
+       enum hid_kind k;
+       hid_item_t *h;
+{
+       hid_data_t d;
+
+       for (d = hid_start_parse(desc, 1<<k); hid_get_item(d, h); ) {
+               if (h->kind == k && !(h->flags & HIO_CONST) && h->usage == u) {
+                       hid_end_parse(d);
+                       return (1);
+               }
+       }
+       hid_end_parse(d);
+       h->report_size = 0;
+       return (0);
+}
diff -r c2681139b520 -r 33ec3b23d032 lib/libusb/usb.3
--- a/lib/libusb/usb.3  Tue May 11 22:39:05 1999 +0000
+++ b/lib/libusb/usb.3  Wed May 12 00:04:49 1999 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: usb.3,v 1.2 1999/05/11 21:15:46 augustss Exp $
+.\"    $NetBSD: usb.3,v 1.3 1999/05/12 00:04:49 augustss Exp $
 .\"
 .\" Copyright (c) 1999 Lennart Augustsson <augustss%netbsd.org@localhost>
 .\" All rights reserved.
@@ -28,16 +28,144 @@
 .Dt USB 3
 .Os
 .Sh NAME
-.Nm usb
+.Nm usb ,
+.Nm get_report_desc ,
+.Nm dispose_report_desc ,
+.Nm hid_start_parse ,
+.Nm hid_end_parse ,
+.Nm hid_get_item ,
+.Nm hid_report_size ,
+.Nm usage_page ,
+.Nm usage_in_page ,
+.Nm init_hid ,
+.Nm get_data ,
+.Nm set_data
 .Nd USB HID access routines
 .Sh LIBRARY
 .Lb libusb
 .Sh SYNOPSIS
 .Fd #include <usb.h>
+.Ft report_desc_t
+.Fn get_report_desc "int file"
+.Ft void
+.Fn 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 usage_page "int i"
+.Ft char *
+.Fn usage_in_page "u_int u"
+.Ft void
+.Fn init_hid "char *file"
+.Ft int
+.Fn get_data "void *data" "hid_item_t *h"
+.Ft void
+.Fn 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.
+.Sh 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 part: extraction of the descriptor,
+parsing of the descriptor, translating to/from symbolic names, and
+data manipulation.
+.Sh DESCRIPTOR FUNCTIONS
+A report descriptor can be obtained by calling
+.Fn 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 dispose_report_desc .
+The type 
+.Fa report_desc_t
+is opaque and should be used when calling the parsing functions.
+.Sh 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.
+.Pp
+Data is 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
+.Sh NAME TRANSLATION FUNCTIONS
+The function
+.Fn usage_page
+will return the symbolic name of a usage page, and the function
+.Fn 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 parse, this is done by calling
+.Fn init_hid
+with the name of the table.  Passing
+.Fa NULL
+to this function will cause it to use the default table.
+.Sh DATA EXTRACTION FUNCTIONS
+Given the data obtained from a HID device and an item in the
+report descriptor the
+.Fn get_data
+function extracts the value of the item.
+Conversely
+.Fn 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
diff -r c2681139b520 -r 33ec3b23d032 lib/libusb/usb.h
--- a/lib/libusb/usb.h  Tue May 11 22:39:05 1999 +0000
+++ b/lib/libusb/usb.h  Wed May 12 00:04:49 1999 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: usb.h,v 1.2 1999/05/11 21:15:46 augustss Exp $ */
+/*     $NetBSD: usb.h,v 1.3 1999/05/12 00:04:49 augustss Exp $ */
 
 /*
  * Copyright (c) 1999 Lennart Augustsson <augustss%netbsd.org@localhost>
@@ -30,9 +30,9 @@
 
 typedef struct hid_data *hid_data_t;
 
-enum hid_kind { 
+typedef enum hid_kind { 
        hid_input, hid_output, hid_feature, hid_collection, hid_endcollection
-};
+}hid_kind_t;
 
 typedef struct hid_item {
        /* Global */
@@ -80,6 +80,7 @@
 void hid_end_parse __P((hid_data_t s));
 int hid_get_item __P((hid_data_t s, hid_item_t *h));
 int hid_report_size __P((report_desc_t d, enum hid_kind k, int *idp));
+int hid_locate __P((report_desc_t d, unsigned int usage, enum hid_kind k, hid_item_t *h));
 
 /* Conversion to/from usage names, usage.c: */
 char *usage_page __P((int i));
@@ -87,4 +88,5 @@
 void init_hid __P((char *file));
 
 /* Extracting/insertion of data, data.c: */
-unsigned int getdata __P((void *data, hid_item_t *h));
+int get_data __P((void *p, hid_item_t *h));
+void set_data __P((void *p, hid_item_t *h, int data));