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