svn commit: r335854 - head/share/man/man4

[Oleksandr Tymoshenko]

Author: gonzo
Date: Sun Jul  1 22:48:00 2018
New Revision: 335854
URL: https://svnweb.freebsd.org/changeset/base/335854

Log:
  [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

Modified:
  head/share/man/man4/uhid.4

Modified: head/share/man/man4/uhid.4
==============================================================================
--- head/share/man/man4/uhid.4	Sun Jul  1 20:52:50 2018	(r335853)
+++ head/share/man/man4/uhid.4	Sun Jul  1 22:48:00 2018	(r335854)
@@ -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 i
 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