1 USBA_HCDI_PIPE_RESET(9E)      Driver Entry Points     USBA_HCDI_PIPE_RESET(9E)
   2 
   3 NAME
   4      usba_hcdi_pipe_reset - reset an open USB pipe
   5 
   6 SYNOPSIS
   7      #include <sys/usb/usba/hcdi.h>
   8 
   9      int
  10      prefix_hcdi_pipe_reset(usba_pipe_handle_data_t *ph,
  11          usb_flags_t usb_flags);
  12 
  13 INTERFACE LEVEL
  14      Volatile - illumos USB HCD private function
  15 
  16      This is a private function that is not part of the stable DDI.  It may be
  17      removed or changed at any time.
  18 
  19 PARAMETERS
  20      ph            A pointer to a USB pipe handle as defined in
  21                    usba_pipe_handle_data(9S).
  22 
  23      usb_flags     Flags which describe how allocations should be performed.
  24                    Valid flags are:
  25 
  26                    USB_FLAGS_NOSLEEP
  27                            Do not block waiting for memory.  If memory is not
  28                            available the allocation will fail.
  29 
  30                    USB_FLAGS_SLEEP
  31                            Perform a blocking allocation.  If memory is not
  32                            available, the function will wait until memory is
  33                            made available.
  34 
  35                            Note, the request may still fail even if
  36                            USB_FLAGS_SLEEP is specified.
  37 
  38 DESCRIPTION
  39      The usba_hcdi_pipe_reset() entry point is designed to take a pipe in an
  40      arbitrary state and return it to the same state it was in after a call to
  41      usba_hcdi_pipe_open(9E).  While this entry point does some similar things
  42      to the usba_hcdi_pipe_stop_intr_polling(9E) and
  43      usba_hcdi_pipe_stop_isoc_polling(9E) entry points, there are some notable
  44      differences.
  45 
  46      This entry point is synchronous.  The host controller driver should take
  47      the following steps on the pipe before returning:
  48 
  49      1.   Quiesce and stop the endpoint.
  50 
  51      2.   If the endpoint has any errors they should be cleared at this time.
  52 
  53      3.   Remove any remaining, scheduled or queued transfers.  For each one
  54           call usba_hcdi_cb(9F) with the code USB_CR_PIPE_RESET.
  55 
  56      4.   Perform any other necessary steps on the controller to have the
  57           endpoint be ready to perform I/O.
  58 
  59      This entry point is called by the broader USBA framework as part of
  60      closing a pipe or in response to a device stall.
  61 
  62 RETURN VALUES
  63      Upon successful completion, the usba_hcdi_pipe_reset() function should
  64      return USB_SUCCESS.  Otherwise, it should return the appropriate USB
  65      error.  If uncertain, use USB_FAILURE.
  66 
  67 SEE ALSO
  68      usba_hcdi_pipe_open(9E), usba_hcdi_pipe_stop_intr_polling(9E),
  69      usba_hcdi_pipe_stop_isoc_polling(9E), usba_hcdi_cb(9F),
  70      usba_pipe_handle_data(9S)
  71 
  72 illumos                         August 20, 2019                        illumos