10229 Some man pages have incorrect cross-references

   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 November 18, 2016
  15 .Dt USBA_HCDI 9E
  16 .Os
  17 .Sh NAME
  18 .Nm usba_hcdi
  19 .Nd USB Host Controller Driver Interface
  21 .In sys/usb/usba/hcdi.h
  23 .Sy Volatile -
  24 illumos USB HCD private function
  25 .Pp
  26 This describes private interfaces that are not part of the stable DDI.
  27 This may be removed or changed at any time.
  29 .Sy hcdi
  30 drivers are device drivers that support USB host controller hardware.
  31 USB host controllers provide an interface between the operating system
  32 and USB devices.
  33 They abstract the interface to the devices, often provide ways of performing
  34 DMA, and also act as the root hub.
  35 .Pp
  36 .Sy hcdi
  37 drivers are part of the illumos USB Architecture (USBA).
  38 The
  39 .Xr usba 7D
  40 driver provides support for many of the surrounding needs of an
  41 .Sy hcdi
  42 driver and requires that such drivers implement a specific operations
  43 vector,
  44 .Xr usba_hcdi_ops 9S .
  45 These functions cover everything from initialization to performing I/O
  46 to USB devices on behalf of client device drivers.
  47 .Ss USB Speed and Version Background
  48 USB devices are often referred to in two different ways.
  49 The first way is the USB version that they conform to.
  50 In the wild this looks like USB 1.1, USB 2.0, USB 3.0, etc..
  51 However, devices are also referred to as
  52 .Sq full- ,
  53 .Sq low- ,
  54 .Sq high- ,
  55 .Sq super-
  56 speed devices.
  57 .Pp
  58 The latter description describes the maximum theoretical speed of a
  59 given device.
  60 For example, a super-speed device theoretically caps out around 5 Gbit/s,
  61 whereas a low-speed device caps out at 1.5 Mbit/s.
  62 .Pp
  63 In general, each speed usually corresponds to a specific USB protocol
  64 generation.
  65 For example, all USB 3.0 devices are super-speed devices.
  66 All 'high-speed' devices are USB 2.x devices.
  67 Full-speed devices are special in that they can either be USB 1.x or USB 2.x
  68 devices.
  69 Low-speed devices are only a USB 1.x thing, they did not jump the fire line to
  70 USB 2.x.
  71 .Pp
  72 USB 3.0 devices and ports generally have the wiring for both USB 2.0 and
  73 USB 3.0.
  74 When a USB 3.0 device is plugged into a USB 2.0 port or hub, then it will report
  75 its version as USB 2.1, to indicate that it is actually a USB 3.0 device.
  76 .Ss USB Endpoint Background
  77 To understand the organization of the functions that make up the hcdi
  78 operations vector, it helps to understand how USB devices are organized
  79 and work at a high level.
  80 .Pp
  81 A given USB device is made up of
  82 .Em endpoints .
  83 A request, or transfer, is made to a specific USB endpoint.
  84 These endpoints can provide different services and have different expectations
  85 around the size of the data that'll be used in a given request and the
  86 periodicity of requests.
  87 Endpoints themselves are either used to make one-shot requests, for example,
  88 making requests to a mass storage device for a given sector, or for making
  89 periodic requests where you end up polling on the endpoint, for example, polling
  90 on a USB keyboard for keystrokes.
  91 .Pp
  92 Each endpoint encodes two different pieces of information: a direction
  93 and a type.
  94 There are two different directions: IN and OUT.
  95 These refer to the general direction that data moves relative to the operating
  96 system.
  97 For example, an IN transfer transfers data in to the operating system, from the
  98 device.
  99 An OUT transfer transfers data from the operating system, out to the device.
 100 .Pp
 101 There are four different kinds of endpoints:
 102 .Bl -tag -width Sy -offset indent
 103 .It Sy BULK
 104 These transfers are large transfers of data to or from a device.
 105 The most common use for bulk transfers is for mass storage devices.
 106 Though they are often also used by network devices and more.
 107 Bulk endpoints do not have an explicit time component to them.
 108 They are always used for one-shot transfers.
 109 .It Sy CONTROL
 110 These transfers are used to manipulate devices themselves and are used
 111 for USB protocol level operations (whether device-specific,
 112 class-specific, or generic across all of USB).
 113 Unlike other transfers, control transfers are always bi-directional and use
 114 different kinds of transfers.
 116 Interrupt transfers are used for small transfers that happen
 117 infrequently, but need reasonable latency.
 118 A good example of interrupt transfers is to receive input from a USB keyboard.
 119 Interrupt-IN transfers are generally polled.
 120 Meaning that a client (device driver) opens up an interrupt-IN endpoint to poll
 121 on it, and receives periodic updates whenever there is information available.
 122 However, Interrupt transfers can be used as one-shot transfers both going IN and
 123 OUT.
 125 These transfers are things that happen once per time-interval at a very
 126 regular rate.
 127 A good example of these transfers are for audio and video.
 128 A device may describe an interval as 10ms at which point it will read or
 129 write the next batch of data every 10ms and transform it for the user.
 130 There are no one-shot Isochronous-IN transfers.
 131 There are one-shot Isochronous-OUT transfers, but these are used by device
 132 drivers to always provide the system with sufficient data.
 133 .El
 134 .Pp
 135 To find out information about the endpoints, USB devices have a series
 136 of descriptors that cover different aspects of the device.
 137 For example, there are endpoint descriptors which cover the properties of
 138 endpoints such as the maximum packet size or polling interval.
 139 .Pp
 140 Descriptors exist at all levels of USB.
 141 For example, there are general descriptors for every device.
 142 The USB device descriptor is described in
 143 .Xr usb_dev_descr 9S .
 144 Host controllers will look at these descriptors to ensure that they
 145 program the device correctly; however, they are more often used by
 146 client device drivers.
 147 There are also descriptors that exist at a class level.
 148 For example, the hub class has a class-specific descriptor which describes
 149 properties of the hub.
 150 That information is requested for and used by the hub driver.
 151 .Pp
 152 All of the different descriptors are gathered by the system and placed
 153 into a tree, with device descriptors, configurations, endpoints, and
 154 more.
 155 Client device drivers gain access to this tree and then use them to then open
 156 endpoints, which are called pipes in USBA (and some revisions of the USB
 157 specification).
 158 .Pp
 159 Each pipe gives access to a specific endpoint on the device which can be
 160 used to perform transfers of a specific type and direction.
 161 For example, a mass storage device often has three different endpoints, the
 162 default control endpoint (which every device has), a Bulk-IN endpoint, and a
 163 Bulk-OUT endpoint.
 164 The device driver ends up with three open pipes.
 165 One to the default control endpoint to configure the device, and then the
 166 other two are used to perform I/O.
 167 .Pp
 168 These routines translate more or less directly into calls to a host
 169 controller driver.
 170 A request to open a pipe takes an endpoint descriptor that describes the
 171 properties of the pipe, and the host controller driver goes through and does any
 172 work necessary to allow the client device driver to access it.
 173 Once the pipe is open, it either makes one-shot transfers specific to the
 174 transfer type or it starts performing a periodic poll of an endpoint.
 175 .Pp
 176 All of these different actions translate into requests to the host
 177 controller.
 178 The host controller driver itself is in charge of making sure that all of the
 179 required resources for polling are allocated with a request and then proceed to
 180 give the driver's periodic callbacks.
 181 .Pp
 182 For each of the different operations described above, there is a corresponding
 183 entry in
 184 .Xr usba_hcdi_ops 9S .
 185 For example, open an endpoint, the host controller has to implement
 186 .Xr usba_hcdi_pipe_open 9E
 187 and for each transfer type, there is a different transfer function.
 188 One example is
 189 .Xr usba_hcdi_pipe_bulk_xfer 9E .
 190 See
 191 .Xr usba_hcdi_ops 9S
 192 for a full list of the different function endpoints.
 193 .Ss HCDI Initialization
 194 hcdi drivers are traditional character device drivers.
 195 To start with, an hcdi driver should define traditional
 196 .Xr dev_ops 9S
 197 and
 198 .Xr cb_ops 9S
 199 structures.
 200 To get started, the device driver should perform normal device initialization in
 201 an
 202 .Xr attach 9E
 203 entry point.
 204 For example, PCI devices should setup the device's registers and program them.
 205 In addition, all devices should configure interrupts, before getting ready to
 206 call into the USBA.
 207 Each instance of a device must be initialized and registered with the USBA.
 208 .Pp
 209 To initialize a device driver with the USBA, it must first call
 210 .Xr usba_alloc_hcdi_ops 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.
 255 For example, a USB 3.x hub will have a
 256 .Xr usb_ep_ss_comp_descr 9S
 257 appended to the structure.
 258 .Pp
 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 .
 300 If for some reason that function does not return
 301 .Sy USB_SUCCESS ,
 302 then the device driver should fail the call to
 303 .Xr detach 9E
 304 and return
 305 .Dv DDI_FAILURE .
 306 .Pp
 307 Once the root hub has been unbound, the device driver can continue by
 308 removing its hcdi registration with USBA.
 309 To do this, the driver should call
 310 .Xr usba_hcdi_unregister 9F .
 311 As this call always succeeds, at this point, it is safe for the driver
 312 to tear down all the rest of its resources and successfully detach.
 313 .Ss State Tracking and Minor Numbers
 314 Because a host controller driver is also a root hub, there are a few
 315 constraints around how the device must store its per-instance state and
 316 how its minor numbers are used.
 317 .Pp
 318 hcdi drivers
 319 .Em must not
 320 store any data with
 321 .Xr ddi_get_driver_private 9F .
 322 This private data is used by USBA.
 323 If it has been called before the device registers, then it will fail to register
 324 successfully with the USBA.
 325 However, setting it after that point will corrupt the state of the USBA and
 326 likely lead to data corruption and crashes.
 327 .Pp
 328 Similarly, part of the minor number space is utilized to represent
 329 various devices like the root hub.
 330 Whenever a device driver is presented with a
 331 .Ft dev_t
 332 and it's trying to extract the minor number, it must take into account
 333 the constant
 335 The following shows how to perform this, given a
 336 .Ft dev_t
 337 called
 338 .Ft dev :
 339 .Bd -literal -offset indent
 340 minor_t minor = getminor(dev) & ~HUBD_IS_ROOT_HUB;
 341 .Ed
 342 .Ss Required Character and Device Operations
 343 The USBA handles many character and device operations entry points for a
 344 device driver or has strict rules on what a device driver must do in
 345 them.
 346 This section summarizes those constraints.
 347 .Pp
 348 In the
 349 .Xr dev_ops 9S
 350 structure, the following members have special significance:
 351 .Bl -tag -offset indent -width Sy
 352 .It Sy devo_bus_ops
 353 The
 354 .Sy devo_bus_ops
 355 member should be set to the symbol
 356 .Sy usba_hubdi_busops .
 357 See
 358 .Xr usba_hubdi_dev_ops 9F
 359 for more information.
 360 .It Sy devo_power
 361 The
 362 .Sy devo_power
 363 member should be set to the symbol
 364 .Sy usba_hubdi_root_hub_power .
 365 See
 366 .Xr usba_hubdi_dev_ops 9F
 367 for more information.
 368 .El
 369 .Pp
 370 The other standard entry points for character devices,
 371 .Sy devo_getinfo ,
 372 .Sy devo_attach ,
 373 and
 374 .Sy devo_detach
 375 should be implemented normally as per
 376 .Xr getinfo 9E ,
 377 .Xr attach 9E ,
 378 and
 379 .Xr detach 9E
 380 respectively.
 381 .Pp
 382 The following members of the
 383 .Xr cb_ops 9S
 384 operations vector must be implemented and set:
 385 .Bl -tag -offset indent -width Sy
 386 .It Sy cb_open
 387 The device driver should implement an
 388 .Xr open 9E
 389 entry point that obtains access to its
 390 .Sy dev_info_t
 391 and then calls
 392 .Xr usba_hubdi_open 9F .
 393 See
 394 .Xr usba_hcdi_cb_open 9E
 395 for more information.
 396 .It Sy cb_close
 397 The device driver should implement a
 398 .Xr close 9E
 399 entry point that obtains access to its
 400 .Sy dev_info_t
 401 and then calls
 402 .Xr usba_hubdi_close 9F .
 403  See
 404 .Xr usba_hcdi_cb_close 9E
 405 for more information.
 406 .It Sy cb_ioctl
 407 The device driver should implement a
 408 .Xr ioctl 9E
 409 entry point that obtains access to its
 410 .Sy dev_info_t
 411 and then calls
 412 .Xr usba_hubdi_ioctl 9F .
 413 .Pp
 414 If the device driver wishes to have private ioctls, it may check the
 415 ioctl command before calling
 416 .Xr usba_hubdi_ioctl 9F .
 417 Because the
 418 .Xr usba_hubdi_ioctl 9F
 419 function normally takes care of checking for the proper privileges,
 420 device drivers must verify that a caller has appropriate privileges
 421 before processing any private ioctls.
 422 .Pp
 423 See
 424 .Xr usba_hcdi_cb_ioctl 9E
 425 for more information.
 426 .It Sy cb_prop_op
 427 The
 428 .Sy cb_prop_op
 429 member should be set to
 430 .Xr ddi_prop_op 9F .
 431 .It Sy cb_flag
 432 The
 433 .Sy cb_flag
 434 member should be set to the bitwise-inclusive-OR of the
 435 .Sy D_MP
 436 flag
 437 and the
 438 .Sy D_HOTPLUG
 439 flag.
 440 .El
 441 .Pp
 442 All other members of the
 443 .Xr cb_ops 9S
 444 structure should not be implemented and set to the appropriate value,
 445 such as
 446 .Xr nodev 9F
 447 or
 448 .Xr nochpoll 9F .
 449 .Ss Locking
 450 In general, the USBA calls into a device driver through one of the
 451 functions that it has register in the
 452 .Xr usba_hcdi_ops 9S
 453 structure.
 454 However, in response to a data transfer, the device driver will need to call
 455 back into the USBA by calling
 456 .Xr usba_hcdi_cb 9F .
 457 .Pp
 458 A device driver must hold
 459 .Em no locks
 460 across the call to
 461 .Xr usba_hcdi_cb 9F .
 462 Returning an I/O to the USBA, particularly an error, may result in
 463 another call back to one of the
 464 .Xr usba_hcdi_cb 9F
 465 vectors.
 466 .Pp
 467 Outside of that constraint, the device driver should perform locking of
 468 its data structures.
 469 It should assume that many of its entry points will be called in parallel across
 470 the many devices that exist.
 471 .Pp
 472 There are certain occasions where a device driver may have to enter the
 473 .Sy p_mutex
 474 member of the
 475 .Xr usba_pipe_handle_data 9S
 476 structure when duplicating isochronous or interrupt requests.
 477 The USBA should in general, not hold this lock across calls to the HCD driver,
 478 and in turn, the HCD driver should not hold this lock across any calls back to
 479 the USBA.
 480 As such, the HCD driver should make sure to incorporate the lock ordering of
 481 this mutex into its broader lock ordering and operational theory.
 482 Generally, the
 483 .Sy p_mutex
 484 mutex will be entered after any HCD-specific locks.
 485 .Pp
 486 The final recommendation is that due to the fact that the host
 487 controller driver provides services to a multitude of USB devices at
 488 once, it should strive not to hold its own internal locks while waiting
 489 for I/O to complete, such as an issued command.
 490 This is particularly true if the device driver uses coarse grained locking.
 491 If the device driver does not pay attention to these conditions, it can easily
 492 lead to service stalls.
 493 .Ss Synchronous and Asynchronous Entry Points
 494 The majority of the entry points that a host controller driver has to
 495 implement are
 496 .Em synchronous .
 497 All actions that the entry point implies must be completed before the
 498 entry point returns.
 499 However, the various transfer routines:
 500 .Xr usba_hcdi_pipe_bulk_xfer 9E ,
 501 .Xr usba_hcdi_pipe_ctrl_xfer 9E ,
 502 .Xr usba_hcdi_pipe_intr_xfer 9E ,
 503 and
 504 .Xr usba_hcdi_pipe_isoc_xfer 9E ,
 505 are ultimately
 506 .Em asynchronous
 507 entry points.
 508 .Pp
 509 Each of the above entry points begins one-shot or periodic I/O.
 510 When the driver returns
 512 from one of those functions, it is expected that it will later call
 513 .Xr usba_hcdi_cb 9F
 514 when the I/O completes, whether successful or not.
 515 It is the driver's responsibility to keep track of these outstanding transfers
 516 and time them out.
 517 For more information on timeouts, see the section
 518 .Sx Endpoint Timeouts .
 519 .Pp
 520 If for some reason, the driver fails to initialize the I/O transfer and
 521 indicates this by returning a value other than
 523 from its entry point, then it must not call
 524 .Xr usba_hcdi_cb 9F
 525 for that transfer.
 526 .Ss Short Transfers
 527 Not all USB transfers will always return the full amount of data
 528 requested in the transfer.
 529 Host controller drivers need to be ready for this and report it.
 530 Each request structure has an attribute to indicate whether or not short
 531 transfers are OK.
 532 If a short transfer is OK, then the driver should update the transfer length.
 533 Otherwise, it should instead return an error.
 534 See the individual entry point pages for more information.
 535 .Ss Root Hub Management
 536 As was mentioned earlier, every host controller is also a root hub.
 537 The USBA interfaces with the root hub no differently than any other hub.
 538 The USBA will open pipes and issue both control and periodic interrupt-IN
 539 transfers to the root hub.
 540 .Pp
 541 In the host controller driver's
 542 .Xr usba_hcdi_pipe_open 9E
 543 entry point, it already has to look at the pipe handle it's been given
 544 to determine the attributes of the endpoint it's looking at.
 545 However, before it does that it needs to look at the USB address of the device
 546 the handle corresponds to.
 547 If the device address matches the macro
 548 .Sy ROOT_HUB_ADDR ,
 549 then this is a time where the USBA is opening one of the root hub's
 550 endpoints.
 551 .Pp
 552 Because the root hub is generally not a real device, the driver will
 553 likely need to handle this in a different manner from traditional pipes.
 554 .Pp
 555 The device driver will want to check for the presence of the device's
 556 address with the following major entry points and change its behavior as
 557 described:
 558 .Bl -tag -width Fn
 559 .It Fn usba_hcdi_pipe_ctrl_xfer
 560 The device driver needs to intercept control transfers to the root hub
 561 and translate them into the appropriate form for the device.
 562 For example, the device driver may be asked to get a port's status.
 563 It should determine the appropriate way to perform this, such as reading a
 564 PCI memory-mapped register, and then create the appropriate response.
 565 .Pp
 566 The device driver needs to implement all of the major hub specific
 567 request types.
 568 It is recommended that driver writers see what existing host controller drivers
 569 implement and what the hub driver currently requires to implement this.
 570 .Pp
 571 Aside from the fact that the request is not being issued to a specific
 572 USB device, a request to the root hub follows the normal rules for a
 573 transfer and the device driver will need to call
 574 .Xr usba_hcdi_cb 9F
 575 to indicate that it has finished.
 576 .It Fn usba_hcdi_pipe_bulk_xfer
 577 The root hub does not support bulk transfers.
 578 If for some reason one is requested on the root hub, the driver should return
 580 .It Fn usba_hcdi_pipe_intr_xfer
 581 The root hub only supports periodic interrupt-IN transfers.
 582 If an interrupt-OUT transfer or an interrupt-IN transfer with the
 584 attribute is set, then the driver should return
 586 .Pp
 587 Otherwise, this represents a request to begin polling on the status
 588 endpoint for a hub.
 589 This is a periodic request, see the section
 590 .Sx Device Addressing
 591 Every USB device has an address assigned to it.
 592 The addresses assigned to each controller are independent.
 593 The root hub of a given controller always has an address of
 594 .Dv ROOT_HUB_ADDR .
 595 .Pp
 596 In general, addresses are assigned by the USBA and stored in the
 597 .Sy usb_addr
 598 member of a
 599 .Xr usba_device_t 9S .
 600 However, some controllers, such as xHCI, require that they control the
 601 device addressing themselves to facilitate their functionality.
 602 In such a case, the USBA still assigns every device an address; however, the
 603 actual address on the bus will be different and assigned by the HCD
 604 driver.
 605 An HCD driver that needs to address devices itself must implement the
 606 .Xr usba_hcdi_device_address 9E
 607 entry point.
 608 .Sx Endpoint Polling
 609 more on the semantics of polling and periodic requests.
 610 .Pp
 611 Here, the device driver will need to provide data and perform a callback
 612 whenever the state of one of the ports changes on its virtual hub.
 613 Different drivers have different ways to perform this.
 614 For example, some hardware will provide an interrupt to indicate that a change
 615 has occurred.
 616 Other hardware does not, so this must be simulated.
 617 .Pp
 618 The way that the status data responses must be laid out is based in the
 619 USB specification.
 620 Generally, there is one bit per port and the driver sets the bit for the
 621 corresponding port that has had a change.
 622 .It Fn usba_hcdi_pipe_isoc_xfer
 623 The root hub does not support isochronous transfers.
 624 If for some reason one is requested on the root hub, the driver should return
 625 .It Fn usba_hcdi_pipe_close
 626 When a pipe to the root hub is closed, the device driver should tear
 627 down whatever it created as part of opening the pipe.
 628 In addition, if the pipe was an interrupt-IN pipe, if it has not already had
 629 polling stop, it should stop the polling as part of closing the pipe.
 630 .It Fn usba_hcdi_pipe_stop_intr_polling
 631 When a request to stop interrupt polling comes in and it is directed
 632 towards the root hub, the device driver should cease delivering
 633 callbacks upon changes in port status being detected.
 634 However, it should continue keeping track of what changes have occurred for the
 635 next time that polling starts.
 636 .Pp
 637 The primary request that was used to start polling should be returned,
 638 as with any other request to stop interrupt polling.
 639 .It Fn usba_hcdi_pipe_stop_isoc_polling
 640 The root hub does not support isochronous transfers.
 641 If for some reason it calls asking to stop polling on an isochronous transfer,
 642 the device driver should log an error and return
 644 .El
 645 .Ss Endpoint Polling
 646 Both interrupt-IN and isochronous-IN endpoints are generally periodic or
 647 polled endpoints.
 648 interrupt-IN polling is indicated by the lack of the
 650 flag being set.
 651 All isochronous-IN transfer requests are requests for polling.
 652 .Pp
 653 Polling operates in a different fashion from traditional transfers.
 654 With a traditional transfer, a single request is made and a single callback
 655 is made for it, no more and no less.
 656 With a polling request, things are different.
 657 A single transfer request comes in; however, the driver needs to keep ensuring
 658 that transfers are being made within the polling bounds until a request to stop
 659 polling comes in or a fatal error is encountered.
 660 .Pp
 661 In many cases, as part of initializing the request, the driver will
 662 prepare several transfers such that there is always an active transfer,
 663 even if there is some additional latency in the system.
 664 This ensures that even if there is a momentary delay in the device driver
 665 processing a given transfer, I/O data will not be lost.
 666 .Pp
 667 The driver must not use the original request structure until it is ready
 668 to return due to a request to stop polling or an error.
 669 To obtain new interrupt and isochronous request structures, the driver should
 670 use the
 671 .Xr usba_hcdi_dup_intr_req 9F
 672 and
 673 .Xr usba_hcdi_dup_isoc_req 9F
 674 functions.
 675 These functions also allocate the resulting message blocks that data should be
 676 copied into.
 677 Note, it is possible that memory will not be available to duplicate such a
 678 request.
 679 In this case, the driver should use the original request to return an error and
 680 stop polling.
 681 .Ss Request Memory and DMA
 682 Each of the four transfer operations,
 683 .Xr usba_hcdi_pipe_ctrl_xfer 9E ,
 684 .Xr usba_hcdi_pipe_bulk_xfer 9E ,
 685 .Xr usba_hcdi_pipe_intr_xfer 9E ,
 686 and
 687 .Xr usba_hcdi_pipe_isoc_xfer 9E
 688 give data to hcdi drivers in the form of
 689 .Xr mblk 9S
 690 structures.
 691 To perform the individual transfers, most systems devices will leverage DMA.
 692 Drivers should allocate memory suitable for DMA for each transfer that they need
 693 to perform and copy the data to and from the message blocks.
 694 .Pp
 695 Device drivers should not use
 696 .Xr desballoc 9F
 697 to try and bind the memory used for DMA transfers to a message block nor
 698 should they bind the message block's read pointer to a DMA handle using
 699 .Xr ddi_dma_addr_bind_handle 9F .
 700 .Pp
 701 While this isn't a strict rule, the general framework does not assume
 702 that there are going to be outstanding message blocks that may be in use
 703 by the controller or belong to the controller outside of the boundaries
 704 of a given call to one of the transfer functions and its corresponding
 705 callback.
 706 .Ss Endpoint Timeouts
 707 The host controller is in charge of watching I/Os for timeouts.
 708 For any request that's not periodic (an interrupt-IN or isochronous-IN)
 709 transfer, the host controller must set up a timeout handler.
 710 If that timeout expires, it needs to stop the endpoint, remove that request, and
 711 return to the caller.
 712 .Pp
 713 The timeouts are specified in seconds in the request structures.
 714 For bulk timeouts, the request is in the
 715 .Sy bulk_timeout
 716 member of the
 717 .Xr usb_bulk_req 9S
 718 structure.
 719 The interrupt and control transfers also have a similar member in their request
 720 structures, see
 721 .Xr usb_intr_req 9S
 722 and
 723 .Xr usb_ctrl_req 9S .
 724 If any of the times is set to zero, the default USBA timeout should be
 725 used.
 726 In that case, drivers should set the value to the macro
 728 which is a time in seconds.
 729 .Pp
 730 Isochronous-OUT transfers do not have a timeout defined on their request
 731 structure, the
 732 .Xr usb_isoc_req 9S .
 733 Due to the periodic nature of even outbound requests, it is less likely
 734 that a timeout will occur; however, driver writers are encouraged to
 735 still set up the default timeout,
 737 on those transfers.
 738 .Pp
 739 The exact means of performing the timeout is best left to the driver
 740 writer as the way that hardware exposes scheduling of different
 741 endpoints will vary.
 742 One strategy to consider is to use the
 743 .Xr timeout 9F
 744 function at a one second period while I/O is ongoing on a per-endpoint
 745 basis.
 746 Because the time is measured in seconds, a driver writer can decrement a counter
 747 for a given outstanding transfer once a second and then if it reaches zero,
 748 interject and stop the endpoint and clean up.
 749 .Pp
 750 This has the added benefit that when no I/O is scheduled, then there
 751 will be no timer activity, reducing overall system load.
 752 .Ss Notable Types and Structures
 753 The following are data structures and types that are used throughout
 754 host controller drivers:
 755 .Bl -tag -width Vt
 756 .It Sy usb_cfg_descr
 757 The configuration descriptor.
 758 A device may have one or more configurations that it supports that can be
 759 switched between.
 760 The descriptor is documented in
 761 .Xr usb_cfg_descr 9S .
 762 .It Sy usb_dev_descr
 763 The device descriptor.
 764 A device descriptor contains basic properties of the device such as the USB
 765 version, device and vendor information, and the maximum packet size.
 766 This will often be used when setting up a device for the first time.
 767 It is documented in
 768 .Xr usb_dev_descr 9S .
 769 .It Sy usb_ep_descr
 770 The endpoint descriptor.
 771 An endpoint descriptor contains the basic properties of an endpoints such as its
 772 type and packet size.
 773 Every endpoint on a given USB device has an endpoint descriptor.
 774 It is documented in
 775 .Xr usb_ep_descr 9S .
 776 .It Sy usb_xep_descr
 777 The extended endpoint descriptor.
 778 This structure is used to contain the endpoint descriptor, but also additional
 779 endpoint companion descriptors which are a part of newer USB standards.
 780 It is documented in
 781 .Xr usb_ep_xdescr 9S .
 782 .It Sy usb_bulk_req
 783 This structure is filled out by client device drivers that want to make
 784 a bulk transfer request.
 785 Host controllers use this and act on it to perform bulk transfers to USB
 786 devices.
 787 The structure is documented in
 788 .Xr usb_bulk_req 9S .
 789 .It Sy usb_ctrl_req
 790 This structure is filled out by client device drivers that want to make
 791 a control transfer request.
 792 Host controllers use this and act on it to perform bulk transfers to USB
 793 devices.
 794 The structure is documented in
 795 .Xr usb_ctrl_req 9S .
 796 .It Sy usb_intr_req
 797 This structure is filled out by client device drivers that want to make
 798 an interrupt transfer request.
 799 Host controllers use this and act on it to perform bulk transfers to USB
 800 devices.
 801 The structure is documented in
 802 .Xr usb_intr_req 9S .
 803 .It Sy usb_isoc_req
 804 This structure is filled out by client device drivers that want to make
 805 an isochronous transfer request.
 806 Host controllers use this and act on it to perform bulk transfers to USB
 807 devices.
 808 The structure is documented in
 809 .Xr usb_isoc_req 9S .
 810 .It Vt usb_flags_t
 811 These define a set of flags that are used on certain entry points.
 812 These generally determine whether or not the entry points should block for
 813 memory allocation.
 814 Individual manual pages indicate the flags that drivers should consult.
 815 .It Vt usb_port_status_t
 816 The
 817 .Sy usb_port_status_t
 818 determines the current negotiated speed of the device.
 819 The following are valid values that this may be:
 820 .Bl -tag -width Sy
 822 The device is running as a low speed device.
 823 This may be a USB 1.x or USB 2.0 device.
 825 The device is running as a full speed device.
 826 This may be a USB 1.x or USB 2.0 device.
 828 The device is running as a high speed device.
 829 This is a USB 2.x device.
 831 The device is running as a super speed device.
 832 This is a USB 3.0 device.
 833 .It Vt usb_cr_t
 834 This is a set of codes that may be returned as a part of the call to
 835 .Xr usba_hcdi_cb 9F .
 836 The best place for the full set of these is currently in the source
 837 control headers.
 838 .El
 839 .El
 840 .Ss Interrupts
 841 While some hardware supports more than one interrupt queue, a single
 842 interrupt is generally sufficient for most host controllers.
 843 If the controller supports interrupt coalescing, then the driver should
 844 generally enable it and set it to a moderate rate.
 845 .Ss driver.conf considerations
 846 Due to the way host controller drivers need to interact with hotplug,
 847 drivers should generally set the
 848 .Sy ddi-forceattach
 849 property to one in their
 850 .Xr driver.conf 4
 851 file.
 852 .Sh SEE ALSO
 853 .Xr driver.conf 4 ,
 854 .Xr hubd 7D ,
 855 .Xr usba 7D ,
 856 .Xr attach 9E ,
 857 .Xr close 9E ,
 858 .Xr detach 9E ,
 859 .Xr getinfo 9E ,
 860 .Xr ioctl 9E ,
 861 .Xr open 9E ,
 862 .Xr usba_hcdi_cb_close 9E ,
 863 .Xr usba_hcdi_cb_ioctl 9E ,
 864 .Xr usba_hcdi_cb_open 9E ,
 865 .Xr usba_hcdi_pipe_bulk_xfer 9E ,
 866 .Xr usba_hcdi_pipe_ctrl_xfer 9E ,
 867 .Xr usba_hcdi_pipe_intr_xfer 9E ,
 868 .Xr usba_hcdi_pipe_isoc_xfer 9E ,
 869 .Xr usba_hcdi_pipe_open 9E ,
 870 .Xr ddi_dma_addr_bind_handle 9F ,
 871 .Xr ddi_get_driver_private 9F ,
 872 .Xr ddi_prop_op 9F ,
 873 .Xr desballoc 9F ,
 874 .Xr nochpoll 9F ,
 875 .Xr nodev 9F ,
 876 .Xr timeout 9F ,
 877 .Xr usba_alloc_hcdi_ops 9F ,
 878 .Xr usba_hcdi_cb 9F ,
 879 .Xr usba_hcdi_dup_intr_req 9F ,
 880 .Xr usba_hcdi_dup_isoc_req 9F ,
 881 .Xr usba_hcdi_register 9F ,
 882 .Xr usba_hcdi_unregister 9F ,
 883 .Xr usba_hubdi_bind_root_hub 9F ,
 884 .Xr usba_hubdi_close 9F ,
 885 .Xr usba_hubdi_dev_ops 9F ,
 886 .Xr usba_hubdi_ioctl 9F ,
 887 .Xr usba_hubdi_open 9F ,
 888 .Xr usba_hubdi_unbind_root_hub 9F ,
 889 .Xr cb_ops 9S ,
 890 .Xr dev_ops 9S ,
 891 .Xr mblk 9S ,
 892 .Xr usb_bulk_req 9S ,
 893 .Xr usb_cfg_descr 9S ,
 894 .Xr usb_ctrl_req 9S ,
 895 .Xr usb_dev_descr 9S ,
 896 .Xr usb_ep_descr 9S ,
 897 .Xr usb_ep_ss_comp_descr 9S ,
 898 .Xr usb_if_descr 9S ,
 899 .Xr usb_intr_req 9S ,
 900 .Xr usb_isoc_req 9S ,
 901 .Xr usba_hcdi_ops 9S
--- EOF ---