1.\"
2.\" This file and its contents are supplied under the terms of the
3.\" Common Development and Distribution License ("CDDL"), version 1.0.
4.\" You may only use this file in accordance with the terms of version
5.\" 1.0 of the CDDL.
6.\"
7.\" A full copy of the text of the CDDL should have accompanied this
8.\" source.  A copy of the CDDL is also available via the Internet at
9.\" http://www.illumos.org/license/CDDL.
10.\"
11.\"
12.\" Copyright 2016 Joyent, Inc.
13.\"
14.Dd Aug 7, 2016
15.Dt USB_EP_XDESCR_FILL 9F
16.Os
17.Sh NAME
18.Nm usb_ep_xdescr_fill
19.Nd fill extended endpoint description from endpoint data
20.Sh SYNOPSIS
21.In sys/usb/usba.h
22.Ft int
23.Fo usb_ep_xdescr_fill
24.Fa "uint_t version"
25.Fa "dev_info_t *dip"
26.Fa "usb_ep_data_t *ep_data"
27.Fa "usb_ep_xdescr_t *ep_xdescr"
28.Fc
29.Sh INTERFACE STABILITY
30illumos DDI specific
31.Sh PARAMETESR
32.Bl -tag -width Fa
33.It Fa version
34Indicates the current version of the
35.Ft usb_ep_xdescr_t
36structure the driver is using.
37Callers should always specify
38.Sy USB_EP_XDESCR_CURRENT_VERSION .
39.It Fa dip
40Pointer to the device's
41.Sy dev_info
42structure.
43.It Fa ep_data
44Pointer to endpoint data retrieved by calling
45.Xr usb_lookup_ep_data 9F .
46.It Fa ep_xdescr
47Pointer to the extended endpoint descriptor that will be filled out.
48.El
49.Sh DESCRIPTION
50The
51.Fn usb_ep_xdescr_fill
52function is used to fill in the members of the extended endpoint
53descriptor
54.Fa ep_xdescr
55based on the endpoint descriptor data in
56.Fa ep_data .
57Once filled in,
58.Fa ep_xdescr
59can be used to open a pipe by calling
60.Xr usb_pipe_xopen 9F .
61.Pp
62Prior to USB 3.0, only one descriptor, the
63.Xr usb_ep_descr 9S ,
64was needed to describe an endpoint.
65However, with USB 3.0, additional companion descriptors have been added and are
66required to successfully open an endpoint.
67After calling this, all descriptors needed to successfully open a pipe will be
68placed into
69.Fa ep_xdescr
70and the endpoint data,
71.Fa ep_data ,
72is no longer required.
73.Sh CONTEXT
74The
75.Fn usb_ep_xdescr_fill
76is generally only called from a drivers
77.Xr attach 9E
78entry point; however, it may be called from either
79.Sy user
80or
81.Sy kernel
82context.
83.Sh RETURN VALUES
84Upon successful completion, the
85.Fn usb_ep_xdescr_fill
86function returns
87.Sy USB_SUCCESS .
88Otherwise an error number is returned.
89.Sh ERRORS
90.Bl -tag -width Er
91.It Er USB_INVALID_ARGS
92The value of
93.Fa version
94is unknown, or one of
95.Fa dip ,
96.Fa ep_data ,
97and
98.Fa ep_xdescr
99was an invalid pointer.
100.It Er USB_FAILURE
101An unknown error occurred.
102.El
103.Sh SEE ALSO
104.Xr usb_lookup_ep_data 9F ,
105.Xr usb_pipe_xopen 9F ,
106.Xr usb_ep_descr 9S ,
107.Xr usb_ep_ss_comp_descr 9S ,
108.Xr usb_ep_xdescr 9S
109