rom/usb/docs/usbhardware.doc

   1 TABLE OF CONTENTS
   2
   3 usbhardware.device/--background--
   4 usbhardware.device/CMD_FLUSH
   5 usbhardware.device/CMD_RESET
   6 usbhardware.device/UHCMD_BULKXFER
   7 usbhardware.device/UHCMD_CONTROLXFER
   8 usbhardware.device/UHCMD_INTXFER
   9 usbhardware.device/UHCMD_ISOXFER
  10 usbhardware.device/UHCMD_QUERYDEVICE
  11 usbhardware.device/UHCMD_USBOPER
  12 usbhardware.device/UHCMD_USBRESET
  13 usbhardware.device/UHCMD_USBRESUME
  14 usbhardware.device/UHCMD_USBSUSPEND
  15
  16
  17 \fusbhardware.device/--background--           usbhardware.device/--background--
  18
  19    PURPOSE
  20        A usbhardware.device provides an API to various hardware
  21        implementations of USB host controllers. According to the USB specs,
  22        it may be referenced best as the host controller driver (HDC).
  23
  24        This hardware API is used by the Poseidon USB protocol stack to
  25        'talk' to the USB hardware.
  26
  27        This document is dated to 14-Feb-07 09:26:22.
  28
  29    OVERVIEW
  30        The abstraction level is that of the transaction layer: the device
  31        must be able to send a series of packets to the USB and receive
  32        and reassemble multiple packets from the USB.
  33
  34        USB protocol error recovery is done inside the device (NAK handling,
  35        retry on error) without explicit interaction from the caller.
  36
  37        The device must support the four transfer types interrupt, control,
  38        bulk and isochroneous, it must be able to handle lowspeed devices
  39        as well as fullspeed devices.
  40
  41        Also, USB constraints on the bus bandwidth allocation should be
  42        followed.
  43
  44    ROOT HUB
  45        The root hub must appear after a bus reset as default device on the
  46        bus with address 0. It should have the ability to be configured like
  47        any external hub. If your hardware does not provide a standard USB
  48        hub device, you will have to emulate the root hub functionality. See
  49        the USB specifications (chapter 11) for details.
  50
  51        You must at least support the following standard descriptors:
  52        Device Descriptor, Configuration Descriptor, Interface Descriptor,
  53        Endpoint Descriptor, and Hub Descriptor. Other supported standard
  54        requests and hub class requests must include ClearHubFeature,
  55        ClearPortFeature, GetHubDescriptor, GetHubStatus, GetPortStatus,
  56        SetHubFeature, and SetPortFeature.
  57
  58        The hub requires to have an interrupt endpoint that returns the
  59        status on a change of the port features. If the hardware allows more
  60        efficient status check, interrupt requests to this endpoint can also
  61        be queued and emulated of course.
  62
  63        For USB 2.0, the root hub might not get the UHFF_HIGHSPEED bit set
  64        for the first transactions. Normally, this should not be a problem,
  65        but cater for this (see below).
  66
  67    DATA SEQUENCE TOGGLES
  68        Your driver has to check for correct DATA0/1 PID schemes as
  69        specified in the USB specs. You have to keep track of the outgoing
  70        toggle bits. Toggles are reset for an endpoint if a
  71        ClearFeature(Endpoint_Halt) is successfully sent.
  72        If SetAddress is sent, you must clear all toggle bits for all 16
  73        possible endpoints of the target device.
  74
  75        Please be sure to get this right and TEST it. This must be working
  76        for both BULK and INTERRUPT transfers. Control transfers keep track
  77        of their toggle bits within the transfer.
  78
  79    QUEUEING
  80        Multiple requests to the very same endpoint of a device must be
  81        queued in order (instead of being executed in parallel). This means
  82        you have to keep track of the currently scheduled IORequests for
  83        each endpoint.
  84
  85    NAK TIMEOUT
  86        It is essential to implement the NAK TIMEOUT feature for BULK,
  87        INTERRUPT and even for CONTROL transfers. Without this, several
  88        higher level class drivers will appear to hang until the device is
  89        removed in certain error cases. On successfully received packets,
  90        the NAK TIMEOUT timer needs to be reset.
  91
  92    USB 2.0
  93        With the emergence of USB 2.0, Poseidon has added support for this by
  94        extending the IORequest structure slightly with V3.x. New flags
  95        include UHFF_HIGHSPEED (which has been there since the beginning)
  96        and UHFF_SPLITTRANS. Poseidon V3.6 also adds UHFF_MULTI_1,
  97        UHFF_MULTI_2 and UHFF_MULTI_3 and fixes some bugs.
  98
  99        The new fields iouh_SplitHubAddr and iouh_SplitHubPort are filled
 100        for USB 2.0 lowspeed and fullspeed split transactions. Note that
 101        these fields are wrong for versions before V3.6 in the case you
 102        have USB devices after a USB 1.1 hub after a USB 2.0 hub.
 103
 104        If your root hub is USB 2.0, Poseidon will not know this until it
 105        reads a USB 2.0 version number from the device descriptor. Hence,
 106        it will not use UHFF_HIGHSPEED during enumeration of the root hub.
 107        However, this is not a problem because the root hub can assume
 108        highspeed transactions unless the UHFF_SPLITTRANS bit is set for
 109        downstream low- and fullspeed USB 1.1 devices.
 110
 111        The iouh_Interval field will use units of ms for USB 1.1 or units
 112        of µFrames for highspeed transfers. It will not store x for 2^x,
 113        but the real value 2^x.
 114
 115    NOTES
 116        The device should support multiple units whenever more than one
 117        host controller of the supported type may be mounted. It is
 118        recommended that units are opened on an exclusive basis.
 119
 120        All fields except the iouh_Actual, io_Error, iouh_State and
 121        iouh_ExtError fields shall not be modified by the device driver.
 122
 123        With the V2 driver structures available in Poseidon V3.x and higher,
 124        iouh_DriverPrivate1 and iouh_DriverPrivate2 are for your drivers
 125        private use and can store anything you like.
 126
 127        Data should be transferred via DMA on hardware implementations where
 128        this is possible. Please take care of alignments and data field
 129        lengths. While it normally should be the case that iouh_Data is
 130        aligned on an even address, for bulk transfers maybe even on
 131        a longword address, this is not guaranteed. Also, the length may
 132        be of any odd value. Do not trash data behind the buffer.
 133
 134        Be sure that the driver is able to send 0-bytes packets and
 135        transfers accordingly. For OUT transfers, respect the
 136        UHFF_NOSHORTPKT flag whenever the size of the transfer is a multiple
 137        of iouh_MaxPktSize.
 138
 139        Also notice, that iouh_MaxPktSize does not have to be a power of
 140        two for interrupt or iso endpoints for your arithmetics.
 141
 142
 143 \fusbhardware.device/CMD_FLUSH                     usbhardware.device/CMD_FLUSH
 144
 145    NAME
 146         CMD_FLUSH -- cancel all pending transfer requests
 147
 148    FUNCTION
 149         CMD_FLUSH aborts all UHCMD_CONTROLXFER, UHCMD_ISOXFER, UHCMD_INTXFER
 150         and UHCMD_BULKXFER requests in progress or queued.
 151
 152    INPUTS
 153         mn_ReplyPort - pointer to message port that receives I/O request
 154                        if the quick flag (IOF_QUICK) is clear
 155         io_Device    - pointer to device node, must be set by (or copied from
 156                        I/O block set by) OpenDevice function
 157         io_Unit      - pointer to unit node to flush, set by OpenDevice
 158         io_Command   - command number for CMD_FLUSH
 159         io_Flags     - flags, must be cleared if not use:
 160                        IOF_QUICK - (CLEAR) reply I/O request
 161
 162    OUTPUTS
 163         none
 164
 165
 166 \fusbhardware.device/CMD_RESET                     usbhardware.device/CMD_RESET
 167
 168    NAME
 169         CMD_RESET -- reset the hardware to a predefined state
 170
 171    FUNCTION
 172         CMD_RESET performs a hardware reset cycle. The hardware then is in a
 173         predefined state. This will also cause a reset on the USB and the
 174         bus going into operational state after about 50ms.
 175
 176    INPUTS
 177         mn_ReplyPort - pointer to message port that receives I/O request
 178                        if the quick flag (IOF_QUICK) is clear
 179         io_Device    - pointer to device node, must be set by (or copied from
 180                        I/O block set by) OpenDevice() function
 181         io_Unit      - pointer to unit node to reset, set by OpenDevice()
 182         io_Command   - command number for CMD_RESET
 183         io_Flags     - flags, must be cleared if not use:
 184                        IOF_QUICK - (CLEAR) reply I/O request
 185
 186    OUTPUTS
 187         io_Error     - either 0, if everything went okay or
 188                        UHIOERR_HOSTERROR, if bus was not in operational state
 189                        after the bus reset.
 190    SEE ALSO
 191         UHCMD_USBRESET
 192
 193
 194 \fusbhardware.device/UHCMD_BULKXFER           usbhardware.device/UHCMD_BULKXFER
 195
 196    NAME
 197         UHCMD_BULKXFER -- start a bulk transfer to or from the bus
 198
 199    FUNCTION
 200         Starts a bulk transfer with the amount of data specified. The
 201         direction of the transfer (host to device or device to host) is
 202         determined by the setting in the iouh_Dir field.
 203
 204         The data itself is split into packets of iouh_MaxPktSize length.
 205         For IN-transactions, iouh_Data holds a pointer to the buffer to be
 206         filled, for OUT-transactions, iouh_Data is a pointer to the data
 207         to send to the device.
 208
 209         In case of an error, the transfer will be retried up to three times.
 210
 211    INPUTS
 212         mn_ReplyPort - pointer to message port that receives I/O request
 213                        if the quick flag (IOF_QUICK) is clear
 214         io_Device    - pointer to device node, must be set by (or copied from
 215                        I/O block set by) OpenDevice() function
 216         io_Unit      - pointer to unit node to use, set by OpenDevice()
 217         io_Command   - command number for UHCMD_CONTROLXFER
 218         io_Flags     - flags, must be cleared if not use:
 219                        IOF_QUICK - (CLEAR) reply I/O request
 220
 221         iouh_Flags        - UHFF_LOWSPEED for low speed devices.
 222                             UHFF_HIGHSPEED for high speed USB2.0 devices.
 223                             full speed devices will be assumed otherwise.
 224                             UHFF_SPLITTRANS for low or fullspeed devices
 225                             behind a USB 2.0 hub. iouh_SplitHubAddr and
 226                             iouh_SplitHubPort are set accordingly.
 227                             UHFF_MULTI_1, UHFF_MULTI_2, UHFF_MULTI_3
 228                             indicating the number of transactions per µFrame
 229                             for highspeed transfers.
 230                             UHFF_NOSHORTPKT will not send terminating short
 231                             packets (if the transfer length is a multiple
 232                             of iouh_MaxPktSize). This allows you to create
 233                             a continous bulk stream with multiple requests.
 234                             UHFF_NAKTIMEOUT will enable the NAK timeout
 235                             feature (see below).
 236                             If UHFF_ALLOWRUNTPKTS is set, the request will
 237                             not return UHIOERR_RUNTPACKET in any case. You
 238                             should check iouh_Actual for the amount of data
 239                             transferred.
 240         iouh_Dir          - either UHDIR_IN for device to host transfers
 241                             or UHDIR_OUT for host to device transfers.
 242         iouh_DevAddr      - device address from 0 to 127.
 243         iouh_Endpoint     - endpoint number from 0 to 15.
 244         iouh_MaxPktSize   - maximum size of a packet for this endpoint.
 245         iouh_Data         - pointer to a buffer to transport the data.
 246         iouh_Length       - number of bytes to transfer.
 247         iouh_SplitHubAddr - for split transactions only: the hub device
 248                             address from 0 to 127.
 249         iouh_SplitHubPort - for split transactions only: the hub port number
 250                             the USB 1.1 device is connected to from 0 to 255.
 251         iouh_NakTimeout   - if UHFF_NAKTIMEOUT is enabled, this specifies
 252                             the time in milliseconds until the request will
 253                             be retired with UHIOERR_NAKTIMEOUT due to the
 254                             endpoint constantly denying the request with
 255                             NAKs. This can be used to avoid hangs on a broken
 256                             USB unit. 1000 (1 second) is a reasonable value.
 257
 258
 259    OUTPUTS
 260         iouh_Actual  - actual bytes transferred.
 261         io_Error     - if something went wrong, you will find a non-null
 262                        value here, indicating the error.
 263
 264    SEE ALSO
 265         UHCMD_CONTROLXFER, UHCMD_INTXFER, UHCMD_ISOXFER
 266
 267
 268 \fusbhardware.device/UHCMD_CONTROLXFER     usbhardware.device/UHCMD_CONTROLXFER
 269
 270    NAME
 271         UHCMD_CONTROLXFER -- start a control transfer to or from the bus
 272
 273    FUNCTION
 274         Starts a control transfer, containing a Setup phase, optional
 275         Data phases (in or out) and the final Status phase.
 276
 277         The setup stage contains an 8 byte packet, with the USB standard
 278         fields bmRequestType, bRequest, wIndex, wValue and wLength.
 279
 280         If iouh_Length is greater than zero, a data phase is initiated and
 281         the data is split into packets smaller than or equal to
 282         iouh_MaxPktSize.
 283
 284         The direction of the transfer (buffer to device or device to buffer)
 285         is determined by the most significant bit of the bmRequestType field
 286         in the setup packet.
 287
 288         Finally, in the status stage the host controller will send a zero
 289         byte data packet to terminate the control transfer.
 290
 291         In case of an error, the transfer will be retried up to three times.
 292
 293    INPUTS
 294         mn_ReplyPort - pointer to message port that receives I/O request
 295                        if the quick flag (IOF_QUICK) is clear
 296         io_Device    - pointer to device node, must be set by (or copied from
 297                        I/O block set by) OpenDevice() function
 298         io_Unit      - pointer to unit node to use, set by OpenDevice()
 299         io_Command   - command number for UHCMD_CONTROLXFER
 300         io_Flags     - flags, must be cleared if not used:
 301                        IOF_QUICK - (CLEAR) reply I/O request
 302
 303         iouh_Flags        - UHFF_LOWSPEED for low speed devices.
 304                             UHFF_HIGHSPEED for high speed USB2.0 devices.
 305                             full speed devices will be assumed otherwise.
 306                             UHFF_SPLITTRANS for low or fullspeed devices
 307                             behind a USB 2.0 hub. iouh_SplitHubAddr and
 308                             iouh_SplitHubPort are set accordingly.
 309                             UHFF_MULTI_1, UHFF_MULTI_2, UHFF_MULTI_3
 310                             indicating the number of transactions per µFrame
 311                             for highspeed transfers.
 312                             UHFF_NAKTIMEOUT will enable the NAK timeout
 313                             feature (see below).
 314                             If UHFF_ALLOWRUNTPKTS is set, the request will
 315                             not return UHIOERR_RUNTPACKET in any case. You
 316                             should check iouh_Actual for the amount of data
 317                             transferred.
 318         iouh_DevAddr      - device address from 0 to 127.
 319         iouh_Endpoint     - endpoint number from 0 to 15.
 320         iouh_MaxPktSize   - maximum size of a packet for this endpoint.
 321         iouh_Data         - pointer to a buffer to transport the data.
 322         iouh_Length       - number of bytes to transfer.
 323         iouh_SetupData    - contents of the eight byte setup packet.
 324                             The first bit in the bmRequestType field will
 325                             determine the direction (1=in, 0=out).
 326         iouh_SplitHubAddr - for split transactions only: the hub device
 327                             address from 0 to 127.
 328         iouh_SplitHubPort - for split transactions only: the hub port number
 329                             the USB 1.1 device is connected to from 0 to 255.
 330         iouh_NakTimeout   - if UHFF_NAKTIMEOUT is enabled, this specifies
 331                             the time in milliseconds until the request will
 332                             be retired with UHIOERR_NAKTIMEOUT due to the
 333                             endpoint constantly denying the request with
 334                             NAKs. This can be used to avoid hangs on broken
 335                             USB units. 1000 (1 second) is a reasonable value.
 336
 337    OUTPUTS
 338         iouh_Actual  - actual bytes transferred during the data phase
 339                        (excluding the 8 bytes from the setup phase).
 340         io_Error     - if something went wrong, you will find a non-null
 341                        value here, indicating the error.
 342
 343    SEE ALSO
 344         UHCMD_BULKXFER, UHCMD_INTXFER, UHCMD_ISOXFER
 345
 346
 347 \fusbhardware.device/UHCMD_INTXFER           usbhardware.device/UHCMD_BULKXFER
 348
 349    NAME
 350         UHCMD_INTXFER -- installs an interrupt transfer to or from the bus
 351
 352    FUNCTION
 353         Installs an interrupt transfer. If no data is to be sent or the
 354         target endpoint does not accept the packet, it will retry to
 355         send the packets with the given time interval in iouh_Interval
 356         until it succeeds.
 357
 358         The direction of the transfer (host to device or device to host) is
 359         determined by the setting in the iouh_Dir field.
 360
 361         The data itself is split into packets of iouh_MaxPktSize length,
 362         although in normal cases you will not request packets larger than
 363         iouh_MaxPktSize.
 364
 365         For IN-transactions, iouh_Data holds a pointer to the buffer to be
 366         filled, for OUT-transactions, iouh_Data is a pointer to the data
 367         to send to the device.
 368
 369         In case of an error, the transfer will be retried up to three times.
 370         This does not include the reception of NAK pakets, which does not
 371         decrement the retry count.
 372
 373    NOTE
 374         An Interrupt transfer request will only return if the device actually
 375         sends the data or if an error occurs. If you do DoIO(), you might get
 376         blocked out, so better do asynchroneous calls like SendIO().
 377
 378    INPUTS
 379         mn_ReplyPort - pointer to message port that receives I/O request
 380                        if the quick flag (IOF_QUICK) is clear
 381         io_Device    - pointer to device node, must be set by (or copied from
 382                        I/O block set by) OpenDevice() function
 383         io_Unit      - pointer to unit node to use, set by OpenDevice()
 384         io_Command   - command number for UHCMD_CONTROLXFER
 385         io_Flags     - flags, must be cleared if not use:
 386                        IOF_QUICK - (CLEAR) reply I/O request
 387
 388         iouh_Flags        - UHFF_LOWSPEED for low speed devices.
 389                             UHFF_HIGHSPEED for high speed USB2.0 devices.
 390                             full speed devices will be assumed otherwise.
 391                             UHFF_SPLITTRANS for low or fullspeed devices
 392                             behind a USB 2.0 hub. iouh_SplitHubAddr and
 393                             iouh_SplitHubPort are set accordingly.
 394                             UHFF_MULTI_1, UHFF_MULTI_2, UHFF_MULTI_3
 395                             indicating the number of transactions per µFrame
 396                             for highspeed transfers.
 397                             UHFF_NOSHORTPKT will not send terminating short
 398                             packets (if the transfer length is a multiple
 399                             of iouh_MaxPktSize). Might not be sensible on
 400                             interrupt transfers.
 401                             UHFF_NAKTIMEOUT will enable the NAK timeout
 402                             feature (see below).
 403                             If UHFF_ALLOWRUNTPKTS is set, the request will
 404                             not return UHIOERR_RUNTPACKET in any case. You
 405                             should check iouh_Actual for the amount of data
 406                             transferred.
 407         iouh_Dir          - either UHDIR_IN for device to host transfers
 408                             or UHDIR_OUT for host to device transfers.
 409         iouh_DevAddr      - device address from 0 to 127.
 410         iouh_Endpoint     - endpoint number from 0 to 15.
 411         iouh_MaxPktSize   - maximum size of a packet for this endpoint.
 412         iouh_Data         - pointer to a buffer to transport the data.
 413         iouh_Length       - number of bytes to transfer.
 414         iouh_Interval     - interval in milliseconds for the request to be
 415                             retried in case of a NAK. For highspeed, this
 416                             value is in number of µFrames (units of
 417                             125µsecs).
 418         iouh_SplitHubAddr - for split transactions only: the hub device
 419                             address from 0 to 127.
 420         iouh_SplitHubPort - for split transactions only: the hub port number
 421                             the USB 1.1 device is connected to from 0 to 255.
 422         iouh_NakTimeout   - if UHFF_NAKTIMEOUT is enabled, this specifies
 423                             the time in milliseconds until the request will
 424                             be retired with UHIOERR_NAKTIMEOUT due to the
 425                             endpoint constantly denying the request with
 426                             NAKs. This can be used to avoid hangs on broken
 427                             USB unit 1000 (1 second) is a reasonable value.
 428
 429    OUTPUTS
 430         iouh_Actual  - actual bytes transferred.
 431         io_Error     - if something went wrong, you will find a non-null
 432                        value here, indicating the error.
 433
 434    SEE ALSO
 435         UHCMD_CONTROLXFER, UHCMD_BULKXFER, UHCMD_ISOXFER
 436
 437
 438 \fusbhardware.device/UHCMD_ISOXFER             usbhardware.device/UHCMD_ISOXFER
 439
 440    NAME
 441         UHCMD_ISOXFER -- start an isochronous transfer to or from the bus
 442
 443    FUNCTION
 444         Starts an isochronous transfer with the amount of data specified.
 445         The direction of the transfer (host to device or device to host) is
 446         determined by the setting in the iouh_Dir field.
 447
 448         The data itself is split into packets of iouh_MaxPktSize length.
 449         For IN-transactions, iouh_Data holds a pointer to the buffer to be
 450         filled, for OUT-transactions, iouh_Data is a pointer to the data
 451         to send to the device.
 452
 453         Isochronous transfer are normally used for large, time-critical
 454         data which does not need to be transferred reliably.
 455
 456         In case of an error, the transfer will NOT be retried at all and
 457         io_Error will contain the error number.
 458
 459    INPUTS
 460         mn_ReplyPort - pointer to message port that receives I/O request
 461                        if the quick flag (IOF_QUICK) is clear
 462         io_Device    - pointer to device node, must be set by (or copied from
 463                        I/O block set by) OpenDevice() function
 464         io_Unit      - pointer to unit node to use, set by OpenDevice()
 465         io_Command   - command number for UHCMD_CONTROLXFER
 466         io_Flags     - flags, must be cleared if not use:
 467                        IOF_QUICK - (CLEAR) reply I/O request
 468
 469         iouh_Flags        - UHFF_LOWSPEED for low speed devices.
 470                             UHFF_HIGHSPEED for high speed USB2.0 devices.
 471                             full speed devices will be assumed otherwise.
 472                             UHFF_SPLITTRANS for low or fullspeed devices
 473                             behind a USB 2.0 hub. iouh_SplitHubAddr and
 474                             iouh_SplitHubPort are set accordingly.
 475                             UHFF_MULTI_1, UHFF_MULTI_2, UHFF_MULTI_3
 476                             indicating the number of transactions per µFrame
 477                             for highspeed transfers.
 478                             UHFF_NOSHORTPKT will not send terminating short
 479                             packets (if the transfer length is a multiple
 480                             of iouh_MaxPktSize). This allows you to create
 481                             a continous bulk stream with multiple requests.
 482                             If UHFF_ALLOWRUNTPKTS is set, the request will
 483                             not return UHIOERR_RUNTPACKET in any case. You
 484                             should check iouh_Actual for the amount of data
 485                             transferred.
 486         iouh_Dir          - either UHDIR_IN for device to host transfers
 487                             or UHDIR_OUT for host to device transfers.
 488         iouh_DevAddr      - device address from 0 to 127.
 489         iouh_Endpoint     - endpoint number from 0 to 15.
 490         iouh_MaxPktSize   - maximum size of a packet for this endpoint.
 491         iouh_Data         - pointer to a buffer to transport the data.
 492         iouh_Length       - number of bytes to transfer.
 493         iouh_SplitHubAddr - for split transactions only: the hub device
 494                             address from 0 to 127.
 495         iouh_SplitHubPort - for split transactions only: the hub port number
 496                             the USB 1.1 device is connected to from 0 to 255.
 497         iouh_NakTimeout   - if UHFF_NAKTIMEOUT is enabled, this specifies
 498                             the time in milliseconds until the request will
 499                             be retired with UHIOERR_NAKTIMEOUT due to the
 500                             endpoint constantly denying the request with
 501                             NAKs. This can be used to avoid hangs on broken
 502                             USB unit 1000 (1 second) is a reasonable value.
 503
 504    OUTPUTS
 505         iouh_Actual  - actual bytes transferred.
 506         io_Error     - if something went wrong, you will find a non-null
 507                        value here, indicating the error.
 508
 509    SEE ALSO
 510         UHCMD_CONTROLXFER, UHCMD_BULKXFER, UHCMD_INTXFER
 511
 512
 513 \fusbhardware.device/UHCMD_QUERYDEVICE     usbhardware.device/UHCMD_QUERYDEVICE
 514
 515    NAME
 516         UHCMD_QUERYDEVICE -- get hardware information
 517
 518    FUNCTION
 519         Can be used to acquire information about the hardware and its
 520         driver. The command uses a TagList as parameter in iouh_Data.
 521
 522         Each taglist entry holds a pointer to a longword (ULONG *), as
 523         usually, and the corresponding data is also written as an ULONG.
 524
 525    TAGS
 526         Currently defined tags include:
 527
 528         UHA_State (UWORD) - Returns a bitmap of the current USB state.
 529                             See UHS flags in devices/usbhardware.h.
 530         UHA_Manufacturer (STRPTR) - Manufactuerer string.
 531         UHA_ProductName (STRPTR) - Product string.
 532         UHA_Version (UWORD) - Version number.
 533         UHA_Revision (UWORD) - Revision of device.
 534         UHA_Description (STRPTR) - String describing features of device.
 535         UHA_Copyright (STRPTR) - Copyright message.
 536         UHA_DriverVersion (UWORD) - BCD encoded version number of the
 537                                     IORequest structure. Currently, only
 538                                     0x100 and 0x200 are valid.
 539
 540    INPUTS
 541         mn_ReplyPort - pointer to message port that receives I/O request
 542                        if the quick flag (IOF_QUICK) is clear
 543         io_Device    - pointer to device node, must be set by (or copied from
 544                        I/O block set by) OpenDevice() function
 545         io_Unit      - pointer to unit node to use, set by OpenDevice()
 546         io_Command   - command number for UHCMD_QUERYDEVICE
 547         io_Flags     - flags, must be cleared if not use:
 548                        IOF_QUICK - (CLEAR) reply I/O request
 549         iouh_Data    - pointer to a TagList to fill
 550
 551    OUTPUTS
 552         iouh_Actual  - number of tags filled.
 553         iouh_State   - current status, if UHA_State was included. Will
 554                        not be changed otherwise.
 555
 556    SEE ALSO
 557         devices/usbhardware.h
 558
 559
 560 \fusbhardware.device/UHCMD_USBOPER             usbhardware.device/UHCMD_USBOPER
 561
 562    NAME
 563         UHCMD_USBOPER -- ask USB into operational mode
 564
 565    FUNCTION
 566         This command try to get the USB operational, whatever mode it
 567         previously might have been.
 568
 569    INPUTS
 570         mn_ReplyPort - pointer to message port that receives I/O request
 571                        if the quick flag (IOF_QUICK) is clear
 572         io_Device    - pointer to device node, must be set by (or copied from
 573                        I/O block set by) OpenDevice() function
 574         io_Unit      - pointer to unit node to use, set by OpenDevice()
 575         io_Command   - command number for UHCMD_USBOPER
 576         io_Flags     - flags, must be cleared if not use:
 577                        IOF_QUICK - (CLEAR) reply I/O request
 578
 579    OUTPUTS
 580         iouh_State   - current status of bus.
 581         io_Error     - either 0, if everything went okay or
 582                        UHIOERR_HOSTERROR, if bus was not in operational state
 583                        after this command.
 584
 585    SEE ALSO
 586         UHCMD_USBSUSPEND, UHCMD_USBRESUME, UHCMD_USBRESET
 587
 588
 589 \fusbhardware.device/UHCMD_USBRESET           usbhardware.device/UHCMD_USBRESET
 590
 591    NAME
 592         UHCMD_USBRESET -- reset USB
 593
 594    FUNCTION
 595         This command will reset the USB. After about 50ms the USB will
 596         automatically go into operational mode.
 597
 598    INPUTS
 599         mn_ReplyPort - pointer to message port that receives I/O request
 600                        if the quick flag (IOF_QUICK) is clear
 601         io_Device    - pointer to device node, must be set by (or copied from
 602                        I/O block set by) OpenDevice() function
 603         io_Unit      - pointer to unit node to use, set by OpenDevice()
 604         io_Command   - command number for UHCMD_USBRESET
 605         io_Flags     - flags, must be cleared if not use:
 606                        IOF_QUICK - (CLEAR) reply I/O request
 607
 608    OUTPUTS
 609         iouh_State   - current status of bus.
 610         io_Error     - either 0, if everything went okay or
 611                        UHIOERR_HOSTERROR, if bus was not in operational state
 612                        after the bus reset.
 613
 614    SEE ALSO
 615         CMD_RESET, UHCMD_USBRESUME, UHCMD_USBSUSPEND, UHCMD_USBOPER
 616
 617
 618 \fusbhardware.device/UHCMD_USBRESUME         usbhardware.device/UHCMD_USBRESUME
 619
 620    NAME
 621         UHCMD_USBRESUME -- go from suspend into operational mode
 622
 623    FUNCTION
 624         This command will wake the bus from suspend mode. The SOF
 625         generation will restart right after, enabling the bus again.
 626
 627    INPUTS
 628         mn_ReplyPort - pointer to message port that receives I/O request
 629                        if the quick flag (IOF_QUICK) is clear
 630         io_Device    - pointer to device node, must be set by (or copied from
 631                        I/O block set by) OpenDevice() function
 632         io_Unit      - pointer to unit node to use, set by OpenDevice()
 633         io_Command   - command number for UHCMD_USBRESUME
 634         io_Flags     - flags, must be cleared if not use:
 635                        IOF_QUICK - (CLEAR) reply I/O request
 636
 637    OUTPUTS
 638         iouh_State   - current status of bus.
 639         io_Error     - either 0, if everything went okay or
 640                        UHIOERR_HOSTERROR, if bus was not in operational state
 641                        after the resume command.
 642
 643    SEE ALSO
 644         UHCMD_USBSUSPEND, UHCMD_USBOPER, UHCMD_USBRESET
 645
 646
 647 \fusbhardware.device/UHCMD_USBSUSPEND       usbhardware.device/UHCMD_USBSUSPEND
 648
 649    NAME
 650         UHCMD_USBSUSPEND -- change bus into suspend mode
 651
 652    FUNCTION
 653         UHCMD_USBSUSPEND will ask the USB to go into suspend mode. SOF
 654         generation will be stopped.
 655
 656    INPUTS
 657         mn_ReplyPort - pointer to message port that receives I/O request
 658                        if the quick flag (IOF_QUICK) is clear
 659         io_Device    - pointer to device node, must be set by (or copied from
 660                        I/O block set by) OpenDevice() function
 661         io_Unit      - pointer to unit node to use, set by OpenDevice()
 662         io_Command   - command number for UHCMD_USBSUSPEND
 663         io_Flags     - flags, must be cleared if not use:
 664                        IOF_QUICK - (CLEAR) reply I/O request
 665
 666    OUTPUTS
 667         iouh_State   - current status of bus.
 668         io_Error     - either 0, if everything went okay or
 669                        UHIOERR_HOSTERROR, if bus could not be suspended.
 670
 671    SEE ALSO
 672         UHCMD_USBRESUME, UHCMD_USBRESET, UHCMD_USBOPER
 673
 674
 675