share/man/man9e/usba_hcdi_pipe_open.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 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 -
  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_open
  64 and
  65 .Fn usba_hcdi_pipe_close
  66 entry points are called by the USB framework whenever a client, or the
  67 framework itself, need to open or close a specific pipe.
  68 For additional background see
  69 .Xr usba_hcdi 9E .
  70 .Pp
  71 When a pipe is opened, the host controller driver is responsible for
  72 preparing the specified endpoint for performing transfers.
  73 This may include allocating bandwidth, programming the controller, and more.
  74 When the pipe is closed, the host controller driver is responsible for
  75 cleaning up any resources that were allocated during the open call.
  76 .Pp
  77 The pipe handle,
  78 .Fa ph ,
  79 identifies the endpoint that it the USBA is trying to open or close
  80 through its endpoint descriptor in the
  81 .Sy p_ep
  82 member.
  83 The endpoint descriptor is described in
  84 .Xr usb_ep_descr 9S .
  85 From the endpoint descriptor the driver can determine the type of
  86 endpoint, what the address of the endpoint is, and what direction the
  87 endpoint is in.
  88 When combined, these uniquely describe the pipe.
  89 .Pp
  90 To open a pipe, the driver may need additional companion endpoint
  91 descriptors.
  92 If these are available, they will be in the
  93 .Sy p_xep
  94 member of the pipe handle.
  95 See
  96 .Xr usb_ep_xdescr 9S
  97 for more information on how to determine which descriptors are present
  98 and get the information encoded in them.
  99 .Pp
 100 Host controller drivers should check the USB address of the
 101 USB device that
 102 .Fa ph
 103 belongs to.
 104 The driver may be asked to open a pipe to the root hub.
 105 As the root hub is often synthetic, the driver may need to take a different
 106 path than normal.
 107 .Ss Pipe open specifics
 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
 149 Upon successful completion, the
 150 .Fn usba_hcdi_pipe_open
 151 and
 152 .Fn uba_hcdi_pipe_close
 153 functions should return
 154 .Sy USB_SUCCESS .
 155 Otherwise, it should return the appropriate USB error.
 156 If uncertain, use
 157 .Sy USB_FAILURE .
 158 .Sh SEE ALSO
 159 .Xr usba_hcdi 9E ,
 160 .Xr usba_hcdi_pipe_stop_intr_polling 9E ,
 161 .Xr usba_hcdi_pipe_stop_isoc_polling 9E ,
 162 .Xr usb_ep_descr 9S ,
 163 .Xr usb_ep_xdescr 9S ,
 164 .Xr usba_pipe_handle_data 9S