1usb_pipe_open(9F) Kernel Functions for Drivers usb_pipe_open(9F)
2
6 usb_pipe_open - Open a USB pipe to a device
7
9 #include <sys/usb/usba.h>
10 int usb_pipe_open(dev_info_t *dip, usb_ep_descr_t *endpoint,
14 usb_pipe_policy_t *pipe_policy,
15 usb_flags_t flags, usb_pipe_handle_t *pipe_handle);
16
19 Solaris DDI specific (Solaris DDI)
20
22 dip Pointer to the device's dev_info structure.
23 endpoint Pointer to endpoint descriptor.
26 pipe_policy Pointer to pipe_policy. pipe_policy provides hints on
29 pipe usage.
30 flags USB_FLAGS_SLEEP is only flag that is recognized. Wait
33 for memory resources if not immediately available.
34 pipe_handle Address to where new pipe handle is returned. (The han‐
37 dle is opaque.)
38
41 A pipe is a logical connection to an endpoint on a USB device. The
42 usb_pipe_open() function creates such a logical connection and returns
43 an initialized handle which refers to that connection.
44 The USB 2.0 specification defines four endpoint types, each with a cor‐
47 responding type of pipe. Each of the four types of pipes uses its phys‐
48 ical connection resource differently. They are:
49 Control pipe Used for bursty, non-periodic, reliable, host-ini‐
51 tiated request/response communication, such as for
52 command/status operations. These are guaranteed to
53 get approximately 10% of frame time and will get
54 more if needed and if available, but there is no
55 guarantee on transfer promptness. Bidirectional.
56 Bulk pipe Used for large, reliable, non-time-critical data
59 transfers. These get the bus on a bandwidth-avail‐
60 able basis. Unidirectional. Sample uses include
61 printer data.
62 Interrupt pipe Used for sending or receiving small amounts of
65 reliable data infrequently but with bounded service
66 periods, as for interrupt handling. Unidirectional.
67 Isochronous pipe Used for large, unreliable, time-critical data
70 transfers. Boasts a guaranteed constant data rate
71 as long as there is data, but there are no retries
72 of failed transfers. Interrupt and isochronous data
73 are together guaranteed 90% of frame time as
74 needed. Unidirectional. Sample uses include audio.
75 The type of endpoint to which a pipe connects (and therefore the pipe
79 type) is defined by the bmAttributes field of that pipe's endpoint
80 descriptor. (See usb_ep_descr(9S)). Opens to interrupt and isochronous
81 pipes can fail if the required bandwidth cannot be guaranteed.
82 The polling interval for periodic (interrupt or isochronous) pipes,
85 carried by the endpoint argument's bInterval field, must be within
86 range. Valid ranges are:
87 Full speed: range of 1-255 maps to 1-255 ms.
90 Low speed: range of 10-255 maps to 10-255 ms.
93 High speed: range of 1-16 maps to (2**(bInterval-1)) * 125us.
96 Adequate bandwidth during transfers is guaranteed for all periodic
99 pipes which are opened successfully. Interrupt and isochronous pipes
100 have guaranteed latency times, so bandwidth for them is allocated when
101 they are opened. (Please refer to Sections 5.7 and 5.8 of the USB 2.0
102 specification which address isochronous and interrupt transfers.) Opens
103 of interrupt and isochronous pipes fail if inadequate bandwidth is
104 available to support their guaranteed latency time. Because periodic
105 pipe bandwidth is allocated on pipe open, open periodic pipes only when
106 needed.
107 The bandwidth required by a device varies based on polling interval,
110 the maximum packet size (wMaxPacketSize) and the device speed. Unallo‐
111 cated bandwidth remaining for new devices depends on the bandwidth
112 already allocated for previously opened periodic pipes.
113 The pipe_policy parameter provides a hint as to pipe usage and must be
116 specified. It is a usb_pipe_policy_t which contains the following
117 fields:
118 uchar_t pp_max_async_reqs:
120 A hint indicating how many
121 asynchronous operations requiring
122 their own kernel thread will be
123 concurrently in progress, the highest
124 number of threads ever needed at one
125 time. Allow at least one for
126 synchronous callback handling and as
127 many as are needed to accommodate the
128 anticipated parallelism of asynchronous*
129 calls to the following functions:
130 usb_pipe_close(9F)
131 usb_set_cfg(9F)
132 usb_set_alt_if(9F)
133 usb_clr_feature(9F)
134 usb_pipe_reset(9F)
135 usb_pipe_drain_reqs(9F)
136 usb_pipe_stop_intr_polling(9F)
137 usb_pipe_stop_isoc_polling(9F)
138 Setting to too small a value can
139 deadlock the pipe.
140 * Asynchronous calls are calls made
142 without the USB_FLAGS_SLEEP flag being
143 passed. Note that a large number of
144 callbacks becomes an issue mainly when
145 blocking functions are called from
146 callback handlers.
147 The control pipe to the default endpoints (endpoints for both direc‐
151 tions with addr 0, sometimes called the default control pipe or default
152 pipe) comes pre-opened by the hub. A client driver receives the default
153 control pipe handle through usb_get_dev_data(9F). A client driver can‐
154 not open the default control pipe manually. Note that the same control
155 pipe may be shared among several drivers when a device has multiple
156 interfaces and each interface is operated by its own driver.
157 All explicit pipe opens are exclusive; attempts to open an opened pipe
160 fail.
161 On success, the pipe_handle argument points to an opaque handle of the
164 opened pipe. On failure, it is set to NULL.
165
167 USB_SUCCESS Open succeeded.
168 USB_NO_RESOURCES Insufficient resources were available.
171 USB_NO_BANDWIDTH Insufficient bandwidth available. (isochronous
174 and interrupt pipes).
175 USB_INVALID_CONTEXT Called from interrupt handler with
178 USB_FLAGS_SLEEP set.
179 USB_INVALID_ARGS dip and/or pipe_handle is NULL. Pipe_policy is
182 NULL.
183 USB_INVALID_PERM Endpoint is NULL, signifying the default con‐
186 trol pipe. A client driver cannot open the
187 default control pipe.
188 USB_NOT_SUPPORTED Isochronous or interrupt endpoint with maximum
191 packet size of zero is not supported.
192 USB_HC_HARDWARE_ERROR Host controller is in an error state.
195 USB_FAILURE Pipe is already open. Host controller not in
198 an operational state. Polling interval
199 (ep_descr bInterval field) is out of range
200 (intr or isoc pipes).
201
204 May be called from user or kernel context regardless of arguments. May
205 also be called from interrupt context if the USB_FLAGS_SLEEP option is
206 not set.
207
209 usb_ep_data_t *ep_data;
210 usb_pipe_policy_t policy;
211 usb_pipe_handle_t pipe;
212 usb_client_dev_data_t *reg_data;
213 uint8_t interface = 1;
214 uint8_t alternate = 1;
215 uint8_t first_ep_number = 0;
216 /* Initialize pipe policy. */
218 bzero(policy, sizeof(usb_pipe_policy_t));
219 policy.pp_max_async_requests = 2;
220 /* Get tree of descriptors for device. */
222 if (usb_get_dev_data(
223 dip, USBDRV_VERSION, ®_data, USB_FLAGS_ALL_DESCR, 0) !=
224 USB_SUCCESS) {
225 ...
226 }
227 /* Get first interrupt-IN endpoint. */
229 ep_data = usb_lookup_ep_data(dip, reg_data, interface, alternate,
230 first_ep_number, USB_EP_ATTR_INTR, USB_EP_DIR_IN);
231 if (ep_data == NULL) {
232 ...
233 }
234 /* Open the pipe. Get handle to pipe back in 5th argument. */
236 if (usb_pipe_open(dip, &ep_data.ep_descr
237 &policy, USB_FLAGS_SLEEP, &pipe) != USB_SUCCESS) {
238 ...
239 }
240
243 See attributes(5) for descriptions of the following attributes:
244 ┌─────────────────────────────┬─────────────────────────────┐
249 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
250 ├─────────────────────────────┼─────────────────────────────┤
251 │Architecture │PCI-based systems │
252 ├─────────────────────────────┼─────────────────────────────┤
253 │Interface stability │Committed │
254 ├─────────────────────────────┼─────────────────────────────┤
255 │Availability │SUNWusb │
256 └─────────────────────────────┴─────────────────────────────┘
257
259 attributes(5), usb_get_alt_if(9F), usb_get_cfg(9F), usb_get_status(9F),
260 usb_get_dev_data(9F), usb_pipe_bulk_xfer(9F), usb_pipe_ctrl_xfer(9F),
261 usb_pipe_close(9F), usb_pipe_get_state(9F), usb_pipe_intr_xfer(9F),
262 usb_pipe_isoc_xfer(9F), usb_pipe_reset(9F), usb_pipe_set_private(9F),
263 usb_ep_descr(9S), usb_callback_flags(9S)
264SunOS 5.11 5 Jan 2004 usb_pipe_open(9F)