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