Hi,
Improvements to the uhid(4) manual:
* Include the relevant header in the synopsis
* Document all supported ioctl commands
* Emphasis that a pointer is required to all ioctl commands
* Make the write(2) semantics a bit clearer
* Add files section
* Document errors
Comments? OK?
Index: uhid.4
===================================================================
RCS file: /cvs/src/share/man/man4/uhid.4,v
retrieving revision 1.19
diff -u -p -r1.19 uhid.4
--- uhid.4 30 Dec 2020 12:49:58 -0000 1.19
+++ uhid.4 14 Sep 2021 17:07:21 -0000
@@ -36,6 +36,8 @@
.Nd USB generic HID support
.Sh SYNOPSIS
.Cd "uhid* at uhidev?"
+.Pp
+.In dev/usb/usb.h
.Sh DESCRIPTION
The
.Nm
@@ -46,9 +48,11 @@ The device handles the following
.Xr ioctl 2
calls:
.Bl -tag -width indent
-.It Dv USB_GET_REPORT_ID Fa int
+.It Dv USB_GET_DEVICEINFO Fa struct usb_device_info *devinfo
+Get summarized information about the device.
+.It Dv USB_GET_REPORT_ID Fa int *repid
Get the report identifier used by this HID report.
-.It Dv USB_GET_REPORT_DESC Fa "struct usb_ctl_report_desc"
+.It Dv USB_GET_REPORT_DESC Fa struct usb_ctl_report_desc *repdesc
Get the HID report descriptor.
Using this descriptor the exact layout and meaning of data to/from
the device can be found.
@@ -59,25 +63,24 @@ struct usb_ctl_report_desc {
u_char ucrd_data[1024]; /* filled data size will vary */
};
.Ed
-.It Dv USB_GET_REPORT Fa "struct usb_ctl_report"
+.It Dv USB_GET_REPORT Fa struct usb_ctl_report *rep
Get a report from the device without waiting for data on
the interrupt pipe.
The
-.Fa report
+.Fa ucr_report
field indicates which report is requested.
It should be
.Dv UHID_INPUT_REPORT ,
.Dv UHID_OUTPUT_REPORT ,
or
.Dv UHID_FEATURE_REPORT .
-This call may fail if the device does not support this feature.
.Bd -literal
struct usb_ctl_report {
int ucr_report;
- u_char ucr_data[1024]; /* used data size will vary */
+ u_char ucr_data[1024]; /* filled data size will vary */
};
.Ed
-.It Dv USB_SET_REPORT Fa "struct usb_ctl_report"
+.It Dv USB_SET_REPORT Fa struct usb_ctl_report *rep
Set a report in the device.
The
.Dv report
@@ -87,9 +90,15 @@ It should be
.Dv UHID_OUTPUT_REPORT ,
or
.Dv UHID_FEATURE_REPORT .
-This call may fail if the device does not support this feature.
.El
.Pp
+The generic ioctls
+.Dv FIONBIO
+and
+.Dv FIOASYNC
+are supported by
+.Nm .
+.Pp
Use
.Xr read 2
to get data from the device.
@@ -98,8 +107,66 @@ Data should be read in chunks of the siz
Use
.Xr write 2
to send data to the device.
+Equivalent to issuing an
+.Xr ioctl 2
+.Dv USB_SET_REPORT
+request with the report set to
+.Dv UHID_OUTPUT_REPORT .
Data should be written in chunks of the size prescribed by the report
descriptor.
+.Sh FILES
+.Bl -tag -width /dev/tun* -compact
+.It Pa /dev/uhid*
+.El
+.Sh ERRORS
+If
+.Xr ioctl 2
+fails,
+.Xr errno 2
+is set to one of the following:
+.Bl -tag -width Er
+.It Bq Er EIO
+The device could not fulfill a
+.Dv USB_GET_REPORT
+or
+.Dv USB_SET_REPORT
+request.
+.It Bq Er EINVAL
+The report specified by the
+.Fa ucr_report
+field in a
+.Dv USB_GET_REPORT
+or
+.Dv USB_SET_REPORT
+request was invalid.
+.It Bq Er ENOTTY
+Unrecognized command.
+.El
+.Pp
+If
+.Xr read 2
+fails,
+.Xr errno 2
+is set to one of the following:
+.Bl -tag -width Er
+.It Bq Er EIO
+The device has already been detached.
+.It Bq Er EWOULDBLOCK
+Non-blocking I/O was selected and no data were available.
+.El
+.Pp
+If
+.Xr write 2
+fails,
+.Xr errno 2
+is set to one of the following:
+.Bl -tag -width Er
+.It Bq Er EIO
+The device has already been detached or the same device does not have a
+corresponding output report.
+.It Bq Er EMSGSIZE
+The size of the supplied data exceeds the size of the output report.
+.El
.Sh SEE ALSO
.Xr usbhidctl 1 ,
.Xr usbhid 3 ,
