| blob | ba3f4e06b00c3ad065a052b5848b1c5e033dd903 |
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 10, 2016
15 .Dt USB_EP_SS_COMP_DESCR 9S
16 .Os
17 .Sh NAME
18 .Nm usb_ep_ss_comp_descr ,
19 .Nm usb_ep_ss_comp_descr_t
20 .Nd USB endpoint SuperSpeed Companion Descriptor
21 .Sh SYNOPSIS
22 .In sys/usb/usba.h
23 .Sh INTERFACE LEVEL
24 illumos DDI Specific
25 .Sh DESCRIPTION
26 The
27 .Sy usb_ep_ss_comp_descr_t
28 structure defines additional endpoint attributes for USB 3.0 and newer
29 devices.
30 This structure is considered a
31 .Em companion descriptor .
32 On its own, it does not uniquely define an endpoint.
33 A standard USB descriptor is still required.
34 See
35 .Xr usb_ep_descr 9S
36 for the definition of the standard descriptor.
37 .Pp
38 If available, the SuperSpeed companion descriptor can be accessed by
39 getting the endpoint data through a call to
40 .Xr usb_lookup_ep_data 9F .
41 These descriptors are required to open pipes for USB 3.0 and newer
42 devices.
43 They can be assembled into the proper format for
44 .Xr usb_pipe_xopen 9F
45 by calling
46 .Xr usb_ep_xdescr_fill 9F .
47 .Pp
48 This structure is formally defined in section 9.6.7 of the USB 3.1
49 specification.
50 .Sh STRUCTURE MEMBERS
51 .Bd -literal -offset indent
52 uint8_t bLength;
53 uint8_t bDescriptorType;
54 uint8_t bMaxBurst;
55 uint8_t bmAttributes;
56 uint16_t wBytesPerInterval;
57 .Ed
58 .Pp
59 The
60 .Sy bLength
61 member is always set to the size of this descriptor, which is usually
62 six.
63 .Pp
64 The
65 .Sy bDescriptorType
66 member should be set to the macro
67 .Sy USB_DESCR_TYPE_SS_EP_COMP
68 whose value is 0x30.
69 .Pp
70 The
71 .Sy bMaxBurst
72 member indicates the maximum number of packets that the endpoint can
73 send in one 'burst'.
74 Valid values range from 0 to 15 and the values are one less than the number of
75 packets.
76 A value of 0 indicates that 1 packet can be sent in a burst.
77 A value of 15 indicates that 16 packets can be sent in a burst.
78 .Pp
79 The
80 .Sy bmAttributes
81 member indicates different attributes of the endpoint.
82 This member is reserved and should be zero for
83 .Sy control
84 and
85 .Sy interrupt
86 endpoints.
87 .Pp
88 For a
89 .Sy bulk
90 endpoint, the
91 .Sy bmAttributes
92 member is used to indicate the maximum number of streams that the device
93 supports.
94 The first five bits (4:0) are used, the remaining 3 bits are reserved and should
95 be zero.
96 Values range from 0 to 16.
97 A value of zero indicates that streams are not supported.
98 Otherwise, it indicates that the device supports 2 raised to the value number of
99 streams.
100 A value of 3, indicates 2^3 streams are supported.
101 .Pp
102 For an
103 .Sy isochronous
104 endpoint, the
105 .Sy bmAttributes
106 member is used to indicate the value of the
107 .Sy Mult
108 property, a value used to calculate the maximum number of packets the
109 device and receive in a service interval.
110 The first two bits (1:0) are used to determine the mult.
111 The remaining 6 bits (7:2) are reserved and should be set to zero.
112 .Pp
113 The
114 .Sy wBytesPerInterval
115 member is used to indicate the total number of bytes that can be
116 transferred in one service interval.
117 Note, this is only valid for
118 .Sy Isochronous
119 and
120 .Sy Interrupt IN
121 (periodic) endpoints.
122 .Sh SEE ALSO
123 .Xr usb_ep_xdescr_fill 9F ,
124 .Xr usb_pipe_xopen 9F ,
125 .Xr usb_ep_descr 9S ,
126 .Xr usb_ep_xdescr 9S
127 .Rs
128 .%T Universal Serial Bus 3.1 Specification
129 .%U www.usb.org
130 .Re