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 Nov 26, 2017
  15 .Dt USBA_HCDI_PIPE_OPEN 9E
  16 .Os
  17 .Sh NAME
  18 .Nm usba_hcdi_pipe_open ,
  19 .Nm usba_hcdi_pipe_close
  20 .Nd open and close a USB pipe
  21 .Sh SYNOPSIS
  22 .In sys/usb/usba/hcdi.h
  23 .Ft int
  24 .Fo prefix_hcdi_pipe_open
  25 .Fa "usba_pipe_handle_data_t *ph"
  26 .Fa "usb_flags_t usb_flags"
  27 .Fc
  28 .Ft int
  29 .Fo prefix_hcdi_pipe_close
  30 .Fa "usba_pipe_handle_data_t *ph"
  31 .Fa "usb_flags_t usb_flags"
  32 .Fc
  33 .Sh INTERFACE LEVEL
  34 .Sy Volatile -

 108 A given endpoint on a device can only be opened once.
 109 If there's a request to open an already open endpoint, then the request to open
 110 the pipe should be failed.
 111 .Pp
 112 By the time the call to open a pipe returns, the driver should expect
 113 that any of the pipe transfer or reset entry points will be called on
 114 the pipe.
 115 .Pp
 116 A driver can establish private data on an endpoint.
 117 During pipe open it may set the
 118 .Sy p_hcd_private
 119 member to any value.
 120 Generally this points to an allocated structure that contains data specific to
 121 the host controller.
 122 This value will remain on the pipe handle.
 123 It is the responsibility of the driver to clear the data when the pipe is
 124 closed.
 125 .Ss Pipe close specifics
 126 When a pipe is closed, the driver must clean up all of the resources
 127 that it allocated when opening the pipe.
 128 For non-periodic transfers, the host controller driver may assueme that there
 129 are no outstanding transfers that need to be cleaned up.
 130 However, the same is not true for periodic pipes.
 131 .Pp
 132 For pipes that have outstanding periodic transfers, the host controller
 133 driver needs to clean them up and quiesce them as though a call to
 134 either
 135 .Xr usba_hcdi_pipe_stop_intr_polling 9E
 136 or
 137 .Xr usba_hcdi_pipe_stop_isoc_polling 9E
 138 had been called.
 139 .Pp
 140 Just as with opening the pipe, the driver should pay attention to the
 141 address of the USB device, as it may be the root hub, which may be a
 142 synthetic pipe.
 143 .Pp
 144 When a call to
 145 .Fn usba_hcdi_pipe_close
 146 completes, the device should be in a state that the pipe can be opened
 147 again.
 148 .Sh RETURN VALUES

   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 February 15, 2020
  15 .Dt USBA_HCDI_PIPE_OPEN 9E
  16 .Os
  17 .Sh NAME
  18 .Nm usba_hcdi_pipe_open ,
  19 .Nm usba_hcdi_pipe_close
  20 .Nd open and close a USB pipe
  21 .Sh SYNOPSIS
  22 .In sys/usb/usba/hcdi.h
  23 .Ft int
  24 .Fo prefix_hcdi_pipe_open
  25 .Fa "usba_pipe_handle_data_t *ph"
  26 .Fa "usb_flags_t usb_flags"
  27 .Fc
  28 .Ft int
  29 .Fo prefix_hcdi_pipe_close
  30 .Fa "usba_pipe_handle_data_t *ph"
  31 .Fa "usb_flags_t usb_flags"
  32 .Fc
  33 .Sh INTERFACE LEVEL
  34 .Sy Volatile -

 108 A given endpoint on a device can only be opened once.
 109 If there's a request to open an already open endpoint, then the request to open
 110 the pipe should be failed.
 111 .Pp
 112 By the time the call to open a pipe returns, the driver should expect
 113 that any of the pipe transfer or reset entry points will be called on
 114 the pipe.
 115 .Pp
 116 A driver can establish private data on an endpoint.
 117 During pipe open it may set the
 118 .Sy p_hcd_private
 119 member to any value.
 120 Generally this points to an allocated structure that contains data specific to
 121 the host controller.
 122 This value will remain on the pipe handle.
 123 It is the responsibility of the driver to clear the data when the pipe is
 124 closed.
 125 .Ss Pipe close specifics
 126 When a pipe is closed, the driver must clean up all of the resources
 127 that it allocated when opening the pipe.
 128 For non-periodic transfers, the host controller driver may assume that there
 129 are no outstanding transfers that need to be cleaned up.
 130 However, the same is not true for periodic pipes.
 131 .Pp
 132 For pipes that have outstanding periodic transfers, the host controller
 133 driver needs to clean them up and quiesce them as though a call to
 134 either
 135 .Xr usba_hcdi_pipe_stop_intr_polling 9E
 136 or
 137 .Xr usba_hcdi_pipe_stop_isoc_polling 9E
 138 had been called.
 139 .Pp
 140 Just as with opening the pipe, the driver should pay attention to the
 141 address of the USB device, as it may be the root hub, which may be a
 142 synthetic pipe.
 143 .Pp
 144 When a call to
 145 .Fn usba_hcdi_pipe_close
 146 completes, the device should be in a state that the pipe can be opened
 147 again.
 148 .Sh RETURN VALUES