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