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