From 5f88cf68fca34a3fda4cad2e0d1e424af93c4c0e Mon Sep 17 00:00:00 2001
From: Oleksandr Tymoshenko <gonzo@FreeBSD.org>
Date: Sun, 1 Jul 2018 22:48:00 +0000
Subject: [PATCH] [man] Get uhid(4) man page in sync with current API

API documented in previous version of uhid(4) man page has been obsolete
since May 2009 when old USB stack was replaced with USB2 implentation.
Current API has the same set of ioctl calls but uses usb_gen_descriptor
structure to pass data to/from kernel.

MFC after:	1 week
---
 share/man/man4/uhid.4 | 47 +++++++++++++++++++++++++++++--------------
 1 file changed, 32 insertions(+), 15 deletions(-)

diff --git a/share/man/man4/uhid.4 b/share/man/man4/uhid.4
index 9763198c2445..e0868e73fb65 100644
--- a/share/man/man4/uhid.4
+++ b/share/man/man4/uhid.4
@@ -29,7 +29,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd April 24, 2018
+.Dd July 1, 2018
 .Dt UHID 4
 .Os
 .Sh NAME
@@ -61,17 +61,28 @@ calls:
 .Bl -tag -width indent
 .It Dv USB_GET_REPORT_ID Pq Vt int
 Get the report identifier used by this HID report.
-.It Dv USB_GET_REPORT_DESC Pq Vt "struct usb_ctl_report_desc"
+.It Dv USB_GET_REPORT_DESC Pq Vt "struct usb_gen_descriptor"
 Get the HID report descriptor.
+Copies a maximum of
+.Va ugd_maxlen
+bytes of the report descriptor data into the memory
+specified by
+.Va ugd_data .
+Upon return
+.Va ugd_actlen
+is set to the number of bytes copied.
 Using
 this descriptor the exact layout and meaning of data to/from
 the device can be found.
 The report descriptor is delivered
 without any processing.
 .Bd -literal
-struct usb_ctl_report_desc {
-    int     ucrd_size;
-    u_char  ucrd_data[1024];	/* filled data size will vary */
+struct usb_gen_descriptor {
+	void   *ugd_data;
+	uint16_t ugd_maxlen;
+	uint16_t ugd_actlen;
+	uint8_t	ugd_report_type;
+	...
 };
 .Ed
 .It Dv USB_SET_IMMED Pq Vt int
@@ -85,11 +96,18 @@ will only return the data that the device reports on its
 interrupt pipe.
 This call may fail if the device does not support
 this feature.
-.It Dv USB_GET_REPORT Pq Vt "struct usb_ctl_report"
+.It Dv USB_GET_REPORT Pq Vt "struct usb_gen_descriptor"
 Get a report from the device without waiting for data on
 the interrupt pipe.
+Copies a maximum of
+.Va ugd_maxlen
+bytes of the report data into the memory specified by
+.Va ugd_data .
+Upon return
+.Va ugd_actlen
+is set to the number of bytes copied.
 The
-.Va report
+.Va ugd_report_type
 field indicates which report is requested.
 It should be
 .Dv UHID_INPUT_REPORT ,
@@ -97,22 +115,21 @@ It should be
 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 */
-};
-.Ed
-.It Dv USB_SET_REPORT Pq Vt "struct usb_ctl_report"
+.It Dv USB_SET_REPORT Pq Vt "struct usb_gen_descriptor"
 Set a report in the device.
 The
-.Va report
+.Va ugd_report_type
 field indicates which report is to be set.
 It should be
 .Dv UHID_INPUT_REPORT ,
 .Dv UHID_OUTPUT_REPORT ,
 or
 .Dv UHID_FEATURE_REPORT .
+The value of the report is specified by the
+.Va ugd_data
+and the
+.Va ugd_maxlen
+fields.
 This call may fail if the device does not support this feature.
 .El
 .Pp