10229 Some man pages have incorrect cross-references
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 Xr usba_hcdi_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. 185 Depending on the hardware, this descriptor may be either static or 186 dynamic. 187 188 This device descriptor should be a packed descriptor that is the same 189 that would be read off of the device. The device descriptor should match 190 a hub of a USB generation equivalent to the maximum speed of the device. 191 For example, a USB 3.0 host controller would use a USB 3.0 hub's device 192 descriptor. Similarly, a USB 2.0 host controller would use a USB 2.0 193 hub's device descriptor. 194 195 The descriptor first starts with a USB configuration descriptor, as 196 defined in usb_cfg_descr(9S). It is then followed by an interface 197 descriptor. The definition for it can be found in usb_if_descr(9S). 198 Next is the endpoint descriptor for the single Interrupt-IN endpoint that 199 all hubs have as defined in usb_ep_descr(9S). Finally, any required 200 companion descriptors should be used. For example, a USB 3.x hub will 201 have a usb_ep_ss_comp_descr(9S) appended to the structure. 202 203 Note, that the structure needs to be packed, as though it were read from 204 a device. The structures types referenced in usb_cfg_descr(9S), 205 usb_if_descr(9S), usb_ep_descr(9S), and usb_ep_ss_comp_descr(9S) are not 206 packed for this purpose. They should not be used as they have gaps added 207 by the compiler for alignment. 208 209 Once assembled, the device driver should call 210 usba_hubdi_bind_root_hub(9F). This will cause an instance of the 211 hubd(7D) driver to be attached and associated with the root controller. 212 As such, driver writers need to ensure that all initialization is done 213 prior to loading the root hub. Once successfully loaded, driver writers 214 should assume that they'll get other calls into the driver's operation 215 vector before the call to usba_hubdi_bind_root_hub(9F.) 216 217 If the call to usba_hubdi_bind_root_hub(9F) failed for whatever reason, 218 the driver should unregister from USBA (see the next section), unwind all 219 of the resources it has allocated, and return DDI_FAILURE. 220 221 Otherwise, at this point it's safe to assume that the instance of the 222 device has initialized successfully and the driver should return 223 DDI_SUCCESS. 224 225 Driver Teardown 226 When a driver's detach(9E) entry point has been called, before anything 227 else is done, the device driver should unbind its instance of the root 228 hub and then unregister from the USBA. 229 230 To unbind the root hub, the instance of the driver should call 231 usba_hubdi_unbind_root_hub(9F). If for some reason that function does 232 not return USB_SUCCESS, then the device driver should fail the call to 233 detach(9E) and return DDI_FAILURE. 234 235 Once the root hub has been unbound, the device driver can continue by 236 removing its hcdi registration with USBA. To do this, the driver should 237 call usba_hcdi_unregister(9F). As this call always succeeds, at this 238 point, it is safe for the driver to tear down all the rest of its 239 resources and successfully detach. 240 241 State Tracking and Minor Numbers 242 Because a host controller driver is also a root hub, there are a few 243 constraints around how the device must store its per-instance state and 244 how its minor numbers are used. 245 246 hcdi drivers must not store any data with ddi_get_driver_private(9F). 247 This private data is used by USBA. If it has been called before the 248 device registers, then it will fail to register successfully with the 249 USBA. However, setting it after that point will corrupt the state of the 250 USBA and likely lead to data corruption and crashes. 251 252 Similarly, part of the minor number space is utilized to represent 253 various devices like the root hub. Whenever a device driver is presented 254 with a dev_t and it's trying to extract the minor number, it must take 255 into account the constant HUBD_IS_ROOT_HUB. The following shows how to 256 perform this, given a dev_t called dev: 257 258 minor_t minor = getminor(dev) & ~HUBD_IS_ROOT_HUB; 259 260 Required Character and Device Operations 261 The USBA handles many character and device operations entry points for a 262 device driver or has strict rules on what a device driver must do in 263 them. This section summarizes those constraints. 264 265 In the dev_ops(9S) structure, the following members have special 266 significance: 267 268 devo_bus_ops 269 The devo_bus_ops member should be set to the symbol 270 usba_hubdi_busops. See usba_hubdi_dev_ops(9F) for more 271 information. 272 273 devo_power 274 The devo_power member should be set to the symbol 275 usba_hubdi_root_hub_power. See usba_hubdi_dev_ops(9F) for 276 more information. 277 278 The other standard entry points for character devices, devo_getinfo, 279 devo_attach, and devo_detach should be implemented normally as per 280 getinfo(9E), attach(9E), and detach(9E) respectively. 281 282 The following members of the cb_ops(9S) operations vector must be 283 implemented and set: 284 285 cb_open 286 The device driver should implement an open(9E) entry point 287 that obtains access to its dev_info_t and then calls 288 usba_hubdi_open(9F). See usba_hcdi_cb_open(9E) for more 289 information. 290 291 cb_close 292 The device driver should implement a close(9E) entry point 293 that obtains access to its dev_info_t and then calls 294 usba_hubdi_close(9F). 295 See usba_hcdi_cb_close(9E) for more information. 296 297 cb_ioctl 298 The device driver should implement a ioctl(9E) entry point 299 that obtains access to its dev_info_t and then calls 300 usba_hubdi_ioctl(9F). 301 302 If the device driver wishes to have private ioctls, it may 303 check the ioctl command before calling 304 usba_hubdi_ioctl(9F). Because the usba_hubdi_ioctl(9F) 305 function normally takes care of checking for the proper 306 privileges, device drivers must verify that a caller has 307 appropriate privileges before processing any private 308 ioctls. 309 310 See usba_hcdi_cb_ioctl(9E) for more information. 311 312 cb_prop_op 313 The cb_prop_op member should be set to ddi_prop_op(9F). 314 315 cb_flag 316 The cb_flag member should be set to the bitwise-inclusive- 317 OR of the D_MP flag and the D_HOTPLUG flag. 318 319 All other members of the cb_ops(9S) structure should not be implemented 320 and set to the appropriate value, such as nodev(9F) or nochpoll(9F). 321 322 Locking 323 In general, the USBA calls into a device driver through one of the 324 functions that it has register in the usba_hcdi_ops(9S) structure. 325 However, in response to a data transfer, the device driver will need to 326 call back into the USBA by calling usba_hcdi_cb(9F). 327 328 A device driver must hold no locks across the call to usba_hcdi_cb(9F). 329 Returning an I/O to the USBA, particularly an error, may result in 330 another call back to one of the usba_hcdi_cb(9F) vectors. 331 332 Outside of that constraint, the device driver should perform locking of 333 its data structures. It should assume that many of its entry points will 334 be called in parallel across the many devices that exist. 335 336 There are certain occasions where a device driver may have to enter the 337 p_mutex member of the usba_pipe_handle_data(9S) structure when 338 duplicating isochronous or interrupt requests. The USBA should in 339 general, not hold this lock across calls to the HCD driver, and in turn, 340 the HCD driver should not hold this lock across any calls back to the 341 USBA. As such, the HCD driver should make sure to incorporate the lock 342 ordering of this mutex into its broader lock ordering and operational 343 theory. Generally, the p_mutex mutex will be entered after any HCD- 344 specific locks. 345 346 The final recommendation is that due to the fact that the host controller 347 driver provides services to a multitude of USB devices at once, it should 348 strive not to hold its own internal locks while waiting for I/O to 349 complete, such as an issued command. This is particularly true if the 350 device driver uses coarse grained locking. If the device driver does not 351 pay attention to these conditions, it can easily lead to service stalls. 352 353 Synchronous and Asynchronous Entry Points 354 The majority of the entry points that a host controller driver has to 355 implement are synchronous. All actions that the entry point implies must 356 be completed before the entry point returns. However, the various 357 transfer routines: usba_hcdi_pipe_bulk_xfer(9E), 358 usba_hcdi_pipe_ctrl_xfer(9E), usba_hcdi_pipe_intr_xfer(9E), and 359 usba_hcdi_pipe_isoc_xfer(9E), are ultimately asynchronous entry points. 360 361 Each of the above entry points begins one-shot or periodic I/O. When the 362 driver returns USB_SUCCESS from one of those functions, it is expected 363 that it will later call usba_hcdi_cb(9F) when the I/O completes, whether 364 successful or not. It is the driver's responsibility to keep track of 365 these outstanding transfers and time them out. For more information on 366 timeouts, see the section Endpoint Timeouts. 367 368 If for some reason, the driver fails to initialize the I/O transfer and 369 indicates this by returning a value other than USB_SUCCESS from its entry 370 point, then it must not call usba_hcdi_cb(9F) for that transfer. 371 372 Short Transfers 373 Not all USB transfers will always return the full amount of data 374 requested in the transfer. Host controller drivers need to be ready for 375 this and report it. Each request structure has an attribute to indicate 376 whether or not short transfers are OK. If a short transfer is OK, then 377 the driver should update the transfer length. Otherwise, it should 378 instead return an error. See the individual entry point pages for more 379 information. 380 381 Root Hub Management 382 As was mentioned earlier, every host controller is also a root hub. The 383 USBA interfaces with the root hub no differently than any other hub. The 384 USBA will open pipes and issue both control and periodic interrupt-IN 385 transfers to the root hub. 386 387 In the host controller driver's usba_hcdi_pipe_open(9E) entry point, it 388 already has to look at the pipe handle it's been given to determine the 389 attributes of the endpoint it's looking at. However, before it does that 390 it needs to look at the USB address of the device the handle corresponds 391 to. If the device address matches the macro ROOT_HUB_ADDR, then this is 392 a time where the USBA is opening one of the root hub's endpoints. 393 394 Because the root hub is generally not a real device, the driver will 395 likely need to handle this in a different manner from traditional pipes. 396 397 The device driver will want to check for the presence of the device's 398 address with the following major entry points and change its behavior as 399 described: 400 401 usba_hcdi_pipe_ctrl_xfer() 402 The device driver needs to intercept control transfers 403 to the root hub and translate them into the appropriate 404 form for the device. For example, the device driver 405 may be asked to get a port's status. It should 406 determine the appropriate way to perform this, such as 407 reading a PCI memory-mapped register, and then create 408 the appropriate response. 409 410 The device driver needs to implement all of the major 411 hub specific request types. It is recommended that 412 driver writers see what existing host controller 413 drivers implement and what the hub driver currently 414 requires to implement this. 415 416 Aside from the fact that the request is not being 417 issued to a specific USB device, a request to the root 418 hub follows the normal rules for a transfer and the 419 device driver will need to call usba_hcdi_cb(9F) to 420 indicate that it has finished. 421 422 usba_hcdi_pipe_bulk_xfer() 423 The root hub does not support bulk transfers. If for 424 some reason one is requested on the root hub, the 425 driver should return USB_NOT_SUPPORTED. 426 427 usba_hcdi_pipe_intr_xfer() 428 The root hub only supports periodic interrupt-IN 429 transfers. If an interrupt-OUT transfer or an 430 interrupt-IN transfer with the USB_ATTRS_ONE_XFER 431 attribute is set, then the driver should return 432 USB_NOT_SUPPORTED. 433 434 Otherwise, this represents a request to begin polling 435 on the status endpoint for a hub. This is a periodic 436 request, see the section Device Addressing Every USB 437 device has an address assigned to it. The addresses 438 assigned to each controller are independent. The root 439 hub of a given controller always has an address of 440 ROOT_HUB_ADDR. 441 442 In general, addresses are assigned by the USBA and 443 stored in the usb_addr member of a usba_device_t(9S). 444 However, some controllers, such as xHCI, require that 445 they control the device addressing themselves to 446 facilitate their functionality. In such a case, the 447 USBA still assigns every device an address; however, 448 the actual address on the bus will be different and 449 assigned by the HCD driver. An HCD driver that needs 450 to address devices itself must implement the 451 usba_hcdi_device_address(9E) entry point. Endpoint 452 Polling more on the semantics of polling and periodic 453 requests. 454 455 Here, the device driver will need to provide data and 456 perform a callback whenever the state of one of the 457 ports changes on its virtual hub. Different drivers 458 have different ways to perform this. For example, some 459 hardware will provide an interrupt to indicate that a 460 change has occurred. Other hardware does not, so this 461 must be simulated. 462 463 The way that the status data responses must be laid out 464 is based in the USB specification. Generally, there is 465 one bit per port and the driver sets the bit for the 466 corresponding port that has had a change. 467 468 usba_hcdi_pipe_isoc_xfer() 469 The root hub does not support isochronous transfers. 470 If for some reason one is requested on the root hub, 471 the driver should return 472 473 usba_hcdi_pipe_close() 474 When a pipe to the root hub is closed, the device 475 driver should tear down whatever it created as part of 476 opening the pipe. In addition, if the pipe was an 477 interrupt-IN pipe, if it has not already had polling 478 stop, it should stop the polling as part of closing the 479 pipe. 480 481 usba_hcdi_pipe_stop_intr_polling() 482 When a request to stop interrupt polling comes in and 483 it is directed towards the root hub, the device driver 484 should cease delivering callbacks upon changes in port 485 status being detected. However, it should continue 486 keeping track of what changes have occurred for the 487 next time that polling starts. 488 489 The primary request that was used to start polling 490 should be returned, as with any other request to stop 491 interrupt polling. 492 493 usba_hcdi_pipe_stop_isoc_polling() 494 The root hub does not support isochronous transfers. 495 If for some reason it calls asking to stop polling on 496 an isochronous transfer, the device driver should log 497 an error and return USB_NOT_SUPPORTED. 498 499 Endpoint Polling 500 Both interrupt-IN and isochronous-IN endpoints are generally periodic or 501 polled endpoints. interrupt-IN polling is indicated by the lack of the 502 USB_ATTRS_ONE_XFER flag being set. All isochronous-IN transfer requests 503 are requests for polling. 504 505 Polling operates in a different fashion from traditional transfers. With 506 a traditional transfer, a single request is made and a single callback is 507 made for it, no more and no less. With a polling request, things are 508 different. A single transfer request comes in; however, the driver needs 509 to keep ensuring that transfers are being made within the polling bounds 510 until a request to stop polling comes in or a fatal error is encountered. 511 512 In many cases, as part of initializing the request, the driver will 513 prepare several transfers such that there is always an active transfer, 514 even if there is some additional latency in the system. This ensures 515 that even if there is a momentary delay in the device driver processing a 516 given transfer, I/O data will not be lost. 517 518 The driver must not use the original request structure until it is ready 519 to return due to a request to stop polling or an error. To obtain new 520 interrupt and isochronous request structures, the driver should use the 521 usba_hcdi_dup_intr_req(9F) and usba_hcdi_dup_isoc_req(9F) functions. 522 These functions also allocate the resulting message blocks that data 523 should be copied into. Note, it is possible that memory will not be 524 available to duplicate such a request. In this case, the driver should 525 use the original request to return an error and stop polling. 526 527 Request Memory and DMA 528 Each of the four transfer operations, usba_hcdi_pipe_ctrl_xfer(9E), 529 usba_hcdi_pipe_bulk_xfer(9E), usba_hcdi_pipe_intr_xfer(9E), and 530 usba_hcdi_pipe_isoc_xfer(9E) give data to hcdi drivers in the form of 531 mblk(9S) structures. To perform the individual transfers, most systems 532 devices will leverage DMA. Drivers should allocate memory suitable for 533 DMA for each transfer that they need to perform and copy the data to and 534 from the message blocks. 535 536 Device drivers should not use desballoc(9F) to try and bind the memory 537 used for DMA transfers to a message block nor should they bind the 538 message block's read pointer to a DMA handle using 539 ddi_dma_addr_bind_handle(9F). 540 541 While this isn't a strict rule, the general framework does not assume 542 that there are going to be outstanding message blocks that may be in use 543 by the controller or belong to the controller outside of the boundaries 544 of a given call to one of the transfer functions and its corresponding 545 callback. 546 547 Endpoint Timeouts 548 The host controller is in charge of watching I/Os for timeouts. For any 549 request that's not periodic (an interrupt-IN or isochronous-IN) transfer, 550 the host controller must set up a timeout handler. If that timeout 551 expires, it needs to stop the endpoint, remove that request, and return 552 to the caller. 553 554 The timeouts are specified in seconds in the request structures. For 555 bulk timeouts, the request is in the bulk_timeout member of the 556 usb_bulk_req(9S) structure. The interrupt and control transfers also 557 have a similar member in their request structures, see usb_intr_req(9S) 558 and usb_ctrl_req(9S). If any of the times is set to zero, the default 559 USBA timeout should be used. In that case, drivers should set the value 560 to the macro HCDI_DEFAULT_TIMEOUT, which is a time in seconds. 561 562 Isochronous-OUT transfers do not have a timeout defined on their request 563 structure, the usb_isoc_req(9S). Due to the periodic nature of even 564 outbound requests, it is less likely that a timeout will occur; however, 565 driver writers are encouraged to still set up the default timeout, 566 HCDI_DEFAULT_TIMEOUT, on those transfers. 567 568 The exact means of performing the timeout is best left to the driver 569 writer as the way that hardware exposes scheduling of different endpoints 570 will vary. One strategy to consider is to use the timeout(9F) function 571 at a one second period while I/O is ongoing on a per-endpoint basis. 572 Because the time is measured in seconds, a driver writer can decrement a 573 counter for a given outstanding transfer once a second and then if it 574 reaches zero, interject and stop the endpoint and clean up. 575 576 This has the added benefit that when no I/O is scheduled, then there will 577 be no timer activity, reducing overall system load. 578 579 Notable Types and Structures 580 The following are data structures and types that are used throughout host 581 controller drivers: 582 583 usb_cfg_descr 584 The configuration descriptor. A device may have one or 585 more configurations that it supports that can be switched 586 between. The descriptor is documented in 587 usb_cfg_descr(9S). 588 589 usb_dev_descr 590 The device descriptor. A device descriptor contains basic 591 properties of the device such as the USB version, device 592 and vendor information, and the maximum packet size. This 593 will often be used when setting up a device for the first 594 time. It is documented in usb_dev_descr(9S). 595 596 usb_ep_descr The endpoint descriptor. An endpoint descriptor contains 597 the basic properties of an endpoints such as its type and 598 packet size. Every endpoint on a given USB device has an 599 endpoint descriptor. It is documented in usb_ep_descr(9S). 600 601 usb_xep_descr 602 The extended endpoint descriptor. This structure is used 603 to contain the endpoint descriptor, but also additional 604 endpoint companion descriptors which are a part of newer 605 USB standards. It is documented in usb_ep_xdescr(9S). 606 607 usb_bulk_req This structure is filled out by client device drivers that 608 want to make a bulk transfer request. Host controllers use 609 this and act on it to perform bulk transfers to USB 610 devices. The structure is documented in usb_bulk_req(9S). 611 612 usb_ctrl_req This structure is filled out by client device drivers that 613 want to make a control transfer request. Host controllers 614 use this and act on it to perform bulk transfers to USB 615 devices. The structure is documented in usb_ctrl_req(9S). 616 617 usb_intr_req This structure is filled out by client device drivers that 618 want to make an interrupt transfer request. Host 619 controllers use this and act on it to perform bulk 620 transfers to USB devices. The structure is documented in 621 usb_intr_req(9S). 622 623 usb_isoc_req This structure is filled out by client device drivers that 624 want to make an isochronous transfer request. Host 625 controllers use this and act on it to perform bulk 626 transfers to USB devices. The structure is documented in 627 usb_isoc_req(9S). 628 629 usb_flags_t These define a set of flags that are used on certain entry 630 points. These generally determine whether or not the entry 631 points should block for memory allocation. Individual 632 manual pages indicate the flags that drivers should 633 consult. 634 635 usb_port_status_t 636 The usb_port_status_t determines the current negotiated 637 speed of the device. The following are valid values that 638 this may be: 639 640 USBA_LOW_SPEED_DEV 641 The device is running as a low speed device. This 642 may be a USB 1.x or USB 2.0 device. 643 644 USBA_FULL_SPEED_DEV 645 The device is running as a full speed device. This 646 may be a USB 1.x or USB 2.0 device. 647 648 USBA_HIGH_SPEED_DEV 649 The device is running as a high speed device. This 650 is a USB 2.x device. 651 652 USBA_SUPER_SPEED_DEV 653 The device is running as a super speed device. 654 This is a USB 3.0 device. 655 656 usb_cr_t 657 This is a set of codes that may be returned as a 658 part of the call to usba_hcdi_cb(9F). The best 659 place for the full set of these is currently in the 660 source control headers. 661 662 Interrupts 663 While some hardware supports more than one interrupt queue, a single 664 interrupt is generally sufficient for most host controllers. If the 665 controller supports interrupt coalescing, then the driver should 666 generally enable it and set it to a moderate rate. 667 668 driver.conf considerations 669 Due to the way host controller drivers need to interact with hotplug, 670 drivers should generally set the ddi-forceattach property to one in their 671 driver.conf(4) file. 672 673 SEE ALSO 674 driver.conf(4), hubd(7D), usba(7D), attach(9E), close(9E), detach(9E), 675 getinfo(9E), ioctl(9E), open(9E), usba_hcdi_cb_close(9E), 676 usba_hcdi_cb_ioctl(9E), usba_hcdi_cb_open(9E), 677 usba_hcdi_pipe_bulk_xfer(9E), usba_hcdi_pipe_ctrl_xfer(9E), 678 usba_hcdi_pipe_intr_xfer(9E), usba_hcdi_pipe_isoc_xfer(9E), 679 usba_hcdi_pipe_open(9E), ddi_dma_addr_bind_handle(9F), 680 ddi_get_driver_private(9F), ddi_prop_op(9F), desballoc(9F), nochpoll(9F), 681 nodev(9F), timeout(9F), usba_alloc_hcdi_ops(9F), usba_hcdi_cb(9F), 682 usba_hcdi_dup_intr_req(9F), usba_hcdi_dup_isoc_req(9F), 683 usba_hcdi_register(9F), usba_hcdi_unregister(9F), 684 usba_hubdi_bind_root_hub(9F), usba_hubdi_close(9F), 685 usba_hubdi_dev_ops(9F), usba_hubdi_ioctl(9F), usba_hubdi_open(9F), 686 usba_hubdi_unbind_root_hub(9F), cb_ops(9S), dev_ops(9S), mblk(9S), 687 usb_bulk_req(9S), usb_cfg_descr(9S), usb_ctrl_req(9S), usb_dev_descr(9S), 688 usb_ep_descr(9S), usb_ep_ss_comp_descr(9S), usb_if_descr(9S), 689 usb_intr_req(9S), usb_isoc_req(9S), usba_hcdi_ops(9S) 690 691 illumos November 18, 2016 illumos --- EOF ---