usr/src/man/man9e/usba_hcdi_pipe_stop_intr_polling.9e

   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 -
  35 illumos USB HCD private function
  36 .Pp
  37 This is a private function that is not part of the stable DDI. It may be
  38 removed or changed at any time.
  39 .Sh PARAMETERS
  40 .Bl -tag -width Fa
  41 .It Fa ph
  42 A pointer to a USB pipe handle as defined in
  43 .Xr usba_pipe_handle_data 9S .
  44 .It Fa usb_flags
  45 Flags which describe how allocations should be performed. Valid flags
  46 are:
  47 .Bl -tag -width Sy
  48 .It Sy USB_FLAGS_NOSLEEP
  49 Do not block waiting for memory. If memory is not available the allocation
  50 will fail.
  51 .It Sy USB_FLAGS_SLEEP
  52 Perform a blocking allocation. If memory is not available, the function
  53 will wait until memory is made available.
  54 .Pp
  55 Note, the request may still fail even if
  56 .Sy USB_FLAGS_SLEEP
  57 is specified.
  58 .El
  59 .El
  60 .Sh DESCRIPTION
  61 The
  62 .Fn usba_hcdi_pipe_stop_intr_polling
  63 and
  64 .Fn usba_hcdi_pipe_stop_isoc_polling
  65 entry points are called when a client driver wishes to cease polling on
  66 an interrupt or isochronous pipe as describe by
  67 .Fa ph .
  68 While these functions should only be called on pipes that have
  69 outstanding periodic interrupt and isochronous requests started through
  70 calls to either
  71 .Xr usba_hcdi_pipe_intr_xfer 9E
  72 or
  73 .Xr usba_hcdi_pipe_isoc_xfer 9E ,
  74 as part of device driver hardening, device drivers should verify that
  75 there are outstanding transfers.
  76 .Pp
  77 For interrupt transfers,
  78 .Fa ph ,
  79 may refer to the root hub and so the driver may need to cease any
  80 synthetic polling it is performing. Isochronous transfers are forbidden
  81 on the root hub, so the
  82 .Fn usba_hcdi_pipe_stop_isoc_polling
  83 will only be called on a pipe that corresponds to an actual device.
  84 .Pp
  85 These functions are
  86 .Em synchronous
  87 requests. In all cases, the driver should take the following steps
  88 before returning from these entry points:
  89 .Bl -enum
  90 .It
  91 Quiesce and stop the endpoint.
  92 .It
  93 Remove any remaining scheduled transfers.
  94 .It
  95 Call
  96 .Xr usba_hcdi_cb 9F
  97 on the original interrupt or isochronous request with the code
  98 .Sy USB_CR_STOPPED_POLLING .
  99 .It
 100 Optionally, free all associated resources. If resources aren't freed
 101 at this time, they must be freed when
 102 .Xr usba_hcdi_pipe_close 9E
 103 is called.
 104 .It
 105 Any other steps needed such that a call to perform one-shot or periodic
 106 transfers on this endpoint again may be enabled.
 107 .El
 108 .Pp
 109 It is possible that this function may be called concurrently with a call
 110 to the
 111 .Xr usba_hcdi_pipe_reset 9E
 112 entry point. In such cases, the host controller driver is required to
 113 perform synchronization on its data structures.
 114 .Sh RETURN VALUES
 115 Upon successful completion, the
 116 .Fn usba_hcdi_pipe_stop_intr_polling
 117 and
 118 .Fn uba_hcdi_pipe_stop_isoc_polling
 119 functions should return
 120 .Sy USB_SUCCESS .
 121 Otherwise, it should return the appropriate USB error. If uncertain, use
 122 .Sy USB_FAILURE .
 123 .Sh SEE ALSO
 124 .Xr usba_hcdi_pipe_close 9E ,
 125 .Xr usba_hcdi_pipe_intr_xfer 9E ,
 126 .Xr usba_hcdi_pipe_isoc_xfer 9E ,
 127 .Xr usba_hcdi_pipe_reset 9E ,
 128 .Xr usba_hcdi_cb 9F ,
 129 .Xr usba_pipe_handle_data 9S