Print this page
12309 errors in section 9e of the manual
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man9e/usba_hcdi_pipe_open.9e
+++ new/usr/src/man/man9e/usba_hcdi_pipe_open.9e
1 1 .\"
2 2 .\" This file and its contents are supplied under the terms of the
3 3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
|
↓ open down ↓ |
3 lines elided |
↑ open up ↑ |
4 4 .\" You may only use this file in accordance with the terms of version
5 5 .\" 1.0 of the CDDL.
6 6 .\"
7 7 .\" A full copy of the text of the CDDL should have accompanied this
8 8 .\" source. A copy of the CDDL is also available via the Internet at
9 9 .\" http://www.illumos.org/license/CDDL.
10 10 .\"
11 11 .\"
12 12 .\" Copyright 2016 Joyent, Inc.
13 13 .\"
14 -.Dd Nov 26, 2017
14 +.Dd February 15, 2020
15 15 .Dt USBA_HCDI_PIPE_OPEN 9E
16 16 .Os
17 17 .Sh NAME
18 18 .Nm usba_hcdi_pipe_open ,
19 19 .Nm usba_hcdi_pipe_close
20 20 .Nd open and close a USB pipe
21 21 .Sh SYNOPSIS
22 22 .In sys/usb/usba/hcdi.h
23 23 .Ft int
24 24 .Fo prefix_hcdi_pipe_open
25 25 .Fa "usba_pipe_handle_data_t *ph"
26 26 .Fa "usb_flags_t usb_flags"
27 27 .Fc
28 28 .Ft int
29 29 .Fo prefix_hcdi_pipe_close
30 30 .Fa "usba_pipe_handle_data_t *ph"
31 31 .Fa "usb_flags_t usb_flags"
32 32 .Fc
33 33 .Sh INTERFACE LEVEL
34 34 .Sy Volatile -
35 35 illumos USB HCD private function
36 36 .Pp
37 37 This is a private function that is not part of the stable DDI.
38 38 It may be removed or changed at any time.
39 39 .Sh PARAMETERS
40 40 .Bl -tag -width Fa
41 41 .It Fa ph
42 42 A pointer to a USB pipe handle as defined in
43 43 .Xr usba_pipe_handle_data 9S .
44 44 .It Fa usb_flags
45 45 Flags which describe how allocations should be performed.
46 46 Valid flags are:
47 47 .Bl -tag -width Sy
48 48 .It Sy USB_FLAGS_NOSLEEP
49 49 Do not block waiting for memory.
50 50 If memory is not available the allocation will fail.
51 51 .It Sy USB_FLAGS_SLEEP
52 52 Perform a blocking allocation.
53 53 If memory is not available, the function will wait until memory is made
54 54 available.
55 55 .Pp
56 56 Note, the request may still fail even if
57 57 .Sy USB_FLAGS_SLEEP
58 58 is specified.
59 59 .El
60 60 .El
61 61 .Sh DESCRIPTION
62 62 The
63 63 .Fn usba_hcdi_pipe_open
64 64 and
65 65 .Fn usba_hcdi_pipe_close
66 66 entry points are called by the USB framework whenever a client, or the
67 67 framework itself, need to open or close a specific pipe.
68 68 For additional background see
69 69 .Xr usba_hcdi 9E .
70 70 .Pp
71 71 When a pipe is opened, the host controller driver is responsible for
72 72 preparing the specified endpoint for performing transfers.
73 73 This may include allocating bandwidth, programming the controller, and more.
74 74 When the pipe is closed, the host controller driver is responsible for
75 75 cleaning up any resources that were allocated during the open call.
76 76 .Pp
77 77 The pipe handle,
78 78 .Fa ph ,
79 79 identifies the endpoint that it the USBA is trying to open or close
80 80 through its endpoint descriptor in the
81 81 .Sy p_ep
82 82 member.
83 83 The endpoint descriptor is described in
84 84 .Xr usb_ep_descr 9S .
85 85 From the endpoint descriptor the driver can determine the type of
86 86 endpoint, what the address of the endpoint is, and what direction the
87 87 endpoint is in.
88 88 When combined, these uniquely describe the pipe.
89 89 .Pp
90 90 To open a pipe, the driver may need additional companion endpoint
91 91 descriptors.
92 92 If these are available, they will be in the
93 93 .Sy p_xep
94 94 member of the pipe handle.
95 95 See
96 96 .Xr usb_ep_xdescr 9S
97 97 for more information on how to determine which descriptors are present
98 98 and get the information encoded in them.
99 99 .Pp
100 100 Host controller drivers should check the USB address of the
101 101 USB device that
102 102 .Fa ph
103 103 belongs to.
104 104 The driver may be asked to open a pipe to the root hub.
105 105 As the root hub is often synthetic, the driver may need to take a different
106 106 path than normal.
107 107 .Ss Pipe open specifics
108 108 A given endpoint on a device can only be opened once.
109 109 If there's a request to open an already open endpoint, then the request to open
110 110 the pipe should be failed.
111 111 .Pp
112 112 By the time the call to open a pipe returns, the driver should expect
113 113 that any of the pipe transfer or reset entry points will be called on
114 114 the pipe.
115 115 .Pp
116 116 A driver can establish private data on an endpoint.
117 117 During pipe open it may set the
|
↓ open down ↓ |
93 lines elided |
↑ open up ↑ |
118 118 .Sy p_hcd_private
119 119 member to any value.
120 120 Generally this points to an allocated structure that contains data specific to
121 121 the host controller.
122 122 This value will remain on the pipe handle.
123 123 It is the responsibility of the driver to clear the data when the pipe is
124 124 closed.
125 125 .Ss Pipe close specifics
126 126 When a pipe is closed, the driver must clean up all of the resources
127 127 that it allocated when opening the pipe.
128 -For non-periodic transfers, the host controller driver may assueme that there
128 +For non-periodic transfers, the host controller driver may assume that there
129 129 are no outstanding transfers that need to be cleaned up.
130 130 However, the same is not true for periodic pipes.
131 131 .Pp
132 132 For pipes that have outstanding periodic transfers, the host controller
133 133 driver needs to clean them up and quiesce them as though a call to
134 134 either
135 135 .Xr usba_hcdi_pipe_stop_intr_polling 9E
136 136 or
137 137 .Xr usba_hcdi_pipe_stop_isoc_polling 9E
138 138 had been called.
139 139 .Pp
140 140 Just as with opening the pipe, the driver should pay attention to the
141 141 address of the USB device, as it may be the root hub, which may be a
142 142 synthetic pipe.
143 143 .Pp
144 144 When a call to
145 145 .Fn usba_hcdi_pipe_close
146 146 completes, the device should be in a state that the pipe can be opened
147 147 again.
148 148 .Sh RETURN VALUES
149 149 Upon successful completion, the
150 150 .Fn usba_hcdi_pipe_open
151 151 and
152 152 .Fn uba_hcdi_pipe_close
153 153 functions should return
154 154 .Sy USB_SUCCESS .
155 155 Otherwise, it should return the appropriate USB error.
156 156 If uncertain, use
157 157 .Sy USB_FAILURE .
158 158 .Sh SEE ALSO
159 159 .Xr usba_hcdi 9E ,
160 160 .Xr usba_hcdi_pipe_stop_intr_polling 9E ,
161 161 .Xr usba_hcdi_pipe_stop_isoc_polling 9E ,
162 162 .Xr usb_ep_descr 9S ,
163 163 .Xr usb_ep_xdescr 9S ,
164 164 .Xr usba_pipe_handle_data 9S
|
↓ open down ↓ |
26 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX