docs/user/drivers/USB3.dox

   1 /*
   2  * Copyright 2007 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Niels Sascha Reedijk, niels.reedijk@gmail.com
   7  *
   8  * Corresponds to:
   9  *              headers/os/drivers/USB3.h rev 19915
  10  */
  11
  12
  13 /*!
  14         \file USB3.h
  15         \ingroup drivers
  16         \ingroup libbe
  17         \brief Interface for the USB module.
  18 */
  19
  20
  21 /*!
  22         \typedef struct usb_module_info usb_module_info
  23         \brief The main interface object. See the usb_module_info documentation.
  24 */
  25
  26
  27 /*!
  28         \typedef uint32 usb_id
  29         \brief Uniquely identify various USB objects that are used in the module.
  30 */
  31
  32
  33 /*!
  34         \typedef usb_id usb_device
  35         \brief Uniquely identify USB devices.
  36 */
  37
  38
  39 /*!
  40         \typedef usb_id usb_interface
  41         \brief Uniquely identify USB interfaces.
  42 */
  43
  44
  45 /*!
  46         \typedef usb_id usb_pipe
  47         \brief Uniquely identify USB pipes.
  48 */
  49
  50
  51 /*!
  52         \typedef struct usb_endpoint_info usb_endpoint_info
  53         \brief Container for USB endpoint descriptors.
  54         \see Documentation for usb_endpoint_info.
  55 */
  56
  57
  58 /*!
  59         \typedef struct usb_interface_info usb_interface_info
  60         \brief Container for USB interface descriptors.
  61         \see Documentation for usb_interface_info.
  62 */
  63
  64
  65 /*!
  66         \typedef struct usb_interface_list usb_interface_list
  67         \brief Container that holds a list of USB interface descriptors.
  68         \see Documentation for usb_interface_list.
  69 */
  70
  71
  72 /*!
  73         \typedef struct usb_configuration_info usb_configuration_info
  74         \brief Container for USB configuration descriptors.
  75         \see Documentation for usb_configuration_info.
  76 */
  77
  78
  79 ///// usb_notify_hooks /////
  80
  81
  82 /*!
  83         \struct usb_notify_hooks
  84         \ingroup drivers
  85         \ingroup libbe
  86         \brief Hooks that the USB stack can callback in case of events.
  87 */
  88
  89
  90 /*!
  91         \fn status_t (*usb_notify_hooks::device_added)(usb_device device, void **cookie)
  92         \brief Called by the stack in case a device is added.
  93
  94         Once you have registered hooks using the
  95         usb_module_info::install_notify() method, this hook will be called as soon as
  96         a device is inserted that matches your provided usb_support_descriptor.
  97
  98         \param device A unique id that identifies this USB device.
  99         \param[in] cookie You can store a pointer to an object in this variable.
 100           When the device is removed, this cookie will be provided to you.
 101         \return You should return \c B_OK in case of success. The USB stack will then
 102           request the kernel to republish your device names so that the new device
 103           will be shown in the \c /dev tree. If you return an error value, the
 104           \a device id will become invalid and you will not be notified if this
 105           device is removed.
 106         \see device_removed()
 107 */
 108
 109
 110 /*!
 111         \var status_t (*usb_notify_hooks::device_removed)(void *cookie)
 112         \brief Called by the stack in case a device you are using is removed.
 113
 114         If you have accepted a device in the device_added() hook, this hook will
 115         be called as soon as the device is removed.
 116
 117         \param cookie The cookie you provided in the device_added() hook. Make sure
 118           that you free the cookie if necessary.
 119         \return Currently the return value of this hook is ignored. It is recommended
 120           to return \c B_OK though.
 121 */
 122
 123
 124 ///// usb_support_descriptor /////
 125
 126
 127 /*!
 128         \struct usb_support_descriptor
 129         \ingroup drivers
 130         \ingroup libbe
 131         \brief Description of device descriptor that the driver can handle.
 132
 133         Support descriptors can be used to match any form of class, subclass or
 134         protocol, or they can be used to match a vendor and/or product.
 135         If any field has the value \c 0, it is treated as a wildcard.
 136
 137         For example, if you want to watch for all the hubs, which have a device
 138         class of \c 0x09, you would pass this descriptor:
 139
 140         \code
 141         usb_support_descriptor hub_devs = { 9, 0, 0, 0, 0 };
 142         \endcode
 143
 144         See usb_module_info::register_driver() for more information on how to use
 145         this object.
 146 */
 147
 148
 149 /*!
 150         \var usb_support_descriptor::dev_class
 151         \brief The supported device classes.
 152 */
 153
 154
 155 /*!
 156         \var usb_support_descriptor::dev_subclass
 157         \brief The supported device subclasses.
 158 */
 159
 160
 161 /*!
 162         \var usb_support_descriptor::dev_protocol
 163         \brief The supported device protocols.
 164 */
 165
 166
 167 /*!
 168         \var usb_support_descriptor::vendor
 169         \brief The supported device vendor.
 170 */
 171
 172
 173 /*!
 174         \var usb_support_descriptor::product
 175         \brief The supported device products.
 176 */
 177
 178
 179 ///// usb_endpoint_info /////
 180
 181
 182 /*!
 183         \struct usb_endpoint_info
 184         \ingroup drivers
 185         \ingroup libbe
 186         \brief Container for endpoint descriptors and their Haiku USB stack
 187           identifiers.
 188 */
 189
 190
 191 /*!
 192         \var usb_endpoint_descriptor *usb_endpoint_info::descr
 193         \brief Pointer to the descriptor of the endpoint.
 194 */
 195
 196
 197 /*!
 198         \var usb_pipe usb_endpoint_info::handle
 199         \brief Handle to use when using the stack to transfer data to and from this
 200           endpoint.
 201 */
 202
 203
 204 ///// usb_interface_info /////
 205
 206
 207 /*!
 208         \struct usb_interface_info
 209         \ingroup drivers
 210         \ingroup libbe
 211         \brief Container for interface descriptors and their Haiku USB stack
 212           identifiers.
 213 */
 214
 215
 216 //! @{
 217
 218
 219 /*!
 220         \var usb_interface_descriptor *usb_interface_info::descr
 221         \brief Pointer to the descriptor of the interface.
 222 */
 223
 224
 225 /*!
 226         \var usb_interface usb_interface_info::handle
 227         \brief Handle to use when using the stack to manipulate this interface.
 228 */
 229
 230
 231 //! @}
 232
 233
 234 /*!
 235         \name Endpoints
 236 */
 237
 238
 239 //! @{
 240
 241
 242 /*!
 243         \var size_t usb_interface_info::endpoint_count
 244         \brief The number of endpoints in this interface.
 245 */
 246
 247
 248 /*!
 249         \var usb_endpoint_info *usb_interface_info::endpoint
 250         \brief An array of endpoints that are associated to this interface.
 251 */
 252
 253
 254 //! @}
 255
 256
 257 /*!
 258         \name Unparsed descriptors
 259 */
 260
 261
 262 //! @{
 263
 264
 265 /*!
 266         \var size_t usb_interface_info::generic_count
 267         \brief The number of unparsed descriptors in this interface.
 268 */
 269
 270
 271 /*!
 272         \var usb_descriptor **usb_interface_info::generic
 273         \brief Unparsed descriptors in this interface.
 274 */
 275
 276
 277 //! @}
 278
 279
 280 ///// usb_interface_list /////
 281
 282
 283 /*!
 284         \struct usb_interface_list
 285         \ingroup drivers
 286         \ingroup libbe
 287         \brief List of interfaces available to a configuration.
 288 */
 289
 290
 291 /*!
 292         \var size_t usb_interface_list::alt_count
 293         \brief Number of available interfaces.
 294 */
 295
 296
 297 /*!
 298         \var usb_interface_info *usb_interface_list::alt
 299         \brief Array of available interfaces.
 300 */
 301
 302
 303 /*!
 304         \var usb_interface_info *usb_interface_list::active
 305         \brief Pointer to active interface.
 306 */
 307
 308
 309 ///// usb_configuration_info /////
 310
 311
 312 /*!
 313         \struct usb_configuration_info
 314         \ingroup drivers
 315         \ingroup libbe
 316         \brief Container for a specific configuration descriptor of a device.
 317 */
 318
 319
 320 /*!
 321         \var usb_configuration_descriptor *usb_configuration_info::descr
 322         \brief The configuration descriptor.
 323 */
 324
 325
 326 /*!
 327         \var size_t usb_configuration_info::interface_count
 328         \brief The number of interfaces in this configuration.
 329 */
 330
 331
 332 /*!
 333         \var usb_interface_list *usb_configuration_info::interface
 334         \brief The list of interfaces available to this configuration.
 335 */
 336
 337
 338 ///// usb_iso_packet_descriptor /////
 339
 340
 341 /*!
 342         \struct usb_iso_packet_descriptor
 343         \ingroup drivers
 344         \ingroup libbe
 345         \brief The descriptor for data packets of isochronous transfers.
 346 */
 347
 348
 349 /*!
 350         \var int16 usb_iso_packet_descriptor::request_length
 351         \brief Length of the request.
 352 */
 353
 354
 355 /*!
 356         \var int16 usb_iso_packet_descriptor::actual_length
 357         \brief The USB stack writes the actual transferred length in this variable.
 358 */
 359
 360
 361 /*!
 362         \var status_t   usb_iso_packet_descriptor::status
 363         \brief The status of the transfer.
 364 */
 365
 366
 367 ///// usb_callback_func /////
 368
 369
 370 /*!
 371         \typedef typedef void (*usb_callback_func)(void *cookie, status_t status,
 372                 void *data, size_t actualLength)
 373         \brief Callback function for asynchronous transfers.
 374
 375         \param cookie The cookie you supplied when you queued the transfer.
 376         \param status The status of the transfer. This is one of the following:
 377           <table>
 378             <tr>
 379               <td><em>B_OK</em></td><td>The transfer succeeded.</td>
 380             </tr>
 381             <tr>
 382               <td><em>B_CANCELED</em></td><td>The transfer was cancelled by the user
 383                 via a usb_module_info::cancel_queued_transfers() call.</td>
 384             </tr>
 385             <tr>
 386               <td><em>B_DEV_MULTIPLE_ERRORS</em></td><td>More than one of the errors
 387                 below occurred. Unfortunately, the stack cannot give you more
 388                 information.</td>
 389             </tr>
 390             <tr>
 391               <td><em>B_DEV_STALLED</em></td><td>The endpoint is stalled. You can
 392                 use usb_module_info::clear_feature() method with the associated pipe
 393                 and the USB_FEATURE_ENDPOINT_HALT arguments.</td>
 394             </tr>
 395             <tr>
 396               <td><em>B_DEV_DATA_OVERRUN</em></td><td>Incoming transfer: more data
 397                 flowing in than the size of the buffer.</td>
 398             </tr>
 399             <tr>
 400               <td><em>B_DEV_DATA_UNDERRUN</em></td><td>Outgoing transfer: more data
 401                 is flowing out than the endpoint accepts.</td>
 402             </tr>
 403             <tr>
 404               <td><em>B_DEV_CRC_ERROR</em></td><td>The internal data consistency
 405                 checks of the USB protocol failed. It is best to retry. If you keep
 406                 on getting this error there might be something wrong with the
 407                 device.</td>
 408             </tr>
 409             <tr>
 410               <td><em>B_DEV_UNEXPECTED_PID</em></td><td>There was an internal error.
 411                 You should retry your transfer.</td>
 412             </tr>
 413             <tr>
 414               <td><em>B_DEV_FIFO_OVERRUN</em></td><td>internal error.
 415                 You should retry your transfer.</td>
 416             </tr>
 417             <tr>
 418                <td><em>B_DEV_FIFO_UNDERRUN</em></td><td>There was an internal error.
 419                  You should retry your transfer.</td>
 420             </tr>
 421           </table>
 422         \param data The provided buffer.
 423         \param actualLength The amount of bytes read or written during the transfer.
 424 */
 425
 426
 427 ///// usb_module_info /////
 428
 429
 430 /*!
 431         \struct usb_module_info
 432         \ingroup drivers
 433         \ingroup libbe
 434         \brief Interface for drivers to interact with Haiku's USB stack.
 435 */
 436
 437
 438 /*!
 439         \var usb_module_info::binfo
 440         \brief Instance of the bus_manager_info object.
 441 */
 442
 443
 444 /*!
 445         \fn status_t (*usb_module_info::register_driver)(const char *driverName, const usb_support_descriptor *supportDescriptors, size_t supportDescriptorCount, const char *optionalRepublishDriverName)
 446         \brief Register your driver.
 447
 448         To let the USB stack know that a driver is available to support devices, a
 449         driver needs to register itself first. To let the stack know about devices
 450         it needs to notify the driver of, have a look at usb_support_descriptor.
 451
 452         It is possible to supply a list of support constructors. You should allocate
 453         an array of support constructors and give the amount of constructors in the
 454         array using the \a supportDescriptorCount parameter.
 455
 456         In case your driver supports all devices or, more likely, you want to
 457         monitor all devices plugged in and removed, it is safe to pass \c NULL to
 458         the \a supportDescriptors paramater and zero (0) to
 459         \a supportDescriptorCount.
 460
 461         \param driverName A unique name that identifies your driver. Avoid names
 462         like \c webcam or \c mouse, instead use vendor names and device types to
 463         avoid nameclashes. The install_notify() and uninstall_notify() functions use
 464         the driver name as an identifier.
 465
 466         \param supportDescriptors An array of the type usb_support_descriptor. Pass
 467                 the amount of objects in the next parameter.
 468         \param supportDescriptorCount The number of objects in the array supplied in
 469                 the previous parameter.
 470         \param optionalRepublishDriverName Unused parameter. You should pass
 471                 \c NULL.
 472
 473         \retval B_OK The driver is registered. You can now call install_notify()
 474         \retval B_BAD_VALUE You passed \c NULL as \a driverName.
 475         \retval B_ERROR General internal error in the USB stack. You may retry the
 476           request in this case.
 477         \retval B_NO_MEMORY Error allocating some internal objects. The system is
 478           out of memory.
 479 */
 480
 481
 482 /*!
 483         \fn status_t (*usb_module_info::install_notify)(const char *driverName, const usb_notify_hooks *hooks)
 484         \brief Install notify hooks for your driver.
 485
 486         After your driver is registered, you need to pass hooks to your driver that
 487         are called whenever a device that matches your \link usb_support_descriptor
 488         support descriptor \endlink .
 489
 490         As soon as the hooks are installed, you'll receive callbacks for devices
 491         that are already attached; so make sure your driver is initialized properly
 492         when calling this method.
 493
 494         \param driverName The name you passed in register_driver().
 495         \param hooks The hooks the stack should call in case the status of devices
 496                 that match your support descriptor changes.
 497
 498         \retval B_OK Hooks are installed succesfully.
 499         \retval B_NAME_NOT_FOUND Invalid \a driverName.
 500
 501         \see usb_notify_hooks for information on how your hooks should behave.
 502         \see uninstall_notify()
 503 */
 504
 505
 506 /*!
 507         \fn status_t (*usb_module_info::uninstall_notify)(const char *driverName)
 508         \brief Uninstall notify hooks for your driver.
 509
 510         If your driver needs to stop, you can uninstall the notifier hooks. This
 511         will clear the stored hooks in the driver, and you will not receive any
 512         notifications when new devices are attached. This method will also call
 513         usb_notify_hooks::device_removed() for all the devices that you are using
 514         and all the stack's resources that are allocated to your driver are
 515         cleared.
 516
 517         \param driverName The name you passed in register_driver().
 518         \retval B_OK Hooks are uninstalled.
 519         \retval B_NAME_NOT_FOUND Invalid \a driverName.
 520 */
 521
 522
 523 /*!
 524         \fn const usb_device_descriptor *(*usb_module_info::get_device_descriptor)(usb_device device)
 525         \brief Get the device descriptor.
 526
 527         \param device The id of the device you want to query.
 528         \return The standard usb_device_descriptor, or \c NULL in case of an error.
 529 */
 530
 531
 532 /*!
 533         \fn const usb_configuration_info *(*usb_module_info::get_nth_configuration)(usb_device device, uint index)
 534         \brief Get a configuration descriptor by index.
 535
 536         \param device The id of the device you want to query.
 537         \param index The (zero based) offset of the list of configurations.
 538         \return This will normally return the usb_configuration_info with the
 539           standard usb configuration descriptor.  \c NULL will be returned if the
 540           \a id is invalid or the \a index is out of bounds.
 541 */
 542
 543
 544 /*!
 545         \fn const usb_configuration_info *(*usb_module_info::get_configuration)(usb_device device)
 546         \brief Get the current configuration.
 547
 548         \param id The id of the device you want to query.
 549         \retval This will return usb_configuration_info with the standard usb
 550           configuration descriptor, or it will return\c NULL if the \a id is invalid.
 551 */
 552
 553
 554 /*!
 555         \fn status_t (*usb_module_info::set_configuration)(usb_device device, const usb_configuration_info *configuration)
 556         \brief Change the current configuration.
 557
 558         Changing the configuration will destroy all the current endpoints. If the
 559         \a configuration points to the current configuration, the request will be
 560         ignored and \c B_OK will be returned.
 561
 562         \param device The id of the device you want to query.
 563         \param configuration The pointer to the new configuration you want to set.
 564         \retval B_OK The new configuration is set succesfully.
 565         \retval B_DEV_INVALID_PIPE The \a device parameter is invalid.
 566         \retval B_BAD_VALUE The configuration does not exist.
 567
 568         \note This method also allows you to completely unconfigure the device, which
 569           means that all the current endpoints, pipes and transfers will be freed.
 570           Pass \c NULL to the parameter \a configuration if you want to do that.
 571 */
 572
 573
 574 /*!
 575         \fn status_t (*usb_module_info::set_alt_interface)(usb_device device, const usb_interface_info *interface)
 576         \brief Set an alternative interface. Not implemented.
 577
 578         This method currently always returns \c B_ERROR.
 579 */
 580
 581
 582 /*!
 583         \fn status_t (*usb_module_info::set_feature)(usb_id handle, uint16 selector)
 584         \brief Convenience function for standard control pipe set feature requests.
 585          Both the set_feature() and clear_feature() requests work on all the Stack's
 586         objects: devices, interfaces and pipes.
 587
 588         \param handle The object you want to query.
 589         \param selector The value you want to pass in the feature request.
 590         \return \c B_OK in case the request succeeded and the device responded
 591           positively, or an error code in case it failed.
 592 */
 593
 594
 595 /*!
 596         \fn status_t (*usb_module_info::clear_feature)(usb_id handle, uint16 selector)
 597         \brief Convenience function for standard control pipe clear feature requests.
 598
 599         \see set_feature() to see how this method works.
 600 */
 601
 602
 603 /*!
 604         \fn status_t (*usb_module_info::get_status)(usb_id handle, uint16 *status)
 605         \brief Convenience function for standard usb status requests.
 606
 607         \param[in] handle The object you want to query.
 608         \param[out] status A variable in which the device can store its status.
 609         \return \c B_OK is returned in case the request succeeded and the device
 610          responded positively, or an error code is returned in case it failed.
 611 */
 612
 613
 614 /*!
 615         \fn status_t (*usb_module_info::get_descriptor)(usb_device device,
 616                 uint8 descriptorType, uint8 index, uint16 languageID, void *data,
 617                 size_t dataLength,  size_t *actualLength)
 618         \brief Convenience function to get a descriptor from a device.
 619
 620         \param[in] device The device you want to query.
 621         \param[in] descriptorType The type of descriptor you are requesting.
 622         \param[in] index In case there are multiple descriptors of this type, you
 623                 select which one you want.
 624         \param[in] languageID The language you want the descriptor in (if applicable,
 625                 as with string_descriptors).
 626         \param[out] data The buffer in which the descriptor can be written.
 627         \param[in] dataLength The size of the buffer (in bytes).
 628         \param[out] actualLength A pointer to a variable in which the actual number
 629                 of bytes written can be stored.
 630
 631         \returns A status code.
 632         \retval B_OK The request succeeded, and the descriptor is written.
 633         \retval B_DEV_INVALID_PIPE Invalid \a device parameter.
 634         \retval "other errors" Request failed.
 635 */
 636
 637
 638 /*!
 639         \fn status_t (*usb_module_info::send_request)(usb_device device,
 640                 uint8 requestType, uint8 request, uint16 value, uint16 index,
 641                 uint16 length, void *data, size_t *actualLength)
 642         \brief Send a generic, synchronous request over the default control pipe.
 643
 644         See queue_request() for an asynchronous version of this method.
 645
 646         Most of the standard values of a request are defined in USB_spec.h.
 647
 648         \param[in] device The device you want to query.
 649         \param[in] requestType The request type.
 650         \param[in] request The request you want to perform.
 651         \param[in] value The value of the request.
 652         \param[in] index The index for the request.
 653         \param[in] length  The size of the buffer pointed by \a data
 654         \param[out] data The buffer where to put the result in.
 655         \param[out] actualLength The actual numbers of bytes written.
 656
 657         \returns A status code.
 658         \retval B_OK The request succeeded.
 659         \retval B_DEV_INVALID_PIPE Invalid \a device parameter.
 660         \retval "other errors" Request failed.
 661 */
 662
 663
 664 /*!
 665         \fn status_t (*usb_module_info::queue_interrupt)(usb_pipe pipe, void *data,
 666                 size_t dataLength, usb_callback_func callback, void *callbackCookie)
 667         \brief Asynchronously queue an interrupt transfer.
 668
 669         \param pipe The id of the pipe you want to query.
 670         \param data The data buffer you want to pass.
 671         \param dataLength The size of the data buffer.
 672         \param callback The callback function the stack should call after finishing.
 673         \param callbackCookie A cookie that will be supplied to your callback
 674                 function when the transfer is finished.
 675
 676         \return This will return a value indicating whether or not the queueing of
 677                 the transfer went well. The return value won't tell you if the transfer
 678                 actually succeeded.
 679         \retval B_OK The interrupt transfer is queued.
 680         \retval B_NO_MEMORY Error allocating objects.
 681         \retval B_DEV_INVALID_PIPE The \a pipe is not a valid interrupt pipe.
 682 */
 683
 684 /*!
 685         \fn status_t (*usb_module_info::queue_bulk)(usb_pipe pipe, void *data, size_t dataLength, usb_callback_func callback, void *callbackCookie)
 686         \brief Asynchronously queue a bulk transfer.
 687
 688         This method behaves like the queue_interrupt() method, except that it queues
 689         a bulk transfer.
 690 */
 691
 692
 693 /*!
 694         \fn status_t (*usb_module_info::queue_bulk_v)(usb_pipe pipe, iovec *vector, size_t vectorCount, usb_callback_func callback, void *callbackCookie)
 695         \brief Asynchronously queue a bulk vector.
 696
 697         This method behaves like the queue_interrupt() method, except that it queues
 698         bulk transfers and that it is based on an (array of) io vectors.
 699
 700         \param vector One or more io vectors. IO vectors are standard POSIX entities.
 701         \param vectorCount The number of elements in the \a vector array.
 702 */
 703
 704
 705 /*!
 706         \fn status_t (*usb_module_info::queue_isochronous)(usb_pipe pipe, void *data, size_t dataLength, usb_iso_packet_descriptor *packetDesc, uint32 packetCount, uint32 *startingFrameNumber, uint32 flags, usb_callback_func callback, void *callbackCookie)
 707         \brief Asynchronously queue a isochronous transfer. Not implemented.
 708
 709         This is not implemented in the current Haiku USB Stack.
 710 */
 711
 712
 713 /*!
 714         \fn status_t (*usb_module_info::queue_request)(usb_device device, uint8 requestType, uint8 request, uint16 value, uint16 index, uint16 length, void *data, usb_callback_func callback, void *callbackCookie)
 715         \brief Asynchronously queue a control pipe request.
 716
 717         This method does roughly the same as send_request(), however, it works
 718         asynchronously. This means that the method will return as soon as the
 719         transfer is queued.
 720
 721         \param callback The callback function for when the transfer is done.
 722         \param callbackCookie The cookie that the stack should pass to your callback
 723           function.
 724           \return Whether or not the queueing of the transfer went well. The return
 725          value won't tell you if the transfer actually succeeded.
 726         \retval B_OK The control transfer is queued.
 727         \retval B_NO_MEMORY Error allocating objects.
 728         \retval B_DEV_INVALID_PIPE The \a device argument is invalid.
 729 */
 730
 731
 732 /*!
 733         \fn status_t (*usb_module_info::set_pipe_policy)(usb_pipe pipe, uint8 maxNumQueuedPackets, uint16 maxBufferDurationMS, uint16 sampleSize)
 734         \brief Set some pipe features.
 735
 736         The USB standard specifies some properties that should be able to be set on
 737         isochronous pipes. If your driver requires the properties to be changed, you
 738         should use this method.
 739
 740         \param pipe The id of the isochronous pipe you want to alter.
 741         \param maxNumQueuedPackets The maximum number of queued packets allowed on
 742           this pipe.
 743         \param maxBufferDurationMS The maximum time in ms that the buffers are valid.
 744         \param sampleSize The size of the samples through this pipe.
 745         \retval B_OK Pipe policy changed.
 746         \retval B_DEV_INVALID_PIPE The \a pipe argument is invalid or not an
 747           isochronous pipe.
 748 */
 749
 750
 751 /*!
 752         \fn status_t (*usb_module_info::cancel_queued_transfers)(usb_pipe pipe)
 753         \brief Cancel pending transfers on a pipe.
 754          All the pending transfers will be cancelled. The stack will perform the
 755         callback on all of them that are cancelled.
 756
 757         \attention There might be transfers that are being executed the moment you
 758           call this method. These will be executed, and their callbacks will be
 759           performed. Make sure you don't delete any buffers that could still be used
 760           by these transfers.
 761
 762         \param pipe The id of the pipe to clear.
 763
 764         \retval B_OK All the pending transfers on this pipe are deleted.
 765         \retval B_DEV_INVALID_PIPE The supplied usb_id is not a valid pipe.
 766         \retval "other errors" There was an error clearing the pipe.
 767 */
 768
 769
 770 /*!
 771         \fn status_t (*usb_module_info::usb_ioctl)(uint32 opcode, void *buffer, size_t bufferSize)
 772         \brief Low level commands to the USB stack.
 773
 774         This method is used to give lowlevel commands to the Stack. There are
 775         currently no uses documented.
 776 */
 777
 778
 779 ///// B_USB_MODULE_NAME /////
 780
 781
 782 /*!
 783         \def B_USB_MODULE_NAME
 784         \brief The identifier string for the USB Stack interface module.
 785 */