1.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved 2.\" Copyright 2016 Joyent, Inc. 3.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. 4.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. 5.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] 6.Dd Sep 16, 2016 7.Dt USB_PIPE_XOPEN 9F 8.Os 9.Sh NAME 10.Nm usb_pipe_open , 11.Nm usb_pipe_xopen 12.Nd Open a USB pipe to a device 13.Sh SYNOPSIS 14.In sys/usb/usba.h 15.Ft int 16.Fo usb_pipe_open 17.Fa "dev_info_t *dip" 18.Fa "usb_ep_descr_t *endpoint" 19.Fa "usb_pipe_policy_t *pipe_policy" 20.Fa "usb_flags_t flags" 21.Fa "usb_pipe_handle_t *pipe_handle" 22.Fc 23.Ft int 24.Fo usb_pipe_xopen 25.Fa "dev_info_t *dip" 26.Fa "usb_ep_xdescr_t *extended_endpoint" 27.Fa "usb_pipe_policy_t *pipe_policy" 28.Fa "usb_flags_t flags" 29.Fa "usb_pipe_handle_t *pipe_handle" 30.Fc 31.Sh INTERFACE LEVEL 32Solaris DDI specific (Solaris DDI) 33.Sh PARAMETERS 34.Bl -tag -width Fa 35.It Fa dip 36Pointer to the device's 37.Sy dev_info 38structure. 39.It Fa endpoint 40Pointer to endpoint descriptor. 41.It Fa extended_endpoint 42Pointer to an extended endpoint descriptor retrieved from calling 43.Xr usb_ep_xdescr_fill 9F . 44.It Fa pipe_policy 45Pointer to 46.Em pipe_policy. 47.Em pipe_policy 48provides hints on pipe usage. 49.It Fa flags 50.Sy USB_FLAGS_SLEEP 51is only flag that is recognized. Wait for memory resources if 52not immediately available. 53.It Fa pipe_handle 54Address to where new pipe handle is returned. (The handle is opaque.) 55.El 56.Sh DESCRIPTION 57A pipe is a logical connection to an endpoint on a USB device. The 58.Fn usb_pipe_xopen 59function creates such a logical connection and returns an 60initialized handle which refers to that connection. 61.Pp 62The 63.Em USB 3.0 64specification defines four endpoint types, each with a 65corresponding type of pipe. Each of the four types of pipes uses its physical 66connection resource differently. They are: 67.Bl -tag -width Sy 68.It Sy Control Pipe 69Used for bursty, non-periodic, reliable, host-initiated request/response 70communication, such as for command/status operations. These are guaranteed to 71get approximately 10% of frame time and will get more if needed and if 72available, but there is no guarantee on transfer promptness. Bidirectional. 73.It Sy Bulk Pipe 74Used for large, reliable, non-time-critical data transfers. These get the bus 75on a bandwidth-available basis. Unidirectional. Sample uses include printer 76data. 77.It Sy Interrupt Pipe 78Used for sending or receiving small amounts of reliable data infrequently but 79with bounded service periods, as for interrupt handling. Unidirectional. 80.It Sy Isochronous Pipe 81Used for large, unreliable, time-critical data transfers. Boasts a guaranteed 82constant data rate as long as there is data, but there are no retries of failed 83transfers. Interrupt and isochronous data are together guaranteed 90% of frame 84time as needed. Unidirectional. Sample uses include audio. 85.El 86.Pp 87The type of endpoint to which a pipe connects (and therefore the pipe type) is 88defined by the 89.Sy bmAttributes 90field of that pipe's endpoint descriptor. 91.Po 92See 93.Xr usb_ep_descr 9S 94.Pc . 95.Pp 96Prior to the 97.Em USB 3.0 98specification, only the 99.Xr usb_ep_descr 9S 100was required to identify all of the attributes of a given pipe. Starting 101with 102.Em USB 3.0 103there are additional endpoint companion descriptors required to open a 104pipe. To support SuperSpeed devices, the new 105.Fn usb_pipe_xopen 106function must be used rather than the older 107.Fn usb_pipe_open 108function. The 109.Xr usb_ep_xdescr 9S 110structure can be automatically filled out and obtained by calling the 111.Xr usb_ep_xdescr_fill 9F 112function. 113.Pp 114Opens to interrupt and isochronous pipes can fail 115if the required bandwidth cannot be guaranteed. 116.Pp 117The polling interval for periodic (interrupt or isochronous) pipes, carried by 118the endpoint argument's bInterval field, must be within range. Valid ranges 119are: 120.Pp 121Full speed: range of 1-255 maps to 1-255 ms. 122.Pp 123Low speed: range of 10-255 maps to 10-255 ms. 124.Pp 125High speed: range of 1-16 maps to (2**(bInterval-1)) * 125us. 126.Pp 127Super speed: range of 1-16 maps to (2**(bInterval-1)) * 125us. 128.Pp 129Adequate bandwidth during transfers is guaranteed for all periodic pipes which 130are opened successfully. Interrupt and isochronous pipes have guaranteed 131latency times, so bandwidth for them is allocated when they are opened. 132.Po 133Please 134refer to Sections 135.Em 4.4.7 136and 137.Em 4.4.8 138of the 139.Em USB 3.1 140specification 141which address isochronous and interrupt transfers. 142.Pc 143Opens of interrupt and isochronous pipes fail if inadequate bandwidth is 144available to support their guaranteed latency time. Because periodic 145pipe bandwidth is allocated on pipe open, open periodic pipes only when 146needed. 147.Pp 148The bandwidth required by a device varies based on polling interval, the 149maximum packet size 150.Pq Sy wMaxPacketSize 151and the device speed. Unallocated 152bandwidth remaining for new devices depends on the bandwidth already allocated 153for previously opened periodic pipes. 154.Pp 155The 156.Em pipe_policy 157parameter provides a hint as to pipe usage and must be 158specified. It is a 159.Em usb_pipe_policy_t 160which contains the following fields: 161.Bd -literal -offset indent 162uchar_t pp_max_async_reqs: 163.Ed 164.Pp 165The 166.Sy pp_max_async_reqs 167member is a hint indicating how many asynchronous operations requiring 168their own kernel thread will be concurrently in progress, the highest 169number of threads ever needed at one time. Allow at least one for 170synchronous callback handling and as many as are needed to accommodate 171the anticipated parallelism of asynchronous* calls to the following 172functions: 173.Xr usb_pipe_close 9F , 174.Xr usb_set_cfg 9F , 175.Xr usb_set_alt_if 9F , 176.Xr usb_clr_feature 9F , 177.Xr usb_pipe_reset 9F , 178.Xr usb_pipe_drain_reqs 9F , 179.Xr usb_pipe_stop_intr_polling 9F , 180and 181.Xr usb_pipe_stop_isoc_polling 9F . 182.Pp 183Setting to too small a value can deadlock the pipe. Asynchronous calls 184are calls made without the 185.Sy USB_FLAGS_SLEEP 186flag being passed. Note that 187a large number of callbacks becomes an issue mainly when blocking 188functions are called from callback handlers. 189.Pp 190The control pipe to the default endpoints (endpoints for both directions with 191addr 0, sometimes called the default control pipe or default pipe) comes 192pre-opened by the hub. A client driver receives the default control pipe handle 193through 194.Xr usb_get_dev_data 9F . 195A client driver cannot open the default 196control pipe manually. Note that the same control pipe may be shared among 197several drivers when a device has multiple interfaces and each interface is 198operated by its own driver. 199.Pp 200All explicit pipe opens are exclusive; attempts to open an opened pipe fail. 201.Pp 202On success, the pipe_handle argument points to an opaque handle of the opened 203pipe. On failure, it is set to NULL. 204.Sh CONTEXT 205May be called from user or kernel context regardless of arguments. May also be 206called from interrupt context if the 207.Sy USB_FLAGS_SLEEP 208option is not set. 209.Sh RETURN VALUES 210.Bl -tag -width Sy 211.It Sy USB_SUCCESS 212Open succeeded. 213.It Sy USB_NO_RESOURCES 214Insufficient resources were available. 215.It Sy USB_NO_BANDWIDTH 216Insufficient bandwidth available. (isochronous and interrupt pipes). 217.It Sy USB_INVALID_CONTEXT 218Called from interrupt handler with USB_FLAGS_SLEEP set. 219.It Sy USB_INVALID_ARGS 220dip and/or pipe_handle is NULL. Pipe_policy is NULL. 221.It Sy USB_INVALID_PERM 222Endpoint is NULL, signifying the default control pipe. A client driver cannot 223open the default control pipe. 224.It Sy USB_NOT_SUPPORTED 225Isochronous or interrupt endpoint with maximum packet size of zero is not 226supported. 227.It Sy USB_HC_HARDWARE_ERROR 228Host controller is in an error state. 229.It Sy USB_FAILURE 230Pipe is already open. Host controller not in an operational state. Polling 231interval 232.Pq Sy Bep_descr bInterval No field 233is out of range (intr or isoc pipes). 234.Pp 235The device referred to by 236.Fa dip 237is at least a SuperSpeed device and the older 238.Fn usb_pipe_open 239function was used. 240.El 241.Sh EXAMPLES 242.Bd -literal -offset indent 243usb_ep_data_t *ep_data; 244usb_ep_xdescr_t ep_xdescr; 245usb_pipe_policy_t policy; 246usb_pipe_handle_t pipe; 247usb_client_dev_data_t *reg_data; 248uint8_t interface = 1; 249uint8_t alternate = 1; 250uint8_t first_ep_number = 0; 251 252/* Initialize pipe policy. */ 253bzero(policy, sizeof(usb_pipe_policy_t)); 254policy.pp_max_async_requests = 2; 255 256/* Get tree of descriptors for device. */ 257if (usb_get_dev_data(dip, USBDRV_VERSION, ®_data, 258 USB_FLAGS_ALL_DESCR, 0) != USB_SUCCESS) { 259 ... 260} 261 262/* Get first interrupt-IN endpoint. */ 263ep_data = usb_lookup_ep_data(dip, reg_data, interface, alternate, 264 first_ep_number, USB_EP_ATTR_INTR, USB_EP_DIR_IN); 265if (ep_data == NULL) { 266 ... 267} 268 269/* Translate the ep_data into the filled in usb_ep_xdescr_t */ 270if (usb_ep_xdescr_fill(USB_EP_XDESCR_CURRENT_VERSION, dip, 271 ep_data, &ep_xdescr) != USB_SUCCESS) { 272 ... 273} 274 275/* Open the pipe. Get handle to pipe back in 5th argument. */ 276if (usb_pipe_open(dip, &ep_data.ep_descr 277 &policy, USB_FLAGS_SLEEP, &pipe) != USB_SUCCESS) { 278 ... 279} 280.Ed 281.Sh SEE ALSO 282.Xr usb_get_alt_if 9F , 283.Xr usb_get_cfg 9F , 284.Xr usb_get_dev_data 9F , 285.Xr usb_get_status 9F , 286.Xr usb_pipe_bulk_xfer 9F , 287.Xr usb_pipe_close 9F , 288.Xr usb_pipe_ctrl_xfer 9F , 289.Xr usb_pipe_get_state 9F , 290.Xr usb_pipe_intr_xfer 9F , 291.Xr usb_pipe_isoc_xfer 9F , 292.Xr usb_pipe_reset 9F , 293.Xr usb_pipe_set_private 9F , 294.Xr usb_callback_flags 9S , 295.Xr usb_ep_descr 9S 296.Rs 297.%T Universal Serial Bus 3.1 Specification 298.%U http://www.usb.org 299.Re 300