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