211 This provides a device driver with the
 212 .Xr usba_hcdi_ops 9S
 213 structure that it must fill out.
 214 Please see
 215 .Xr usba_hcdi_ops 9S
 216 for instructions on how it should be filled out.
 217 Once filled out, the driver should call
 218 .Xr usba_hcdi_register 9F .
 219 .Pp
 220 If the call to register fails for whatever reason, the device driver
 221 should fail its
 222 .Xr attach 9E
 223 entry point.
 224 After this call successfully completes, the driver should assume that any of the
 225 functions it registered with the call to
 226 .Xr usba_hcdi_register 9F
 227 will be called at this point.
 228 .Ss Binding the Root Hub
 229 Once this is set up, the hcdi driver must initialize its root hub by
 230 calling
 231 Xr usba_hcdi_bind_root_hub 9F .
 232 To bind the root hub, the device driver is responsible for providing a
 233 device descriptor that represents the hardware.
 234  Depending on the hardware, this descriptor may be either static or dynamic.
 235 .Pp
 236 This device descriptor should be a packed descriptor that is the same
 237 that would be read off of the device.
 238 The device descriptor should match a hub of a USB generation equivalent to the
 239 maximum speed of the device.
 240 For example, a USB 3.0 host controller would use a USB 3.0 hub's device
 241 descriptor.
 242 Similarly, a USB 2.0 host controller would use a USB 2.0 hub's device
 243 descriptor.
 244 .Pp
 245 The descriptor first starts with a USB configuration descriptor, as
 246 defined in
 247 .Xr usb_cfg_descr 9S .
 248 It is then followed by an interface descriptor.
 249 The definition for it can be found in
 250 .Xr usb_if_descr 9S .
 251 Next is the endpoint descriptor for the single Interrupt-IN endpoint
 252 that all hubs have as defined in
 253 .Xr usb_ep_descr 9S .
 254 Finally, any required companion descriptors should be used.

 259 Note, that the structure needs to be packed, as though it were read from
 260 a device.
 261 The structures types referenced in
 262 .Xr usb_cfg_descr 9S ,
 263 .Xr usb_if_descr 9S ,
 264 .Xr usb_ep_descr 9S ,
 265 and
 266 .Xr usb_ep_ss_comp_descr 9S
 267 are not packed for this purpose.
 268 They should not be used as they have gaps added by the compiler for alignment.
 269 .Pp
 270 Once assembled, the device driver should call
 271 .Xr usba_hubdi_bind_root_hub 9F .
 272 This will cause an instance of the
 273 .Xr hubd 7D
 274 driver to be attached and associated with the root controller.
 275 As such, driver writers need to ensure that all initialization is done prior to
 276 loading the root hub.
 277 Once successfully loaded, driver writers should assume that they'll get other
 278 calls into the driver's operation vector before the call to
 279 .Xr usba_hubdi_bind_root_hub 9F.
 280 .Pp
 281 If the call to
 282 .Xr usba_hubdi_bind_root_hub 9F
 283 failed for whatever reason, the driver should unregister from USBA (see
 284 the next section), unwind all of the resources it has allocated, and
 285 return
 286 .Dv DDI_FAILURE .
 287 .Pp
 288 Otherwise, at this point it's safe to assume that the instance of the
 289 device has initialized successfully and the driver should return
 290 .Dv DDI_SUCCESS .
 291 .Ss Driver Teardown
 292 When a driver's
 293 .Xr detach 9E
 294 entry point has been called, before anything else is done, the device
 295 driver should unbind its instance of the root hub and then unregister
 296 from the USBA.
 297 .Pp
 298 To unbind the root hub, the instance of the driver should call
 299 .Xr usba_hubdi_unbind_root_hub 9F .

 211 This provides a device driver with the
 212 .Xr usba_hcdi_ops 9S
 213 structure that it must fill out.
 214 Please see
 215 .Xr usba_hcdi_ops 9S
 216 for instructions on how it should be filled out.
 217 Once filled out, the driver should call
 218 .Xr usba_hcdi_register 9F .
 219 .Pp
 220 If the call to register fails for whatever reason, the device driver
 221 should fail its
 222 .Xr attach 9E
 223 entry point.
 224 After this call successfully completes, the driver should assume that any of the
 225 functions it registered with the call to
 226 .Xr usba_hcdi_register 9F
 227 will be called at this point.
 228 .Ss Binding the Root Hub
 229 Once this is set up, the hcdi driver must initialize its root hub by
 230 calling
 231 .Xr usba_hubdi_bind_root_hub 9F .
 232 To bind the root hub, the device driver is responsible for providing a
 233 device descriptor that represents the hardware.
 234 Depending on the hardware, this descriptor may be either static or dynamic.
 235 .Pp
 236 This device descriptor should be a packed descriptor that is the same
 237 that would be read off of the device.
 238 The device descriptor should match a hub of a USB generation equivalent to the
 239 maximum speed of the device.
 240 For example, a USB 3.0 host controller would use a USB 3.0 hub's device
 241 descriptor.
 242 Similarly, a USB 2.0 host controller would use a USB 2.0 hub's device
 243 descriptor.
 244 .Pp
 245 The descriptor first starts with a USB configuration descriptor, as
 246 defined in
 247 .Xr usb_cfg_descr 9S .
 248 It is then followed by an interface descriptor.
 249 The definition for it can be found in
 250 .Xr usb_if_descr 9S .
 251 Next is the endpoint descriptor for the single Interrupt-IN endpoint
 252 that all hubs have as defined in
 253 .Xr usb_ep_descr 9S .
 254 Finally, any required companion descriptors should be used.

 259 Note, that the structure needs to be packed, as though it were read from
 260 a device.
 261 The structures types referenced in
 262 .Xr usb_cfg_descr 9S ,
 263 .Xr usb_if_descr 9S ,
 264 .Xr usb_ep_descr 9S ,
 265 and
 266 .Xr usb_ep_ss_comp_descr 9S
 267 are not packed for this purpose.
 268 They should not be used as they have gaps added by the compiler for alignment.
 269 .Pp
 270 Once assembled, the device driver should call
 271 .Xr usba_hubdi_bind_root_hub 9F .
 272 This will cause an instance of the
 273 .Xr hubd 7D
 274 driver to be attached and associated with the root controller.
 275 As such, driver writers need to ensure that all initialization is done prior to
 276 loading the root hub.
 277 Once successfully loaded, driver writers should assume that they'll get other
 278 calls into the driver's operation vector before the call to
 279 .Xr usba_hubdi_bind_root_hub 9F .
 280 .Pp
 281 If the call to
 282 .Xr usba_hubdi_bind_root_hub 9F
 283 failed for whatever reason, the driver should unregister from USBA (see
 284 the next section), unwind all of the resources it has allocated, and
 285 return
 286 .Dv DDI_FAILURE .
 287 .Pp
 288 Otherwise, at this point it's safe to assume that the instance of the
 289 device has initialized successfully and the driver should return
 290 .Dv DDI_SUCCESS .
 291 .Ss Driver Teardown
 292 When a driver's
 293 .Xr detach 9E
 294 entry point has been called, before anything else is done, the device
 295 driver should unbind its instance of the root hub and then unregister
 296 from the USBA.
 297 .Pp
 298 To unbind the root hub, the instance of the driver should call
 299 .Xr usba_hubdi_unbind_root_hub 9F .