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 22, 2016 15.Dt USBA_HCDI_PIPE_RESET 9E 16.Os 17.Sh NAME 18.Nm usba_hcdi_pipe_rest 19.Nd reset an open USB pipe 20.Sh SYNOPSIS 21.In sys/usb/usba/hcdi.h 22.Ft int 23.Fo prefix_hcdi_pipe_reset 24.Fa "usba_pipe_handle_data_t *ph" 25.Fa "usb_flags_t usb_flags" 26.Fc 27.Sh INTERFACE LEVEL 28.Sy Volatile - 29illumos USB HCD private function 30.Pp 31This is a private function that is not part of the stable DDI. It may be 32removed or changed at any time. 33.Sh PARAMETERS 34.Bl -tag -width Fa 35.It Fa ph 36A pointer to a USB pipe handle as defined in 37.Xr usba_pipe_handle_data 9S . 38.It Fa usb_flags 39Flags which describe how allocations should be performed. Valid flags 40are: 41.Bl -tag -width Sy 42.It Sy USB_FLAGS_NOSLEEP 43Do not block waiting for memory. If memory is not available the allocation 44will fail. 45.It Sy USB_FLAGS_SLEEP 46Perform a blocking allocation. If memory is not available, the function 47will wait until memory is made available. 48.Pp 49Note, the request may still fail even if 50.Sy USB_FLAGS_SLEEP 51is specified. 52.El 53.El 54.Sh DESCRIPTION 55The 56.Fn usba_hcdi_pipe_reset 57entry point is designed to take a pipe in an arbitrary state and return 58it to the same state it was in after a call to 59.Xr usba_hcdi_pipe_open 9E . 60While this entry point does some similar things to the 61.Xr usba_hcdi_stop_intr_polling 9E 62and 63.Xr usba_hcdi_stop_isoc_polling 9E 64entry points, there are some notable differences. 65.Pp 66This entry point is synchronous. The host controller driver should take 67the following steps on the pipe before returning: 68.Bl -enum 69.It 70Quiesce and stop the endpoint. 71.It 72If the endpoint has any errors they should be cleared at this time. 73.It 74Remove any remaining, scheduled or queued transfers. For each one call 75.Xr usba_hcdi_cb 9F 76with the code 77.Sy USB_CR_PIPE_RESET . 78.It 79Perform any other necessary steps on the controller to have the endpoint 80be ready to perform I/O. 81.El 82.Pp 83This entry point is called by the broader USBA framework as part of 84closing a pipe or in response to a device stall. 85.Sh RETURN VALUES 86Upon successful completion, the 87.Fn usba_hcdi_pipe_reset 88function should return 89.Sy USB_SUCCESS . 90Otherwise, it should return the appropriate USB error. If uncertain, use 91.Sy USB_FAILURE . 92.Sh SEE ALSO 93.Xr usba_hcdi_pipe_open 9E , 94.Xr usba_hcdi_stop_intr_polling 9E , 95.Xr usba_hcdi_stop_isoc_polling 9E , 96.Xr usba_hcdi_cb 9F , 97.Xr usba_pipe_handle_data 9S 98