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. 32It may be removed 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. 40Valid flags are: 41.Bl -tag -width Sy 42.It Sy USB_FLAGS_NOSLEEP 43Do not block waiting for memory. 44If memory is not available the allocation will fail. 45.It Sy USB_FLAGS_SLEEP 46Perform a blocking allocation. 47If memory is not available, the function will wait until memory is made 48available. 49.Pp 50Note, the request may still fail even if 51.Sy USB_FLAGS_SLEEP 52is specified. 53.El 54.El 55.Sh DESCRIPTION 56The 57.Fn usba_hcdi_pipe_reset 58entry point is designed to take a pipe in an arbitrary state and return 59it to the same state it was in after a call to 60.Xr usba_hcdi_pipe_open 9E . 61While this entry point does some similar things to the 62.Xr usba_hcdi_stop_intr_polling 9E 63and 64.Xr usba_hcdi_stop_isoc_polling 9E 65entry points, there are some notable differences. 66.Pp 67This entry point is synchronous. 68The host controller driver should take the following steps on the pipe before 69returning: 70.Bl -enum 71.It 72Quiesce and stop the endpoint. 73.It 74If the endpoint has any errors they should be cleared at this time. 75.It 76Remove any remaining, scheduled or queued transfers. 77For each one call 78.Xr usba_hcdi_cb 9F 79with the code 80.Sy USB_CR_PIPE_RESET . 81.It 82Perform any other necessary steps on the controller to have the endpoint 83be ready to perform I/O. 84.El 85.Pp 86This entry point is called by the broader USBA framework as part of 87closing a pipe or in response to a device stall. 88.Sh RETURN VALUES 89Upon successful completion, the 90.Fn usba_hcdi_pipe_reset 91function should return 92.Sy USB_SUCCESS . 93Otherwise, it should return the appropriate USB error. 94If uncertain, use 95.Sy USB_FAILURE . 96.Sh SEE ALSO 97.Xr usba_hcdi_pipe_open 9E , 98.Xr usba_hcdi_stop_intr_polling 9E , 99.Xr usba_hcdi_stop_isoc_polling 9E , 100.Xr usba_hcdi_cb 9F , 101.Xr usba_pipe_handle_data 9S 102