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
20 .Sh SYNOPSIS
21 .In sys/usb/usba/hcdi.h
22 .Sh INTERFACE LEVEL
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.
28 .Sh DESCRIPTION
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.
115 .It Sy INTERRUPT
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.
124 .It Sy ISOCHRONOUS
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
334 .Dv HUBD_IS_ROOT_HUB .
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
511 .Sy USB_SUCCESS
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
522 .Sy USB_SUCCESS
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
579 .Sy USB_NOT_SUPPORTED .
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
583 .Sy USB_ATTRS_ONE_XFER
584 attribute is set, then the driver should return
585 .Sy USB_NOT_SUPPORTED .
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
643 .Sy USB_NOT_SUPPORTED .
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
649 .Sy USB_ATTRS_ONE_XFER
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
727 .Sy HCDI_DEFAULT_TIMEOUT ,
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,
736 .Sy HCDI_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
821 .It Sy USBA_LOW_SPEED_DEV
822 The device is running as a low speed device.
823 This may be a USB 1.x or USB 2.0 device.
824 .It Sy USBA_FULL_SPEED_DEV
825 The device is running as a full speed device.
826 This may be a USB 1.x or USB 2.0 device.
827 .It Sy USBA_HIGH_SPEED_DEV
828 The device is running as a high speed device.
829 This is a USB 2.x device.
830 .It Sy USBA_SUPER_SPEED_DEV
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