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