.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2016 Joyent, Inc.
.\"
.Dd Dec 20, 2016
.Dt USBA_HCDI_PIPE_STOP_INTR_POLLING 9E
.Os
.Sh NAME
.Nm usba_hcdi_pipe_stop_intr_polling ,
.Nm usba_hcdi_pipe_stop_isoc_polling
.Nd stop polling on an interrupt or isochronous pipe
.Sh SYNOPSIS
.In sys/usb/usba/hcdi.h
.Ft int
.Fo prefix_hcdi_pipe_stop_intr_polling
.Fa "usba_pipe_handle_data_t *ph"
.Fa "usba_flags_t usb_flags"
.Fc
.Ft int
.Fo prefix_hcdi_pipe_stop_isoc_polling
.Fa "usba_pipe_handle_data_t *ph"
.Fa "usba_flags_t usb_flags"
.Fc
.Sh INTERFACE LEVEL
.Sy Volatile -
illumos USB HCD private function
.Pp
This is a private function that is not part of the stable DDI.
It may be removed or changed at any time.
.Sh PARAMETERS
.Bl -tag -width Fa
.It Fa ph
A pointer to a USB pipe handle as defined in
.Xr usba_pipe_handle_data 9S .
.It Fa usb_flags
Flags which describe how allocations should be performed.
Valid flags are:
.Bl -tag -width Sy
.It Sy USB_FLAGS_NOSLEEP
Do not block waiting for memory.
If memory is not available the allocation will fail.
.It Sy USB_FLAGS_SLEEP
Perform a blocking allocation.
If memory is not available, the function will wait until memory is made
available.
.Pp
Note, the request may still fail even if
.Sy USB_FLAGS_SLEEP
is specified.
.El
.El
.Sh DESCRIPTION
The
.Fn usba_hcdi_pipe_stop_intr_polling
and
.Fn usba_hcdi_pipe_stop_isoc_polling
entry points are called when a client driver wishes to cease polling on
an interrupt or isochronous pipe as describe by
.Fa ph .
While these functions should only be called on pipes that have
outstanding periodic interrupt and isochronous requests started through
calls to either
.Xr usba_hcdi_pipe_intr_xfer 9E
or
.Xr usba_hcdi_pipe_isoc_xfer 9E ,
as part of device driver hardening, device drivers should verify that
there are outstanding transfers.
.Pp
For interrupt transfers,
.Fa ph ,
may refer to the root hub and so the driver may need to cease any
synthetic polling it is performing.
Isochronous transfers are forbidden on the root hub, so the
.Fn usba_hcdi_pipe_stop_isoc_polling
will only be called on a pipe that corresponds to an actual device.
.Pp
These functions are
.Em synchronous
requests.
In all cases, the driver should take the following steps before returning from
these entry points:
.Bl -enum
.It
Quiesce and stop the endpoint.
.It
Remove any remaining scheduled transfers.
.It
Call
.Xr usba_hcdi_cb 9F
on the original interrupt or isochronous request with the code
.Sy USB_CR_STOPPED_POLLING .
.It
Optionally, free all associated resources.
If resources aren't freed at this time, they must be freed when
.Xr usba_hcdi_pipe_close 9E
is called.
.It
Any other steps needed such that a call to perform one-shot or periodic
transfers on this endpoint again may be enabled.
.El
.Pp
It is possible that this function may be called concurrently with a call
to the
.Xr usba_hcdi_pipe_reset 9E
entry point.
In such cases, the host controller driver is required to perform synchronization
on its data structures.
.Sh RETURN VALUES
Upon successful completion, the
.Fn usba_hcdi_pipe_stop_intr_polling
and
.Fn uba_hcdi_pipe_stop_isoc_polling
functions should return
.Sy USB_SUCCESS .
Otherwise, it should return the appropriate USB error.
If uncertain, use
.Sy USB_FAILURE .
.Sh SEE ALSO
.Xr usba_hcdi_pipe_close 9E ,
.Xr usba_hcdi_pipe_intr_xfer 9E ,
.Xr usba_hcdi_pipe_isoc_xfer 9E ,
.Xr usba_hcdi_pipe_reset 9E ,
.Xr usba_hcdi_cb 9F ,
.Xr usba_pipe_handle_data 9S