10229 Some man pages have incorrect cross-references

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