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 Aug 20, 2019
  15 .Dt USBA_HCDI_PIPE_RESET 9E
  16 .Os
  17 .Sh NAME
  18 .Nm usba_hcdi_pipe_reset
  19 .Nd reset an open USB pipe
  20 .Sh SYNOPSIS
  21 .In sys/usb/usba/hcdi.h
  22 .Ft int
  23 .Fo prefix_hcdi_pipe_reset
  24 .Fa "usba_pipe_handle_data_t *ph"
  25 .Fa "usb_flags_t usb_flags"
  26 .Fc
  27 .Sh INTERFACE LEVEL
  28 .Sy Volatile -
  29 illumos USB HCD private function
  30 .Pp
  31 This is a private function that is not part of the stable DDI.
  32 It may be removed or changed at any time.
  33 .Sh PARAMETERS
  34 .Bl -tag -width Fa
  35 .It Fa ph
  36 A pointer to a USB pipe handle as defined in
  37 .Xr usba_pipe_handle_data 9S .
  38 .It Fa usb_flags
  39 Flags which describe how allocations should be performed.
  40 Valid flags are:
  41 .Bl -tag -width Sy
  42 .It Sy USB_FLAGS_NOSLEEP
  43 Do not block waiting for memory.
  44 If memory is not available the allocation will fail.
  45 .It Sy USB_FLAGS_SLEEP
  46 Perform a blocking allocation.
  47 If memory is not available, the function will wait until memory is made
  48 available.
  49 .Pp
  50 Note, the request may still fail even if
  51 .Sy USB_FLAGS_SLEEP
  52 is specified.
  53 .El
  54 .El
  55 .Sh DESCRIPTION
  56 The
  57 .Fn usba_hcdi_pipe_reset
  58 entry point is designed to take a pipe in an arbitrary state and return
  59 it to the same state it was in after a call to
  60 .Xr usba_hcdi_pipe_open 9E .
  61 While this entry point does some similar things to the
  62 .Xr usba_hcdi_pipe_stop_intr_polling 9E
  63 and
  64 .Xr usba_hcdi_pipe_stop_isoc_polling 9E
  65 entry points, there are some notable differences.
  66 .Pp
  67 This entry point is synchronous.
  68 The host controller driver should take the following steps on the pipe before
  69 returning:
  70 .Bl -enum
  71 .It
  72 Quiesce and stop the endpoint.
  73 .It
  74 If the endpoint has any errors they should be cleared at this time.
  75 .It
  76 Remove any remaining, scheduled or queued transfers.
  77 For each one call
  78 .Xr usba_hcdi_cb 9F
  79 with the code
  80 .Sy USB_CR_PIPE_RESET .
  81 .It
  82 Perform any other necessary steps on the controller to have the endpoint
  83 be ready to perform I/O.
  84 .El
  85 .Pp
  86 This entry point is called by the broader USBA framework as part of
  87 closing a pipe or in response to a device stall.
  88 .Sh RETURN VALUES
  89 Upon successful completion, the
  90 .Fn usba_hcdi_pipe_reset
  91 function should return
  92 .Sy USB_SUCCESS .
  93 Otherwise, it should return the appropriate USB error.
  94 If uncertain, use
  95 .Sy USB_FAILURE .
  96 .Sh SEE ALSO
  97 .Xr usba_hcdi_pipe_open 9E ,
  98 .Xr usba_hcdi_pipe_stop_intr_polling 9E ,
  99 .Xr usba_hcdi_pipe_stop_isoc_polling 9E ,
 100 .Xr usba_hcdi_cb 9F ,
 101 .Xr usba_pipe_handle_data 9S