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