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 Sep 16, 2016
15.Dt USB_EP_XDESCR 9S
16.Os
17.Sh NAME
18.Nm usb_ep_xdescr ,
19.Nm usb_ep_xdescr_t
20.Nd extended endpoint descriptor
21.Sh SYNOPSIS
22.In sys/usb/usba.h
23.Sh INTERFACE LEVEL
24illumos DDI Specific
25.Sh DESCRIPTION
26The
27.Sy usb_ep_xdescr_t
28structure is used to describe an endpoint descriptor as well account for
29the continuing evolutions in the USB specification.
30.Pp
31Starting with the
32.Em USB 3.0
33specification,
34.Em USB 3.0
35endpoints have an endpoint SuperSpeed companion descriptor. See
36.Xr usb_ep_ss_comp_descr 9S
37for a description of the descriptor. In the
38.Em USB 3.1
39specification, certain endpoints will have additional companion
40descriptors.
41.Pp
42The
43.Sy usb_ep_xdescr_t
44structure, combined with the
45.Xr usb_ep_xdescr_fill 9F
46and
47.Xr usb_pipe_xopen 9F
48are designed to abstract away the need for USB client device drivers to
49need to be updated in the face of these newer endpoints, whose
50information is required for host controller devices to properly program
51the device.
52.Pp
53After looking up endpoint data, through the
54.Xr usb_lookup_ep_data 9F ,
55device drivers should call the
56.Xr usb_ep_xdescr_fill 9F
57function. After that, the
58.Sy usb_ep_xdescr_t
59structure will be filled in.
60.Sh STRUCTURE MEMBERS
61The
62.Sy usb_ep_xdescr_t
63structure has the following members:
64.Bd -literal -offset indent
65uint_t			uex_version;
66usb_ep_xdescr_flags_t	uex_flags;
67usb_ep_descr_t		uex_ep;
68usb_ep_ss_comp_descr_t	uex_ep_ss;
69.Ed
70.Pp
71The
72.Sy uex_version
73member is used to describe the current version of this structure. This
74member will be set to the value passed in by the device driver to
75.Xr usb_ep_xdescr_fil 9F .
76Device drivers should ignore this field and should not modify the value
77placed there or modify it.
78.Pp
79The
80.Sy uex_flags
81member is an enumeration that defines a number of flags. Each flag
82indicates whether or not a given member is present or valid. Before
83accessing any member other than
84.Sy uex_ep ,
85the device driver should check the flag here, otherwise its contents may
86be undefined. Currently the following flags are defined:
87.Bl -tag -width Sy -offset indent
88.It Sy USB_EP_XFLAGS_SS_COMP
89Indicates that a SuperSpeed endpoint companion descriptor is present and
90has been filled in. The member
91.Sy uex_ep_ss
92is valid.
93.El
94.Pp
95The
96.Sy uex_ep
97member contains a traditional USB endpoint descriptor. Its contents are
98defined in
99.Xr usb_ep_descr 9S .
100There is no flag for this member in
101.Sy uex_flags ,
102it is always valid.
103.Pp
104The
105.Sy uex_ep_ss
106member contains a USB 3.0 SuperSpeed endpoint companion descriptor as
107defined in
108.Xr usb_ep_ss_comp_descr 9S .
109This member is only valid if the
110.Sy USB_EP_XFLAGS_SS_COMP
111flag is specified in
112.Sy uex_flags .
113.Sh SEE ALSO
114.Xr usb_ep_xdescr_fill 9F ,
115.Xr usb_pipe_xopen 9F ,
116.Xr usb_ep_descr 9S ,
117.Xr usb_ep_ss_comp_descr 9S
118