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