MFprojects/hid:

Import the rest of HID improvements from the branch:
 - improve report descriptor parser in libusbhid to handle several kinds of
reports same time;
 - add to the libusbhid API two functions wrapping respective kernel IOCTLs
for reading and writing reports;
 - tune uhid IOCTL interface to allow reading and writing arbitrary report,
when multiple supported by the device;
 - teach usbhidctl to set output and feature reports;
 - make usbhidaction support all the same item names as bhidctl.

Sponsored by: iXsystems, inc.

1 files changed, 69 insertions, 11 deletions

diff --git a/usr.bin/usbhidctl/usbhidctl.1 b/usr.bin/usbhidctl/usbhidctl.1
index 37c7c7a..5681189 100644
--- a/usr.bin/usbhidctl/usbhidctl.1
+++ b/usr.bin/usbhidctl/usbhidctl.1
@@ -28,7 +28,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd November 23, 2006
+.Dd August 01, 2011
 .Dt USBHIDCTL 1
 .Os
 .Sh NAME
@@ -36,27 +36,51 @@
 .Nd manipulate USB HID devices
 .Sh SYNOPSIS
 .Nm
-.Op Fl a
 .Fl f Ar device
+.Op Fl t Ar table
+.Op Fl v
+.Op Fl x
+.Fl r
+.Nm
+.Fl f Ar device
+.Op Fl t Ar table
 .Op Fl l
-.Op Fl n
-.Op Fl r
+.Op Fl v
+.Op Fl x
+.Fl a
+.Nm
+.Fl f Ar device
 .Op Fl t Ar table
+.Op Fl l
+.Op Fl n
 .Op Fl v
 .Op Fl x
-.Op Ar item ...
+.Ar item ...
+.Nm
+.Fl f Ar device
+.Op Fl t Ar table
+.Op Fl v
+.Op Fl z
+.Fl w
+.Ar item=value ...
 .Sh DESCRIPTION
 The
 .Nm
-utility can be used to dump the state of a USB HID (Human Interface Device).
+utility can be used to dump and modify the state of a USB HID (Human
+Interface Device).
 Each named
 .Ar item
 is printed.
+If the
+.Fl w
+flag is specified
+.Nm
+attempts to set the specified items to the given values.
 .Pp
 The options are as follows:
 .Bl -tag -width Ds
 .It Fl a
-Show all items.
+Show all items and their current values if device returns.
 .It Fl f Ar device
 Specify a path name for the device to operate on.
 .It Fl l
@@ -69,9 +93,47 @@ Dump the report descriptor.
 Specify a path name for the HID usage table file.
 .It Fl v
 Be verbose.
+.It Fl w
+Change item values.
+Only 'output' and 'feature' kinds can be set with this option.
 .It Fl x
 Dump data in hexadecimal as well as decimal.
+.It Fl z
+Reset reports to zero before processing
+.Fl w
+arguments. If not specified, current values will be requested from device.
 .El
+.Sh SYNTAX
+.Nm
+compares the names of items specified on the command line against the human
+interface items reported by the USB device.
+Each human interface item is mapped from its native form to a human readable
+name, using the HID usage table file.
+Command line items are compared with the generated item names,
+and the USB HID device is operated on when a match is found.
+.Pp
+Each human interface item is named by the
+.Qq page
+it appears in, the
+.Qq usage
+within that page, and the list of
+.Qq collections
+containing the item.
+Each collection in turn is also identified by page, and
+the usage within that page.
+.Pp
+On the
+.Nm
+command line the page name is separated from the usage name with the character
+.Sq Cm \&: .
+The collections are separated by the character
+.Sq Cm \&. .
+.Pp
+Some devices give the same name to more than one item.
+.Nm
+supports isolating each item by appending a
+.Sq Cm \&# .
+character and a decimal item instance number, starting at zero.
 .Sh FILES
 .Pa /usr/share/misc/usb_hid_usages
 The default HID usage table.
@@ -84,7 +146,3 @@ The
 .Nm
 command appeared in
 .Nx 1.4 .
-.Sh BUGS
-The
-.Nm
-utility cannot show nor set output and feature items.