usr/src/man/man9s/usba_hcdi_ops.9s

   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_OPS 9S
  16 .Os
  17 .Sh NAME
  18 .Nm usba_hcdi_ops ,
  19 .Nm usba_hcdi_ops_t
  20 .Nd USBA host controller driver operations vector
  21 .Sh SYNOPSIS
  22 .In sys/usb/usba/hcdi.h
  23 .Sh INTERFACE LEVEL
  24 .Sy Volatile -
  25 illumos USB HCD private
  26 .Pp
  27 This is a private data structure that is not part of the stable DDI.
  28 It may be removed or changed at any time.
  29 .Sh DESCRIPTION
  30 The
  31 .Sy usba_hcdi_ops
  32 structure is usbed HCD drivers to register operations vectors and
  33 callbacks from the USBA HCD interface.
  34 See
  35 .Xr usba_hcdi 9E
  36 for more information on USB HCD device drivers.
  37 .Pp
  38 The structure is allocated through a call to the
  39 .Xr usba_alloc_hcdi_ops 9F
  40 function and is used with a call to
  41 .Xr usba_hcdi_register 9F .
  42 When the driver is done with the operations vector, either because
  43 registering has failed or it is unregistering, it should call
  44 .Xr usba_free_hcdi_ops 9F
  45 to free the associated memory.
  46 .Sh STRUCTURE MEMBERS
  47 The
  48 .Sy usba_hcdi_ops
  49 structure has the following members:
  50 .Bd -literal -offset indent
  51 int             usba_hcdi_ops_version;
  52 dev_info_t      *usba_hcdi_dip;
  53
  54 int     (*usba_hcdi_pm_support)(dev_info_t *);
  55 int     (*usba_hcdi_pipe_open)(usba_pipe_handle_data_t *, usb_flags_t);
  56 int     (*usba_hcdi_pipe_close)(usba_pipe_handle_data_t *, usb_flags_t);
  57 int     (*usba_hcdi_pipe_reset)(usba_pipe_handle_data_t *, usb_flags_t);
  58 void    (*usba_hcdi_pipe_reset_data_toggle)(usba_pipe_handle_data_t *);
  59
  60 int     (*usba_hcdi_pipe_ctrl_xfer)(usba_pipe_handle_data_t *,
  61             usb_ctrl_req_t *, usb_flags_t);
  62
  63 int     (*usba_hcdi_bulk_transfer_size)(usba_device_t *, size_t *);
  64 int     (*usba_hcdi_pipe_bulk_xfer)(usba_pipe_handle_data_t *,
  65             usb_bulk_req_t *, usb_flags_t);
  66
  67 int     (*usba_hcdi_pipe_intr_xfer)(usba_pipe_handle_data_t *,
  68             usb_intr_req_t *, usb_flags_t);
  69 int     (*usba_hcdi_pipe_stop_intr_polling)(usba_pipe_handle_data_t *,
  70             usb_flags_t);
  71
  72 int     (*usba_hcdi_pipe_isoc_xfer)(usba_pipe_handle_data_t *,
  73             usb_isoc_req_t *, usb_flags_t);
  74 int     (*usba_hcdi_pipe_stop_isoc_polling)(usba_pipe_handle_data_t *,
  75             usb_flags_t);
  76 int     (*usba_hcdi_get_current_frame_number)(usba_device_t *,
  77             usb_frame_number_t *);
  78 int     (*usba_hcdi_get_max_isoc_pkts)(usba_device_t *, uint_t *);
  79
  80 int     (*usba_hcdi_console_input_init)(usba_pipe_handle_data_t *,
  81             uchar_t **, usb_console_info_impl_t *);
  82 int     (*usba_hcdi_console_input_fini)(usb_console_info_impl_t *);
  83 int     (*usba_hcdi_console_input_enter)(usb_console_info_impl_t *);
  84 int     (*usba_hcdi_console_read)(usb_console_info_impl_t *, uint_t);
  85 int     (*usba_hcdi_console_input_exit)(usb_console_info_impl_t *);
  86
  87 int     (*usba_hcdi_console_output_init)(usba_pipe_handle_data_t *,
  88             usb_console_info_impl_t *);
  89 int     (*usba_hcdi_console_output_fini)(usb_console_info_impl_t *);
  90 int     (*usba_hcdi_console_output_enter)(usb_console_info_impl_t *);
  91 int     (*usba_hcdi_console_write)(usb_console_info_impl_t *, uchar_t *,
  92             uint_t, uint_t *);
  93 int     (*usba_hcdi_console_output_exit)(usb_console_info_impl_t *);
  94
  95 int     (*usba_hcdi_device_init)(usba_device_t *, usb_port_t, void **);
  96 void    (*usba_hcdi_device_fini)(usba_device_t *, void *);
  97 int     (*usba_hcdi_device_address)(usba_device_t *);
  98
  99 int     (*usba_hcdi_hub_update)(usba_device_t *, uint8_t, uint8_t);
 100 .Ed
 101 .Pp
 102 The
 103 .Sy usba_hcdi_ops_version
 104 member is used to indicate the revision of the operations vector.
 105 HCD drivers should generally set this to
 106 .Dv HCDI_OPS_VERSION .
 107 .Pp
 108 The
 109 .Sy usba_hcdi_dip
 110 member should be set to the
 111 .Sy dev_info_t
 112 structure of the HCD driver that was received in
 113 .Xr attach 9E .
 114 .Pp
 115 The
 116 .Sy usba_hcdi_pm_support
 117 member is vestigial.
 118 If may be set to
 119 .Dv NULL
 120 or to a function which only returns
 121 .Sy USB_FAILURE .
 122 .Pp
 123 The
 124 .Sy usba_hcdi_pipe_open
 125 member should be set to a function which takes care of the all of the
 126 controller-specific actions of opening up an endpoint on a device and
 127 associating it with the pipe.
 128 See
 129 .Xr usba_hcdi_pipe_open 9E
 130 for more information.
 131 .Pp
 132 The
 133 .Sy usba_hcdi_pipe_close
 134 member should be set to a function which takes care of releasing all of
 135 the controller-specific resources and actions taken when the pipe was
 136 opened.
 137 This function also has the responsibility to clean up any outstanding polling on
 138 the endpoint.
 139 See
 140 .Xr usba_hcdi_pipe_close 9E
 141 for more information.
 142 .Pp
 143 The
 144 .Sy usba_hcdi_pipe_reset
 145 member should be set to a function that takes care of resetting a pipe.
 146 A pipe reset not only performs controller-specific functionality, but it
 147 also cleans up any outstanding requests and terminates polling.
 148 See
 149 .Xr usba_hcdi_pipe_reset 9E
 150 for more information.
 151 .Pp
 152 The
 153 .Sy usba_hcdi_pipe_reset_data_toggle
 154 member should be set to a function that takes care of the USB data
 155 toggle, if the controller exposes this functionality to the host.
 156 .Pp
 157 The
 158 .Sy usba_hcdi_pipe_ctrl_xfer
 159 member should be set to a function that handles control transfers for any
 160 device, including the root hub.
 161 See
 162 .Xr usba_hcdi_pipe_ctrl_xfer 9E
 163 for more information.
 164 .Pp
 165 The
 166 .Sy usba_hcdi_bulk_transfer_size
 167 member should be a set to a function which can return the maximum amount
 168 of data that can be performed in a given USB transfer for a bulk
 169 transfer.
 170 .Pp
 171 The
 172 .Sy usba_hcdi_pipe_bulk_xfer
 173 member should be set set to a function which performs a bulk transfer.
 174 See
 175 .Xr usba_hcdi_pipe_bulk_xfer 9E
 176 for more information.
 177 .Pp
 178 The
 179 .Sy usba_hcdi_pipe_intr_xfer
 180 member should be set to a function which performs interrupt transfers.
 181 These may be both periodic and one-shot transfers.
 182 In addition, this may need to handle requests for the root hub.
 183 See
 184 .Xr usba_hcdi_pipe_intr_xfer 9E
 185 for more information.
 186 .Pp
 187 The
 188 .Sy usba_hcdi_pipe_stop_intr_polling
 189 member should be set to a function which is used to terminate interrupt
 190 polling and return the original interrupt request.
 191 See
 192 .Xr usba_hcdi_pipe_stop_intr_polling 9E
 193 for more information.
 194 .Pp
 195 The
 196 .Sy usba_hcdi_pipe_isoc_xfer
 197 member should be set to a function which performs isochronous transfers.
 198 These may be both periodic and one-shot transfers.
 199 See
 200 .Xr usba_hcdi_pipe_isoc_xfer 9E
 201 for more information.
 202 .Pp
 203 The
 204 .Sy usba_hcdi_pipe_stop_isoc_polling
 205 member should be set to a function which is used to terminate isochronous
 206 polling and return the original isochronous request.
 207 See
 208 .Xr usba_hcdi_pipe_stop_isoc_polling 9E
 209 for more information.
 210 .Pp
 211 The
 212 .Sy usba_hcdi_get_current_frame_number
 213 member should be set to a function which returns the current virtual
 214 frame number.
 215 While this entry point is required, at this time, nothing uses this
 216 functionality in illumos, so having a dummy function which just returns
 217 .Sy USB_FAILURE
 218 is acceptable.
 219 .Pp
 220 The
 221 .Sy usba_hcdi_max_isoc_pkts
 222 member should be set to a function that returns the maximum number of
 223 isochronous fragments that can be queued in a given transfer.
 224 .Pp
 225 The
 226 .Sy usba_hcdi_console_input_init ,
 227 .Sy usba_hcdi_console_input_fini ,
 228 .Sy usba_hcdi_console_input_enter ,
 229 .Sy usba_hcdi_console_read ,
 230 and
 231 .Sy usba_hcdi_console_input_exit
 232 members are used to facilitate a USB device acting as the system console
 233 and reading input from it.
 234 Support for this is optional in an HCD driver.
 235 HCD drivers which do not support this functionality should have functions which
 236 return
 237 .Sy USB_FAILURE .
 238 .Pp
 239 The
 240 .Sy usba_hcdi_console_output_init ,
 241 .Sy usba_hcdi_console_output_fini ,
 242 .Sy usba_hcdi_console_output_enter ,
 243 .Sy usba_hcdi_console_writ ,
 244 and
 245 .Sy usba_hcdi_console_output_exit
 246 members are used to facilitate a USB device acting as the system console
 247 and outputting data to it.
 248 Support for this is optional in an HCD driver.
 249 HCD drivers which do not support this functionality should have functions which
 250 return
 251 .Sy USB_FAILURE .
 252 .Pp
 253 The
 254 .Sy usba_hcdi_device_init
 255 member is an
 256 .Em optional
 257 entry point that will be called every time a new device is initialized
 258 and detected by the system.
 259 If an HCD does not need this functionality, the member should be set to
 260 .Dv NULL .
 261 See
 262 .Xr usba_hcdi_device_init 9E
 263 for more information.
 264 .Pp
 265 The
 266 .Sy usba_hcdi_device_fini
 267 member is an
 268 .Em optional
 269 entry point that will be called every time a device is removed from the
 270 system, whether through it being unplugged or a
 271 .Xr cfgadm 1M
 272 action.
 273 If an HCD does not need this functionality, the member should be set to
 274 .Dv NULL .
 275 See
 276 .Xr usba_hcdi_device_fini 9E
 277 for more information.
 278 .Pp
 279 The
 280 .Sy usba_hcdi_device_address
 281 member is an
 282 .Em optional
 283 entry point that will be called every time a USB device needs to be
 284 addressed.
 285 If an HCD driver does not need this functionality, the member should be set to
 286 .Dv NULL .
 287 See
 288 .Xr usba_hcdi_device_address 9E
 289 for more information.
 290 .Pp
 291 The
 292 .Sy usba_hcdi_hub_update
 293 member is an
 294 .Em optional
 295 entry point that will be called every time a device descriptor is read
 296 that turns out to be a hub.
 297 This gives HCD drivers a chance to perform any needed controller-specific
 298 functionality before the device is used.
 299 If an HCD driver does not need this functionality, the member should be set to
 300 .Dv NULL .
 301 See
 302 .Xr usba_hcdi_hub_update 9E
 303 for more information.
 304 .Sh SEE ALSO
 305 .Xr cfgadm 1M ,
 306 .Xr attach 9E ,
 307 .Xr usba_hcdi 9E ,
 308 .Xr usba_hcdi_device_address 9E ,
 309 .Xr usba_hcdi_device_fini 9E ,
 310 .Xr usba_hcdi_device_init 9E ,
 311 .Xr usba_hcdi_hub_update 9E ,
 312 .Xr usba_hcdi_pipe_bulk_xfer 9E ,
 313 .Xr usba_hcdi_pipe_close 9E ,
 314 .Xr usba_hcdi_pipe_ctrl_xfer 9E ,
 315 .Xr usba_hcdi_pipe_intr_xfer 9E ,
 316 .Xr usba_hcdi_pipe_isoc_xfer 9E ,
 317 .Xr usba_hcdi_pipe_open 9E ,
 318 .Xr usba_hcdi_pipe_reset 9E ,
 319 .Xr usba_hcdi_pipe_stop_intr_polling 9E ,
 320 .Xr usba_hcdi_pipe_stop_isoc_polling 9E ,
 321 .Xr usba_alloc_hcdi_ops 9F ,
 322 .Xr usba_free_hcdi_ops 9F ,
 323 .Xr usba_hcdi_register 9F