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