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