1 USBA_HCDI(9E) Driver Entry Points USBA_HCDI(9E) 2 3 NAME 4 usba_hcdi - USB Host Controller Driver Interface 5 6 SYNOPSIS 7 #include <sys/usb/usba/hcdi.h> 8 9 INTERFACE LEVEL 10 Volatile - illumos USB HCD private function 11 12 This describes private interfaces that are not part of the stable DDI. 13 This may be removed or changed at any time. 14 15 DESCRIPTION 16 hcdi drivers are device drivers that support USB host controller 17 hardware. USB host controllers provide an interface between the 18 operating system and USB devices. They abstract the interface to the 19 devices, often provide ways of performing DMA, and also act as the root 20 hub. 21 22 hcdi drivers are part of the illumos USB Architecture (USBA). The 23 usba(7D) driver provides support for many of the surrounding needs of an 24 hcdi driver and requires that such drivers implement a specific 25 operations vector, usba_hcdi_ops(9S). These functions cover everything 26 from initialization to performing I/O to USB devices on behalf of client 27 device drivers. 28 29 USB Speed and Version Background 30 USB devices are often referred to in two different ways. The first way 31 is the USB version that they conform to. In the wild this looks like USB 32 1.1, USB 2.0, USB 3.0, etc.. However, devices are also referred to as 33 `full-', `low-', `high-', `super-' speed devices. 34 35 The latter description describes the maximum theoretical speed of a given 36 device. For example, a super-speed device theoretically caps out around 37 5 Gbit/s, whereas a low-speed device caps out at 1.5 Mbit/s. 38 39 In general, each speed usually corresponds to a specific USB protocol 40 generation. For example, all USB 3.0 devices are super-speed devices. 41 All 'high-speed' devices are USB 2.x devices. Full-speed devices are 42 special in that they can either be USB 1.x or USB 2.x devices. Low-speed 43 devices are only a USB 1.x thing, they did not jump the fire line to USB 44 2.x. 45 46 USB 3.0 devices and ports generally have the wiring for both USB 2.0 and 47 USB 3.0. When a USB 3.0 device is plugged into a USB 2.0 port or hub, 48 then it will report its version as USB 2.1, to indicate that it is 49 actually a USB 3.0 device. 50 51 USB Endpoint Background 52 To understand the organization of the functions that make up the hcdi 53 operations vector, it helps to understand how USB devices are organized 54 and work at a high level. 55 56 A given USB device is made up of endpoints. A request, or transfer, is 57 made to a specific USB endpoint. These endpoints can provide different 58 services and have different expectations around the size of the data 59 that'll be used in a given request and the periodicity of requests. 60 Endpoints themselves are either used to make one-shot requests, for 61 example, making requests to a mass storage device for a given sector, or 62 for making periodic requests where you end up polling on the endpoint, 63 for example, polling on a USB keyboard for keystrokes. 64 65 Each endpoint encodes two different pieces of information: a direction 66 and a type. There are two different directions: IN and OUT. These refer 67 to the general direction that data moves relative to the operating 68 system. For example, an IN transfer transfers data in to the operating 69 system, from the device. An OUT transfer transfers data from the 70 operating system, out to the device. 71 72 There are four different kinds of endpoints: 73 74 BULK These transfers are large transfers of data to or from a 75 device. The most common use for bulk transfers is for mass 76 storage devices. Though they are often also used by 77 network devices and more. Bulk endpoints do not have an 78 explicit time component to them. They are always used for 79 one-shot transfers. 80 81 CONTROL 82 These transfers are used to manipulate devices themselves 83 and are used for USB protocol level operations (whether 84 device-specific, class-specific, or generic across all of 85 USB). Unlike other transfers, control transfers are always 86 bi-directional and use different kinds of transfers. 87 88 INTERRUPT 89 Interrupt transfers are used for small transfers that 90 happen infrequently, but need reasonable latency. A good 91 example of interrupt transfers is to receive input from a 92 USB keyboard. Interrupt-IN transfers are generally polled. 93 Meaning that a client (device driver) opens up an 94 interrupt-IN endpoint to poll on it, and receives periodic 95 updates whenever there is information available. However, 96 Interrupt transfers can be used as one-shot transfers both 97 going IN and OUT. 98 99 ISOCHRONOUS 100 These transfers are things that happen once per time- 101 interval at a very regular rate. A good example of these 102 transfers are for audio and video. A device may describe 103 an interval as 10ms at which point it will read or write 104 the next batch of data every 10ms and transform it for the 105 user. There are no one-shot Isochronous-IN transfers. 106 There are one-shot Isochronous-OUT transfers, but these are 107 used by device drivers to always provide the system with 108 sufficient data. 109 110 To find out information about the endpoints, USB devices have a series of 111 descriptors that cover different aspects of the device. For example, 112 there are endpoint descriptors which cover the properties of endpoints 113 such as the maximum packet size or polling interval. 114 115 Descriptors exist at all levels of USB. For example, there are general 116 descriptors for every device. The USB device descriptor is described in 117 usb_dev_descr(9S). Host controllers will look at these descriptors to 118 ensure that they program the device correctly; however, they are more 119 often used by client device drivers. There are also descriptors that 120 exist at a class level. For example, the hub class has a class-specific 121 descriptor which describes properties of the hub. That information is 122 requested for and used by the hub driver. 123 124 All of the different descriptors are gathered by the system and placed 125 into a tree, with device descriptors, configurations, endpoints, and 126 more. Client device drivers gain access to this tree and then use them 127 to then open endpoints, which are called pipes in USBA (and some 128 revisions of the USB specification). 129 130 Each pipe gives access to a specific endpoint on the device which can be 131 used to perform transfers of a specific type and direction. For example, 132 a mass storage device often has three different endpoints, the default 133 control endpoint (which every device has), a Bulk-IN endpoint, and a 134 Bulk-OUT endpoint. The device driver ends up with three open pipes. One 135 to the default control endpoint to configure the device, and then the 136 other two are used to perform I/O. 137 138 These routines translate more or less directly into calls to a host 139 controller driver. A request to open a pipe takes an endpoint descriptor 140 that describes the properties of the pipe, and the host controller driver 141 goes through and does any work necessary to allow the client device 142 driver to access it. Once the pipe is open, it either makes one-shot 143 transfers specific to the transfer type or it starts performing a 144 periodic poll of an endpoint. 145 146 All of these different actions translate into requests to the host 147 controller. The host controller driver itself is in charge of making 148 sure that all of the required resources for polling are allocated with a 149 request and then proceed to give the driver's periodic callbacks. 150 151 For each of the different operations described above, there is a 152 corresponding entry in usba_hcdi_ops(9S). For example, open an endpoint, 153 the host controller has to implement usba_hcdi_pipe_open(9E) and for each 154 transfer type, there is a different transfer function. One example is 155 usba_hcdi_pipe_bulk_xfer(9E). See usba_hcdi_ops(9S) for a full list of 156 the different function endpoints. 157 158 HCDI Initialization 159 hcdi drivers are traditional character device drivers. To start with, an 160 hcdi driver should define traditional dev_ops(9S) and cb_ops(9S) 161 structures. To get started, the device driver should perform normal 162 device initialization in an attach(9E) entry point. For example, PCI 163 devices should setup the device's registers and program them. In 164 addition, all devices should configure interrupts, before getting ready 165 to call into the USBA. Each instance of a device must be initialized and 166 registered with the USBA. 167 168 To initialize a device driver with the USBA, it must first call 169 usba_alloc_hcdi_ops(9F). This provides a device driver with the 170 usba_hcdi_ops(9S) structure that it must fill out. Please see 171 usba_hcdi_ops(9S) for instructions on how it should be filled out. Once 172 filled out, the driver should call usba_hcdi_register(9F). 173 174 If the call to register fails for whatever reason, the device driver 175 should fail its attach(9E) entry point. After this call successfully 176 completes, the driver should assume that any of the functions it 177 registered with the call to usba_hcdi_register(9F) will be called at this 178 point. 179 180 Binding the Root Hub 181 Once this is set up, the hcdi driver must initialize its root hub by 182 calling usba_hubdi_bind_root_hub(9F). To bind the root hub, the device 183 driver is responsible for providing a device descriptor that represents 184 the hardware. Depending on the hardware, this descriptor may be either 185 static or dynamic. 186 187 This device descriptor should be a packed descriptor that is the same 188 that would be read off of the device. The device descriptor should match 189 a hub of a USB generation equivalent to the maximum speed of the device. 190 For example, a USB 3.0 host controller would use a USB 3.0 hub's device 191 descriptor. Similarly, a USB 2.0 host controller would use a USB 2.0 192 hub's device descriptor. 193 194 The descriptor first starts with a USB configuration descriptor, as 195 defined in usb_cfg_descr(9S). It is then followed by an interface 196 descriptor. The definition for it can be found in usb_if_descr(9S). 197 Next is the endpoint descriptor for the single Interrupt-IN endpoint that 198 all hubs have as defined in usb_ep_descr(9S). Finally, any required 199 companion descriptors should be used. For example, a USB 3.x hub will 200 have a usb_ep_ss_comp_descr(9S) appended to the structure. 201 202 Note, that the structure needs to be packed, as though it were read from 203 a device. The structures types referenced in usb_cfg_descr(9S), 204 usb_if_descr(9S), usb_ep_descr(9S), and usb_ep_ss_comp_descr(9S) are not 205 packed for this purpose. They should not be used as they have gaps added 206 by the compiler for alignment. 207 208 Once assembled, the device driver should call 209 usba_hubdi_bind_root_hub(9F). This will cause an instance of the 210 hubd(7D) driver to be attached and associated with the root controller. 211 As such, driver writers need to ensure that all initialization is done 212 prior to loading the root hub. Once successfully loaded, driver writers 213 should assume that they'll get other calls into the driver's operation 214 vector before the call to usba_hubdi_bind_root_hub(9F). 215 216 If the call to usba_hubdi_bind_root_hub(9F) failed for whatever reason, 217 the driver should unregister from USBA (see the next section), unwind all 218 of the resources it has allocated, and return DDI_FAILURE. 219 220 Otherwise, at this point it's safe to assume that the instance of the 221 device has initialized successfully and the driver should return 222 DDI_SUCCESS. 223 224 Driver Teardown 225 When a driver's detach(9E) entry point has been called, before anything 226 else is done, the device driver should unbind its instance of the root 227 hub and then unregister from the USBA. 228 229 To unbind the root hub, the instance of the driver should call 230 usba_hubdi_unbind_root_hub(9F). If for some reason that function does 231 not return USB_SUCCESS, then the device driver should fail the call to 232 detach(9E) and return DDI_FAILURE. 233 234 Once the root hub has been unbound, the device driver can continue by 235 removing its hcdi registration with USBA. To do this, the driver should 236 call usba_hcdi_unregister(9F). As this call always succeeds, at this 237 point, it is safe for the driver to tear down all the rest of its 238 resources and successfully detach. 239 240 State Tracking and Minor Numbers 241 Because a host controller driver is also a root hub, there are a few 242 constraints around how the device must store its per-instance state and 243 how its minor numbers are used. 244 245 hcdi drivers must not store any data with ddi_get_driver_private(9F). 246 This private data is used by USBA. If it has been called before the 247 device registers, then it will fail to register successfully with the 248 USBA. However, setting it after that point will corrupt the state of the 249 USBA and likely lead to data corruption and crashes. 250 251 Similarly, part of the minor number space is utilized to represent 252 various devices like the root hub. Whenever a device driver is presented 253 with a dev_t and it's trying to extract the minor number, it must take 254 into account the constant HUBD_IS_ROOT_HUB. The following shows how to 255 perform this, given a dev_t called dev: 256 257 minor_t minor = getminor(dev) & ~HUBD_IS_ROOT_HUB; 258 259 Required Character and Device Operations 260 The USBA handles many character and device operations entry points for a 261 device driver or has strict rules on what a device driver must do in 262 them. This section summarizes those constraints. 263 264 In the dev_ops(9S) structure, the following members have special 265 significance: 266 267 devo_bus_ops 268 The devo_bus_ops member should be set to the symbol 269 usba_hubdi_busops. See usba_hubdi_dev_ops(9F) for more 270 information. 271 272 devo_power 273 The devo_power member should be set to the symbol 274 usba_hubdi_root_hub_power. See usba_hubdi_dev_ops(9F) for 275 more information. 276 277 The other standard entry points for character devices, devo_getinfo, 278 devo_attach, and devo_detach should be implemented normally as per 279 getinfo(9E), attach(9E), and detach(9E) respectively. 280 281 The following members of the cb_ops(9S) operations vector must be 282 implemented and set: 283 284 cb_open 285 The device driver should implement an open(9E) entry point 286 that obtains access to its dev_info_t and then calls 287 usba_hubdi_open(9F). See usba_hcdi_cb_open(9E) for more 288 information. 289 290 cb_close 291 The device driver should implement a close(9E) entry point 292 that obtains access to its dev_info_t and then calls 293 usba_hubdi_close(9F). 294 See usba_hcdi_cb_close(9E) for more information. 295 296 cb_ioctl 297 The device driver should implement a ioctl(9E) entry point 298 that obtains access to its dev_info_t and then calls 299 usba_hubdi_ioctl(9F). 300 301 If the device driver wishes to have private ioctls, it may 302 check the ioctl command before calling 303 usba_hubdi_ioctl(9F). Because the usba_hubdi_ioctl(9F) 304 function normally takes care of checking for the proper 305 privileges, device drivers must verify that a caller has 306 appropriate privileges before processing any private 307 ioctls. 308 309 See usba_hcdi_cb_ioctl(9E) for more information. 310 311 cb_prop_op 312 The cb_prop_op member should be set to ddi_prop_op(9F). 313 314 cb_flag 315 The cb_flag member should be set to the bitwise-inclusive- 316 OR of the D_MP flag and the D_HOTPLUG flag. 317 318 All other members of the cb_ops(9S) structure should not be implemented 319 and set to the appropriate value, such as nodev(9F) or nochpoll(9F). 320 321 Locking 322 In general, the USBA calls into a device driver through one of the 323 functions that it has register in the usba_hcdi_ops(9S) structure. 324 However, in response to a data transfer, the device driver will need to 325 call back into the USBA by calling usba_hcdi_cb(9F). 326 327 A device driver must hold no locks across the call to usba_hcdi_cb(9F). 328 Returning an I/O to the USBA, particularly an error, may result in 329 another call back to one of the usba_hcdi_cb(9F) vectors. 330 331 Outside of that constraint, the device driver should perform locking of 332 its data structures. It should assume that many of its entry points will 333 be called in parallel across the many devices that exist. 334 335 There are certain occasions where a device driver may have to enter the 336 p_mutex member of the usba_pipe_handle_data(9S) structure when 337 duplicating isochronous or interrupt requests. The USBA should in 338 general, not hold this lock across calls to the HCD driver, and in turn, 339 the HCD driver should not hold this lock across any calls back to the 340 USBA. As such, the HCD driver should make sure to incorporate the lock 341 ordering of this mutex into its broader lock ordering and operational 342 theory. Generally, the p_mutex mutex will be entered after any HCD- 343 specific locks. 344 345 The final recommendation is that due to the fact that the host controller 346 driver provides services to a multitude of USB devices at once, it should 347 strive not to hold its own internal locks while waiting for I/O to 348 complete, such as an issued command. This is particularly true if the 349 device driver uses coarse grained locking. If the device driver does not 350 pay attention to these conditions, it can easily lead to service stalls. 351 352 Synchronous and Asynchronous Entry Points 353 The majority of the entry points that a host controller driver has to 354 implement are synchronous. All actions that the entry point implies must 355 be completed before the entry point returns. However, the various 356 transfer routines: usba_hcdi_pipe_bulk_xfer(9E), 357 usba_hcdi_pipe_ctrl_xfer(9E), usba_hcdi_pipe_intr_xfer(9E), and 358 usba_hcdi_pipe_isoc_xfer(9E), are ultimately asynchronous entry points. 359 360 Each of the above entry points begins one-shot or periodic I/O. When the 361 driver returns USB_SUCCESS from one of those functions, it is expected 362 that it will later call usba_hcdi_cb(9F) when the I/O completes, whether 363 successful or not. It is the driver's responsibility to keep track of 364 these outstanding transfers and time them out. For more information on 365 timeouts, see the section Endpoint Timeouts. 366 367 If for some reason, the driver fails to initialize the I/O transfer and 368 indicates this by returning a value other than USB_SUCCESS from its entry 369 point, then it must not call usba_hcdi_cb(9F) for that transfer. 370 371 Short Transfers 372 Not all USB transfers will always return the full amount of data 373 requested in the transfer. Host controller drivers need to be ready for 374 this and report it. Each request structure has an attribute to indicate 375 whether or not short transfers are OK. If a short transfer is OK, then 376 the driver should update the transfer length. Otherwise, it should 377 instead return an error. See the individual entry point pages for more 378 information. 379 380 Root Hub Management 381 As was mentioned earlier, every host controller is also a root hub. The 382 USBA interfaces with the root hub no differently than any other hub. The 383 USBA will open pipes and issue both control and periodic interrupt-IN 384 transfers to the root hub. 385 386 In the host controller driver's usba_hcdi_pipe_open(9E) entry point, it 387 already has to look at the pipe handle it's been given to determine the 388 attributes of the endpoint it's looking at. However, before it does that 389 it needs to look at the USB address of the device the handle corresponds 390 to. If the device address matches the macro ROOT_HUB_ADDR, then this is 391 a time where the USBA is opening one of the root hub's endpoints. 392 393 Because the root hub is generally not a real device, the driver will 394 likely need to handle this in a different manner from traditional pipes. 395 396 The device driver will want to check for the presence of the device's 397 address with the following major entry points and change its behavior as 398 described: 399 400 usba_hcdi_pipe_ctrl_xfer() 401 The device driver needs to intercept control transfers 402 to the root hub and translate them into the appropriate 403 form for the device. For example, the device driver 404 may be asked to get a port's status. It should 405 determine the appropriate way to perform this, such as 406 reading a PCI memory-mapped register, and then create 407 the appropriate response. 408 409 The device driver needs to implement all of the major 410 hub specific request types. It is recommended that 411 driver writers see what existing host controller 412 drivers implement and what the hub driver currently 413 requires to implement this. 414 415 Aside from the fact that the request is not being 416 issued to a specific USB device, a request to the root 417 hub follows the normal rules for a transfer and the 418 device driver will need to call usba_hcdi_cb(9F) to 419 indicate that it has finished. 420 421 usba_hcdi_pipe_bulk_xfer() 422 The root hub does not support bulk transfers. If for 423 some reason one is requested on the root hub, the 424 driver should return USB_NOT_SUPPORTED. 425 426 usba_hcdi_pipe_intr_xfer() 427 The root hub only supports periodic interrupt-IN 428 transfers. If an interrupt-OUT transfer or an 429 interrupt-IN transfer with the USB_ATTRS_ONE_XFER 430 attribute is set, then the driver should return 431 USB_NOT_SUPPORTED. 432 433 Otherwise, this represents a request to begin polling 434 on the status endpoint for a hub. This is a periodic 435 request, see the section Device Addressing Every USB 436 device has an address assigned to it. The addresses 437 assigned to each controller are independent. The root 438 hub of a given controller always has an address of 439 ROOT_HUB_ADDR. 440 441 In general, addresses are assigned by the USBA and 442 stored in the usb_addr member of a usba_device_t(9S). 443 However, some controllers, such as xHCI, require that 444 they control the device addressing themselves to 445 facilitate their functionality. In such a case, the 446 USBA still assigns every device an address; however, 447 the actual address on the bus will be different and 448 assigned by the HCD driver. An HCD driver that needs 449 to address devices itself must implement the 450 usba_hcdi_device_address(9E) entry point. Endpoint 451 Polling more on the semantics of polling and periodic 452 requests. 453 454 Here, the device driver will need to provide data and 455 perform a callback whenever the state of one of the 456 ports changes on its virtual hub. Different drivers 457 have different ways to perform this. For example, some 458 hardware will provide an interrupt to indicate that a 459 change has occurred. Other hardware does not, so this 460 must be simulated. 461 462 The way that the status data responses must be laid out 463 is based in the USB specification. Generally, there is 464 one bit per port and the driver sets the bit for the 465 corresponding port that has had a change. 466 467 usba_hcdi_pipe_isoc_xfer() 468 The root hub does not support isochronous transfers. 469 If for some reason one is requested on the root hub, 470 the driver should return 471 472 usba_hcdi_pipe_close() 473 When a pipe to the root hub is closed, the device 474 driver should tear down whatever it created as part of 475 opening the pipe. In addition, if the pipe was an 476 interrupt-IN pipe, if it has not already had polling 477 stop, it should stop the polling as part of closing the 478 pipe. 479 480 usba_hcdi_pipe_stop_intr_polling() 481 When a request to stop interrupt polling comes in and 482 it is directed towards the root hub, the device driver 483 should cease delivering callbacks upon changes in port 484 status being detected. However, it should continue 485 keeping track of what changes have occurred for the 486 next time that polling starts. 487 488 The primary request that was used to start polling 489 should be returned, as with any other request to stop 490 interrupt polling. 491 492 usba_hcdi_pipe_stop_isoc_polling() 493 The root hub does not support isochronous transfers. 494 If for some reason it calls asking to stop polling on 495 an isochronous transfer, the device driver should log 496 an error and return USB_NOT_SUPPORTED. 497 498 Endpoint Polling 499 Both interrupt-IN and isochronous-IN endpoints are generally periodic or 500 polled endpoints. interrupt-IN polling is indicated by the lack of the 501 USB_ATTRS_ONE_XFER flag being set. All isochronous-IN transfer requests 502 are requests for polling. 503 504 Polling operates in a different fashion from traditional transfers. With 505 a traditional transfer, a single request is made and a single callback is 506 made for it, no more and no less. With a polling request, things are 507 different. A single transfer request comes in; however, the driver needs 508 to keep ensuring that transfers are being made within the polling bounds 509 until a request to stop polling comes in or a fatal error is encountered. 510 511 In many cases, as part of initializing the request, the driver will 512 prepare several transfers such that there is always an active transfer, 513 even if there is some additional latency in the system. This ensures 514 that even if there is a momentary delay in the device driver processing a 515 given transfer, I/O data will not be lost. 516 517 The driver must not use the original request structure until it is ready 518 to return due to a request to stop polling or an error. To obtain new 519 interrupt and isochronous request structures, the driver should use the 520 usba_hcdi_dup_intr_req(9F) and usba_hcdi_dup_isoc_req(9F) functions. 521 These functions also allocate the resulting message blocks that data 522 should be copied into. Note, it is possible that memory will not be 523 available to duplicate such a request. In this case, the driver should 524 use the original request to return an error and stop polling. 525 526 Request Memory and DMA 527 Each of the four transfer operations, usba_hcdi_pipe_ctrl_xfer(9E), 528 usba_hcdi_pipe_bulk_xfer(9E), usba_hcdi_pipe_intr_xfer(9E), and 529 usba_hcdi_pipe_isoc_xfer(9E) give data to hcdi drivers in the form of 530 mblk(9S) structures. To perform the individual transfers, most systems 531 devices will leverage DMA. Drivers should allocate memory suitable for 532 DMA for each transfer that they need to perform and copy the data to and 533 from the message blocks. 534 535 Device drivers should not use desballoc(9F) to try and bind the memory 536 used for DMA transfers to a message block nor should they bind the 537 message block's read pointer to a DMA handle using 538 ddi_dma_addr_bind_handle(9F). 539 540 While this isn't a strict rule, the general framework does not assume 541 that there are going to be outstanding message blocks that may be in use 542 by the controller or belong to the controller outside of the boundaries 543 of a given call to one of the transfer functions and its corresponding 544 callback. 545 546 Endpoint Timeouts 547 The host controller is in charge of watching I/Os for timeouts. For any 548 request that's not periodic (an interrupt-IN or isochronous-IN) transfer, 549 the host controller must set up a timeout handler. If that timeout 550 expires, it needs to stop the endpoint, remove that request, and return 551 to the caller. 552 553 The timeouts are specified in seconds in the request structures. For 554 bulk timeouts, the request is in the bulk_timeout member of the 555 usb_bulk_req(9S) structure. The interrupt and control transfers also 556 have a similar member in their request structures, see usb_intr_req(9S) 557 and usb_ctrl_req(9S). If any of the times is set to zero, the default 558 USBA timeout should be used. In that case, drivers should set the value 559 to the macro HCDI_DEFAULT_TIMEOUT, which is a time in seconds. 560 561 Isochronous-OUT transfers do not have a timeout defined on their request 562 structure, the usb_isoc_req(9S). Due to the periodic nature of even 563 outbound requests, it is less likely that a timeout will occur; however, 564 driver writers are encouraged to still set up the default timeout, 565 HCDI_DEFAULT_TIMEOUT, on those transfers. 566 567 The exact means of performing the timeout is best left to the driver 568 writer as the way that hardware exposes scheduling of different endpoints 569 will vary. One strategy to consider is to use the timeout(9F) function 570 at a one second period while I/O is ongoing on a per-endpoint basis. 571 Because the time is measured in seconds, a driver writer can decrement a 572 counter for a given outstanding transfer once a second and then if it 573 reaches zero, interject and stop the endpoint and clean up. 574 575 This has the added benefit that when no I/O is scheduled, then there will 576 be no timer activity, reducing overall system load. 577 578 Notable Types and Structures 579 The following are data structures and types that are used throughout host 580 controller drivers: 581 582 usb_cfg_descr 583 The configuration descriptor. A device may have one or 584 more configurations that it supports that can be switched 585 between. The descriptor is documented in 586 usb_cfg_descr(9S). 587 588 usb_dev_descr 589 The device descriptor. A device descriptor contains basic 590 properties of the device such as the USB version, device 591 and vendor information, and the maximum packet size. This 592 will often be used when setting up a device for the first 593 time. It is documented in usb_dev_descr(9S). 594 595 usb_ep_descr The endpoint descriptor. An endpoint descriptor contains 596 the basic properties of an endpoints such as its type and 597 packet size. Every endpoint on a given USB device has an 598 endpoint descriptor. It is documented in usb_ep_descr(9S). 599 600 usb_xep_descr 601 The extended endpoint descriptor. This structure is used 602 to contain the endpoint descriptor, but also additional 603 endpoint companion descriptors which are a part of newer 604 USB standards. It is documented in usb_ep_xdescr(9S). 605 606 usb_bulk_req This structure is filled out by client device drivers that 607 want to make a bulk transfer request. Host controllers use 608 this and act on it to perform bulk transfers to USB 609 devices. The structure is documented in usb_bulk_req(9S). 610 611 usb_ctrl_req This structure is filled out by client device drivers that 612 want to make a control transfer request. Host controllers 613 use this and act on it to perform bulk transfers to USB 614 devices. The structure is documented in usb_ctrl_req(9S). 615 616 usb_intr_req This structure is filled out by client device drivers that 617 want to make an interrupt transfer request. Host 618 controllers use this and act on it to perform bulk 619 transfers to USB devices. The structure is documented in 620 usb_intr_req(9S). 621 622 usb_isoc_req This structure is filled out by client device drivers that 623 want to make an isochronous transfer request. Host 624 controllers use this and act on it to perform bulk 625 transfers to USB devices. The structure is documented in 626 usb_isoc_req(9S). 627 628 usb_flags_t These define a set of flags that are used on certain entry 629 points. These generally determine whether or not the entry 630 points should block for memory allocation. Individual 631 manual pages indicate the flags that drivers should 632 consult. 633 634 usb_port_status_t 635 The usb_port_status_t determines the current negotiated 636 speed of the device. The following are valid values that 637 this may be: 638 639 USBA_LOW_SPEED_DEV 640 The device is running as a low speed device. This 641 may be a USB 1.x or USB 2.0 device. 642 643 USBA_FULL_SPEED_DEV 644 The device is running as a full speed device. This 645 may be a USB 1.x or USB 2.0 device. 646 647 USBA_HIGH_SPEED_DEV 648 The device is running as a high speed device. This 649 is a USB 2.x device. 650 651 USBA_SUPER_SPEED_DEV 652 The device is running as a super speed device. 653 This is a USB 3.0 device. 654 655 usb_cr_t 656 This is a set of codes that may be returned as a 657 part of the call to usba_hcdi_cb(9F). The best 658 place for the full set of these is currently in the 659 source control headers. 660 661 Interrupts 662 While some hardware supports more than one interrupt queue, a single 663 interrupt is generally sufficient for most host controllers. If the 664 controller supports interrupt coalescing, then the driver should 665 generally enable it and set it to a moderate rate. 666 667 driver.conf considerations 668 Due to the way host controller drivers need to interact with hotplug, 669 drivers should generally set the ddi-forceattach property to one in their 670 driver.conf(4) file. 671 672 SEE ALSO 673 driver.conf(4), hubd(7D), usba(7D), attach(9E), close(9E), detach(9E), 674 getinfo(9E), ioctl(9E), open(9E), usba_hcdi_cb_close(9E), 675 usba_hcdi_cb_ioctl(9E), usba_hcdi_cb_open(9E), 676 usba_hcdi_pipe_bulk_xfer(9E), usba_hcdi_pipe_ctrl_xfer(9E), 677 usba_hcdi_pipe_intr_xfer(9E), usba_hcdi_pipe_isoc_xfer(9E), 678 usba_hcdi_pipe_open(9E), ddi_dma_addr_bind_handle(9F), 679 ddi_get_driver_private(9F), ddi_prop_op(9F), desballoc(9F), nochpoll(9F), 680 nodev(9F), timeout(9F), usba_alloc_hcdi_ops(9F), usba_hcdi_cb(9F), 681 usba_hcdi_dup_intr_req(9F), usba_hcdi_dup_isoc_req(9F), 682 usba_hcdi_register(9F), usba_hcdi_unregister(9F), 683 usba_hubdi_bind_root_hub(9F), usba_hubdi_close(9F), 684 usba_hubdi_dev_ops(9F), usba_hubdi_ioctl(9F), usba_hubdi_open(9F), 685 usba_hubdi_unbind_root_hub(9F), cb_ops(9S), dev_ops(9S), mblk(9S), 686 usb_bulk_req(9S), usb_cfg_descr(9S), usb_ctrl_req(9S), usb_dev_descr(9S), 687 usb_ep_descr(9S), usb_ep_ss_comp_descr(9S), usb_if_descr(9S), 688 usb_intr_req(9S), usb_isoc_req(9S), usba_hcdi_ops(9S) 689 690 illumos November 18, 2016 illumos