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_STOP_INTR_POLLING 9E 16.Os 17.Sh NAME 18.Nm usba_hcdi_pipe_stop_intr_polling , 19.Nm usba_hcdi_pipe_stop_isoc_polling 20.Nd stop polling on an interrupt or isochronous pipe 21.Sh SYNOPSIS 22.In sys/usb/usba/hcdi.h 23.Ft int 24.Fo prefix_hcdi_pipe_stop_intr_polling 25.Fa "usba_pipe_handle_data_t *ph" 26.Fa "usba_flags_t usb_flags" 27.Fc 28.Ft int 29.Fo prefix_hcdi_pipe_stop_isoc_polling 30.Fa "usba_pipe_handle_data_t *ph" 31.Fa "usba_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_stop_intr_polling 64and 65.Fn usba_hcdi_pipe_stop_isoc_polling 66entry points are called when a client driver wishes to cease polling on 67an interrupt or isochronous pipe as describe by 68.Fa ph . 69While these functions should only be called on pipes that have 70outstanding periodic interrupt and isochronous requests started through 71calls to either 72.Xr usba_hcdi_pipe_intr_xfer 9E 73or 74.Xr usba_hcdi_pipe_isoc_xfer 9E , 75as part of device driver hardening, device drivers should verify that 76there are outstanding transfers. 77.Pp 78For interrupt transfers, 79.Fa ph , 80may refer to the root hub and so the driver may need to cease any 81synthetic polling it is performing. 82Isochronous transfers are forbidden on the root hub, so the 83.Fn usba_hcdi_pipe_stop_isoc_polling 84will only be called on a pipe that corresponds to an actual device. 85.Pp 86These functions are 87.Em synchronous 88requests. 89In all cases, the driver should take the following steps before returning from 90these entry points: 91.Bl -enum 92.It 93Quiesce and stop the endpoint. 94.It 95Remove any remaining scheduled transfers. 96.It 97Call 98.Xr usba_hcdi_cb 9F 99on the original interrupt or isochronous request with the code 100.Sy USB_CR_STOPPED_POLLING . 101.It 102Optionally, free all associated resources. 103If resources aren't freed at this time, they must be freed when 104.Xr usba_hcdi_pipe_close 9E 105is called. 106.It 107Any other steps needed such that a call to perform one-shot or periodic 108transfers on this endpoint again may be enabled. 109.El 110.Pp 111It is possible that this function may be called concurrently with a call 112to the 113.Xr usba_hcdi_pipe_reset 9E 114entry point. 115In such cases, the host controller driver is required to perform synchronization 116on its data structures. 117.Sh RETURN VALUES 118Upon successful completion, the 119.Fn usba_hcdi_pipe_stop_intr_polling 120and 121.Fn uba_hcdi_pipe_stop_isoc_polling 122functions should return 123.Sy USB_SUCCESS . 124Otherwise, it should return the appropriate USB error. 125If uncertain, use 126.Sy USB_FAILURE . 127.Sh SEE ALSO 128.Xr usba_hcdi_pipe_close 9E , 129.Xr usba_hcdi_pipe_intr_xfer 9E , 130.Xr usba_hcdi_pipe_isoc_xfer 9E , 131.Xr usba_hcdi_pipe_reset 9E , 132.Xr usba_hcdi_cb 9F , 133.Xr usba_pipe_handle_data 9S 134