Ticket #1740: USB3_sample2_definitions.diff

File USB3_sample2_definitions.diff, 30.5 KB (added by nielx, 10 years ago)

Test attachment

  • drivers/USB3.dox

     
    1616
    1717/*!
    1818  \typedef struct usb_module_info usb_module_info
    19   \brief The main interface object. See the usb_module_info documentation.
     19  \brief This is the main interface object. See the usb_module_info documentation.
    2020*/
    2121
    2222/*!
    2323  \typedef uint32 usb_id
    24   \brief Uniquely identify various USB objects that are used in the module.
     24  \brief uniquely identifies various USB objects that are used in the module
    2525*/
    2626
    2727/*!
    2828  \typedef usb_id usb_device
    29   \brief Uniquely identify USB devices.
     29  \brief uniquely identifies USB devices
    3030*/
    3131
    3232/*!
    3333  \typedef usb_id usb_interface
    34   \brief Uniquely identify USB interfaces.
     34  \brief uniquely identifies USB interfaces
    3535*/
    3636
    3737/*!
    3838  \typedef usb_id usb_pipe
    39   \brief Uniquely identify USB pipes.
     39  \brief uniquely identifies USB pipes
    4040*/
    4141
    4242/*!
    4343  \typedef struct usb_endpoint_info usb_endpoint_info
    44   \brief Container for USB endpoint descriptors.
    45   \see Documentation for usb_endpoint_info.
     44  \brief container for USB endpoint descriptors
     45  \see documentation for usb_endpoint_info
    4646*/
    4747
    4848/*!
    4949  \typedef struct usb_interface_info usb_interface_info
    5050  \brief Container for USB interface descriptors.
    51   \see Documentation for usb_interface_info.
     51  \see documentation for usb_interface_info
    5252*/
    5353
    5454/*!
    55   \typedef usb_interface_list usb_interface_list
     55  \typedef struct usb_interface_list usb_interface_list
    5656  \brief Container that holds a list of USB interface descriptors.
    57   \see Documentation for usb_interface_list.
     57  \see documentation for usb_interface_list
    5858*/
    5959
    6060/*!
    6161  \typedef struct usb_configuration_info usb_configuration_info
    6262  \brief Container for USB configuration descriptors.
    63   \see Documentation for usb_configuration_info.
     63  \see documentation for usb_configuration_info
    6464*/
    6565
    6666///// usb_notify_hooks /////
    6767
    6868/*!
    6969  \struct usb_notify_hooks
    70   \brief Hooks that the USB stack can callback in case of events.
     70  \brief hooks that the USB stack can callback in case of events
    7171*/
    7272
    7373/*!
    7474  \fn status_t (*usb_notify_hooks::device_added)(usb_device device, void **cookie)
    75   \brief Called by the stack in case a device is added.
     75  \brief called by the stack in case a device is added
    7676 
    77   As soon as you have registered hooks using the
     77  Once you have registered hooks using the
    7878  usb_module_info::install_notify() method, this hook will be called as soon as
    7979  a device is inserted that matches your provided usb_support_descriptor.
    8080 
    81   \param device A unique id that identifies this USB device.
     81  \param device a unique id that identifies this USB device
    8282  \param[in] cookie You can store a pointer to an object in this variable.
    8383    When the device is removed, this cookie will be provided to you.
    8484  \return You should return \c B_OK in case of success. The USB stack will then
    85     request the kernel to republish your device names, so that the new device
     85    request the kernel to republish your device names so that the new device
    8686    will be shown in the \c /dev tree. If you return an error value, the
    8787    \a device id will become invalid and you will not be notified if this
    8888    device is removed.
     
    9191
    9292/*!
    9393  \var status_t (*usb_notify_hooks::device_removed)(void *cookie)
    94   \brief Called by the stack in case a device you are using is removed.
     94  \brief called by the stack in case a device you are using is removed
    9595 
    9696  If you have accepted a device in the device_added() hook, this hook will
    9797  be called as soon as the device is removed.
    9898 
    99   \param cookie The cookie you provided in the device_added() hook. Make sure
    100     that you free the cookie, if necessary.
     99  \param cookie This is the cookie you provided in the device_added() hook. Make sure
     100    that you free the cookie if necessary.
    101101  \return Currently the return value of this hook is ignored. It is recommended
    102102    to return \c B_OK though.
    103103*/
     
    106106 
    107107/*!
    108108  \struct usb_support_descriptor
    109   \brief Description of device descriptor that the driver can handle.
     109  \brief description of device descriptor that the driver can handle
    110110 
    111   Support descriptors can be used to match any form of class, subclass or
    112   protocol, or a vendor and/or product. If any field has the value \c 0, it
    113   is treated as a wildcard.
     111  Support descriptors can be used to match any form of class, subclass, or
     112  protocol, or they can be used to match a vendor and/or product.
     113  If any field has the value \c 0, it is treated as a wildcard.
    114114 
    115115  For example, if you want to watch for all the hubs, which have a device
    116116  class of \c 0x09, you would pass this descriptor:
     
    125125 
    126126/*!
    127127  \var usb_support_descriptor::dev_class
    128   \brief The supported device classes.
     128  \brief the supported device classes
    129129*/
    130130
    131131/*!
    132132  \var usb_support_descriptor::dev_subclass
    133   \brief The suported device subclasses.
     133  \brief the supported device subclasses
    134134*/
    135135
    136136/*!
    137137  \var usb_support_descriptor::dev_protocol
    138   \brief The supported device protocols.
     138  \brief the supported device protocols
    139139*/
    140140
    141141/*!
    142142  \var usb_support_descriptor::vendor
    143   \brief The supported device vendor.
     143  \brief the supported device vendor
    144144*/
    145145
    146146/*!
    147147  \var usb_support_descriptor::product
    148   \brief The supported device products.
     148  \brief the supported device products
    149149*/
    150150
    151151///// usb_endpoint_info /////
    152152
    153153/*!
    154154  \struct usb_endpoint_info
    155   \brief Container for endpoint descriptors and their Haiku USB stack
    156     identifiers.
     155  \brief a container for endpoint descriptors and their Haiku USB stack
     156    identifiers
    157157*/
    158158
    159159/*!
    160160  \var usb_endpoint_descriptor *usb_endpoint_info::descr
    161   \brief Pointer to the descriptor of the endpoint.
     161  \brief a pointer to the descriptor of the endpoint
    162162*/
    163163
    164164/*!
    165165  \var usb_pipe usb_endpoint_info::handle
    166   \brief Handle to use when using the stack to transfer data to and from this
    167     endpoint.
     166  \brief a handle to use when using the stack to transfer data to and from this
     167    endpoint
    168168*/
    169169
    170170///// usb_interface_info /////
    171171
    172172/*!
    173173  \struct usb_interface_info
    174   \brief Container for interface descriptors and their Haiku USB stack
    175     identifiers.
     174  \brief acontainer for interface descriptors and their Haiku USB stack
     175    identifiers
    176176*/
    177177
    178178//! @{
    179179
    180180/*!
    181181  \var usb_interface_descriptor *usb_interface_info::descr
    182   \brief Pointer to the descriptor of the interface.
     182  \brief a pointer to the descriptor of the interface
    183183*/
    184184
    185185/*!
    186186  \var usb_interface usb_interface_info::handle
    187   \brief Handle to use when using the stack to manipulate this interface.
     187  \brief a handle to use when using the stack to manipulate this interface
    188188*/
    189189
    190190//! @}
     
    197197
    198198/*!
    199199  \var size_t usb_interface_info::endpoint_count
    200   \brief The number of endpoints in this interface.
     200  \brief the number of endpoints in this interface
    201201*/
    202202
    203203/*!
    204204  \var usb_endpoint_info *usb_interface_info::endpoint
    205   \brief An array of endpoints that are associated to this interface.
     205  \brief an array of endpoints that are associated to this interface
    206206*/
    207207
    208208//! @}
     
    215215
    216216/*!
    217217  \var size_t usb_interface_info::generic_count
    218   \brief The number of unparsed descriptors in this interface.
     218  \brief the number of unparsed descriptors in this interface
    219219*/
    220220
    221221/*!
    222222  \var usb_descriptor **usb_interface_info::generic
    223   \brief Unparsed descriptors in this interface.
     223  \brief unparsed descriptors in this interface
    224224*/
    225225
    226226//! @}
     
    229229
    230230/*!
    231231  \struct usb_interface_list
    232   \brief List of interfaces available to a configuration.
     232  \brief the list of interfaces available to a configuration
    233233*/
    234234
    235235/*!
    236236  \var size_t usb_interface_list::alt_count
    237   \brief Number of available interfaces.
     237  \brief the number of available interfaces
    238238*/
    239239
    240240/*!
    241241  \var usb_interface_info *usb_interface_list::alt
    242   \brief Array of available interfaces.
     242  \brief the array of available interfaces
    243243*/
    244244
    245245/*!
    246246  \var usb_interface_info *usb_interface_list::active
    247   \brief Pointer to active interface.
     247  \brief the pointer to active interface
    248248*/
    249249
    250250///// usb_configuration_info /////
    251251
    252252/*!
    253253  \struct usb_configuration_info
    254   \brief Container for a specific configuration descriptor of a device.
     254  \brief a container for a specific configuration descriptor of a device
    255255*/
    256256
    257257/*!
    258258  \var usb_configuration_descriptor *usb_configuration_info::descr
    259   \brief The configuration descriptor.
     259  \brief the configuration descriptor
    260260*/
    261261
    262262/*!
    263263  \var size_t usb_configuration_info::interface_count
    264   \brief The number of interfaces in this configuration.
     264  \brief the number of interfaces in this configuration
    265265*/
    266266
    267267/*!
    268268  \var usb_interface_list *usb_configuration_info::interface
    269   \brief The list of interfaces available to this configuration.
     269  \brief the list of interfaces available to this configuration
    270270*/
    271271
    272272///// usb_iso_packet_descriptor /////
    273273
    274274/*!
    275275  \struct usb_iso_packet_descriptor
    276   \brief The descriptor for data packets of isochronous transfers.
     276  \brief the descriptor for data packets of isochronous transfers
    277277*/
    278278
    279279/*!
    280280  \var int16 usb_iso_packet_descriptor::req_len
    281   \brief Length of the request.
     281  \brief the length of the request
    282282*/
    283283
    284284/*!
     
    288288
    289289/*!
    290290  \var status_t usb_iso_packet_descriptor::status
    291   \brief The status of the transfer.
     291  \brief the status of the transfer
    292292*/
    293293 
    294294///// usb_callback_func /////
    295295
    296296/*!
    297297  \typedef typedef void (*usb_callback_func)(void *cookie, status_t status, void *data, size_t actualLength)
    298   \brief Callback function for asynchronous transfers.
     298  \brief callback function for asynchronous transfers
    299299
    300   \param cookie The cookie you supplied when you queued the transfer.
    301   \param status The status of the transfer. This is one of the following:
     300  \param cookie the cookie you supplied when you queued the transfer
     301  \param status This is the status of the transfer. It can be one of the following:
    302302    <table>
    303303      <tr>
    304         <td><em>B_OK</em></td><td>Transfer succeeded.</td>
     304        <td><em>B_OK</em></td><td>The transfer succeeded.</td>
    305305      </tr>
    306306      <tr>
    307         <td><em>B_CANCELED</em></td><td>Transfer cancelled by the user via a
    308           usb_module_info::cancel_queued_transfers() call.</td>
     307        <td><em>B_CANCELED</em></td><td>The transfer was cancelled by the user
     308          via a usb_module_info::cancel_queued_transfers() call.</td>
    309309      </tr>
    310310      <tr>
    311311        <td><em>B_DEV_MULTIPLE_ERRORS</em></td><td>More than one of the errors
    312           below. Unfortunately, the stack cannot give you more information.</td>
     312          below occurred. Unfortunately, the stack cannot give you more
     313          information.</td>
    313314      </tr>
    314315      <tr>
    315316        <td><em>B_DEV_STALLED</em></td><td>The endpoint is stalled. You can use
     
    322323      </tr>
    323324      <tr>
    324325        <td><em>B_DEV_DATA_UNDERRUN</em></td><td>Outgoing transfer: more data
    325           flowing out than the endpoint accepts.</td>
     326          is flowing out than the endpoint accepts.</td>
    326327      </tr>
    327328      <tr>
    328329        <td><em>B_DEV_CRC_ERROR</em></td><td>The internal data consistency
    329           checks of the USB protocol failed. You are best to retry. If you keep
    330           on getting this error, there might be something wrong with the
     330          checks of the USB protocol failed. It is best to retry. If you keep
     331          on getting this error there might be something wrong with the
    331332          device.</td>
    332333      </tr>
    333334      <tr>
    334         <td><em>B_DEV_UNEXPECTED_PID</em></td><td>Internal error. You should
    335           retry your transfer.</td>
     335        <td><em>B_DEV_UNEXPECTED_PID</em></td><td>There was an internal error.
     336          You should retry your transfer.</td>
    336337      </tr>
    337338      <tr>
    338         <td><em>B_DEV_FIFO_OVERRUN</em></td><td>Internal error. You should
    339           retry your transfer.</td>
     339        <td><em>B_DEV_FIFO_OVERRUN</em></td><td>There was an internal error.
     340          You should retry your transfer.</td>
    340341      </tr>
    341342      <tr>
    342          <td><em>B_DEV_FIFO_UNDERRUN</em></td><td>Internal error. You should
    343           retry your transfer.</td>
     343         <td><em>B_DEV_FIFO_UNDERRUN</em></td><td>There was an internal error.
     344           You should retry your transfer.</td>
    344345      </tr>
    345346    </table>
    346   \param data The provided buffer.
    347   \param actualLength The amount of bytes read or written during the transfer.
     347  \param data the provided buffer
     348  \param actualLength the amount of bytes read or written during the transfer
    348349*/
    349350
    350351///// usb_module_info /////
    351352
    352353/*!
    353354  \struct usb_module_info
    354   \brief Interface for drivers to interact with Haiku's USB stack.
     355  \brief interface for drivers to interact with Haiku's USB stack
    355356*/
    356357
    357358/*!
    358359  \var usb_module_info::binfo
    359   \brief Instance of the bus_manager_info object.
     360  \brief instance of the bus_manager_info object
    360361*/
    361362
    362363/*!
     
    364365  \brief Register your driver.
    365366 
    366367  To let the USB stack know that a driver is available to support devices, a
    367   driver needs to register itself first. To let the stack know which devices
     368  driver needs to register itself first. To let the stack know about devices
    368369  it needs to notify the driver of, have a look at usb_support_descriptor.
    369370 
    370371  It is possible to supply a list of support constructors. You should allocate
    371   an array of support constructors, and give the amount of constructors in the
     372  an array of support constructors and give the amount of constructors in the
    372373  array using the \a supportDescriptorCount parameter.
    373374 
    374   In case your driver supports all devices, or more likely, in case you want to
     375  In case your driver supports all devices or, more likely, you want to
    375376  monitor all devices plugged in and removed, it is safe to pass \c NULL to the
    376377  \a supportDescriptors paramater and zero (0) to \a supportDescriptorCount.
    377378 
    378   \param driverName A unique name that identifies your driver. Avoid names like
     379  \param driverName This is a unique name that identifies your driver. Avoid names like
    379380    \c webcam or \c mouse, instead use vendor names and device types to avoid
    380381    nameclashes. The install_notify() and uninstall_notify() functions use the
    381382    driver name as an identifier.
    382   \param supportDescriptors An array of the type usb_support_descriptor. Pass
     383  \param supportDescriptors This is an array of the type usb_support_descriptor. Pass
    383384    the amount of objects in the next parameter.
    384   \param supportDescriptorCount The number of objects in the array supplied in
    385     the previous parameter.
     385  \param supportDescriptorCount the number of objects in the array supplied in
     386    the previous parameter
    386387  \param optionalRepublishDriverName Unused parameter. You should pass \c NULL.
    387388  \retval B_OK The driver is registered. You can now call install_notify()
    388389  \retval B_BAD_VALUE You passed \c NULL as \a driverName.
    389   \retval B_ERROR General internal error in the USB stack. You may retry the
     390  \retval B_ERROR A general internal error in the USB stack occured. You may retry the
    390391    request in this case.
    391   \retval B_NO_MEMORY Error allocating some internal objects. The system is
     392  \retval B_NO_MEMORY An error allocating some internal objects occured. The system is
    392393    out of memory.
    393394*/
    394395
     
    400401  are called whenever a device that matches your \link usb_support_descriptor
    401402  support descriptor \endlink .
    402403 
    403   As soon as the hooks are installed you'll receive callbacks for devices that
    404   are already attached, so make sure your driver is initialized properly when
     404  As soon as the hooks are installed, you'll receive callbacks for devices that
     405  are already attached; so make sure your driver is initialized properly when
    405406  calling this method.
    406407 
    407   \param driverName The name you passed in register_driver().
    408   \param hooks The hooks the stack should call in case the status of devices
    409     that match your support descriptor changes.
     408  \param driverName the name you passed in register_driver()
     409  \param hooks the hooks the stack should call in case the status of devices
     410    that match your support descriptor changes
    410411  \retval B_OK Hooks are installed succesfully.
    411   \retval B_NAME_NOT_FOUND Invalid \a driverName.
     412  \retval B_NAME_NOT_FOUND invalid \a driverName
    412413 
    413414  \see usb_notify_hooks for information on how your hooks should behave.
    414415  \see uninstall_notify()
     
    419420  \brief Uninstall notify hooks for your driver.
    420421 
    421422  If your driver needs to stop, you can uninstall the notifier hooks. This will
    422   clear the stored hooks in the driver and you will not receive any
     423  clear the stored hooks in the driver, and you will not receive any
    423424  notifications when new devices are attached. This method will also call
    424425  usb_notify_hooks::device_removed() for all the devices that you are using and
    425426  all the stack's resources that are allocated to your driver are cleared.
    426427 
    427   \param driverName The name you passed in register_driver().
    428   \retval B_OK Hooks are uninstalled.
    429   \retval B_NAME_NOT_FOUND Invalid \a driverName.
     428  \param driverName the name you passed in register_driver()
     429  \retval B_OK hooks are uninstalled
     430  \retval B_NAME_NOT_FOUND invalid \a driverName
    430431*/
    431432
    432433/*!
    433434  \fn const usb_device_descriptor *(*usb_module_info::get_device_descriptor)(usb_device device)
    434435  \brief Get the device descriptor.
    435436 
    436   \param device The id of the device you want to query.
    437   \return The standard usb_device_descriptor, or \c NULL in case of an error.
     437  \param device the id of the device you want to query
     438  \return the standard usb_device_descriptor or \c NULL in case of an error
    438439*/
    439440
    440441/*!
    441442  \fn const usb_configuration_info  *(*usb_module_info::get_nth_configuration)(usb_device device, uint index)
    442443  \brief Get a configuration descriptor by index.
    443444 
    444   \param device The id of the device you want to query.
    445   \param index The (zero based) offset of the list of configurations.
    446   \return The usb_configuration_info with the standard usb configuration
    447     descriptor, or \c NULL if the \a id is invalid or the \a index is out of
    448     bounds.
     445  \param device the id of the device you want to query
     446  \param index the (zero based) offset of the list of configurations
     447  \return This will normally return the usb_configuration_info with the
     448    standard usb configuration descriptor.  \c NULL will be returned if the
     449    \a id is invalid or the \a index is out of bounds.
    449450*/
    450451
    451452/*!
    452453  \fn const usb_configuration_info  *(*usb_module_info::get_configuration)(usb_device device)
    453454  \brief Get the current configuration.
    454455 
    455   \param id The id of the device you want to query.
    456   \retval The usb_configuration_info with the standard usb configuration
    457     descriptor, or \c NULL if the \a id is invalid.
     456  \param id the id of the device you want to query
     457  \retval This will return usb_configuration_info with the standard usb
     458    configuration descriptor, or it will return\c NULL if the \a id is invalid.
    458459*/
    459460
    460461/*!
     
    465466  \a configuration points to the current configuration, the request will be
    466467  ignored and \c B_OK will be returned.
    467468 
    468   \param device The id of the device you want to query.
    469   \param configuration The pointer to the new configuration you want to set.
     469  \param device the id of the device you want to query
     470  \param configuration the pointer to the new configuration you want to set
    470471  \retval B_OK The new configuration is set succesfully.
    471472  \retval B_DEV_INVALID_PIPE The \a device parameter is invalid.
    472473  \retval B_BAD_VALUE The configuration does not exist.
     
    478479
    479480/*!
    480481  \fn status_t (*usb_module_info::set_alt_interface)(usb_device device, const usb_interface_info *interface)
    481   \brief Set an alternative interface. Not implemented.
     482  \brief Set an alternative interface. This is not implemented.
    482483 
    483484  This method currently always returns \c B_ERROR.
    484485*/
    485486
    486487/*!
    487488  \fn status_t (*usb_module_info::set_feature)(usb_id handle, uint16 selector)
    488   \brief Convenience function for standard control pipe set feature requests. 
     489  \brief convenience function for standard control pipe set feature requests
    489490
    490491  Both the set_feature() and clear_feature() requests work on all the Stack's
    491492  objects: devices, interfaces and pipes.
    492493 
    493   \param handle The object you want to query.
    494   \param selector The value you want to pass in the feature request.
    495   \return \c B_OK in case the request succeeded and the device responded
    496     positively, or an error code in case it failed.
     494  \param handle the object you want to query
     495  \param selector the value you want to pass in the feature request
     496  \return This returns \c B_OK in case the request succeeded and the device
     497    responded positively, or it returns an error code in case it failed.
    497498*/
    498499
    499500/*!
    500501  \fn status_t (*usb_module_info::clear_feature)(usb_id handle, uint16 selector)
    501   \brief Convenience function for standard control pipe clear feature requests.
     502  \brief convenience function for standard control pipe clear feature requests
    502503 
    503504  \see set_feature() to see how this method works.
    504505*/
     
    507508  \fn status_t (*usb_module_info::get_status)(usb_id handle, uint16 *status)
    508509  \brief Convenience function for standard usb status requests.
    509510 
    510   \param[in] handle The object you want to query.
    511   \param[out] status A variable in which the device can store it's status.
    512   \return \c B_OK in case the request succeeded and the device responded
    513     positively, or an error code in case it failed.
     511  \param[in] handle the object you want to query
     512  \param[out] status a variable in which the device can store it's status
     513  \return \c B_OK is returned in case the request succeeded and the device
     514    responded positively, or an error code is returned in case it failed.
    514515*/
    515516 
    516517/*!
    517518  \fn status_t (*usb_module_info::get_descriptor)(usb_device device, uint8 descriptorType, uint8 index, uint16 languageID, void *data, size_t dataLength,  size_t *actualLength)
    518   \brief Convenience function to get a descriptor from a device.
     519  \brief convenience function to get a descriptor from a device
    519520 
    520   \param[in] device The device you want to query.
    521   \param[in] descriptorType The type of descriptor you are requesting.
     521  \param[in] device the device you want to query
     522  \param[in] descriptorType the type of descriptor you are requesting
    522523  \param[in] index In case there are multiple descriptors of this type, you
    523524    select which one you want.
    524   \param[in] languageID The language you want the descriptor in (if applicable,
    525     like with string_descriptors).
    526   \param[out] data The buffer in which the descriptor can be written.
    527   \param[in] dataLength The size of the buffer (in bytes).
    528   \param[out] actualLength A pointer to a variable in which the actual number
    529     of bytes written can be stored.
     525  \param[in] languageID the language you want the descriptor in (if applicable,
     526    as with string_descriptors)
     527  \param[out] data the buffer in which the descriptor can be written
     528  \param[in] dataLength the size of the buffer (in bytes)
     529  \param[out] actualLength a pointer to a variable in which the actual number
     530    of bytes written can be stored
    530531  \retval B_OK The request succeeded, and the descriptor is written.
    531   \retval B_DEV_INVALID_PIPE Invalid \a device parameter.
    532   \retval "other errors" Request failed.
     532  \retval B_DEV_INVALID_PIPE invalid \a device parameter
     533  \retval "other errors" The Request failed.
    533534*/
    534535 
    535536/*!
     
    540541 
    541542  Most of the standard values of a request are defined in USB_spec.h.
    542543 
    543   \param[in] device The device you want to query.
    544   \param[in] requestType The request type.
    545   \param[in] request The request you want to perform.
    546   \param[in] value The value of the request.
    547   \param[in] index The index for the request.
    548   \param[in] length  The size of the buffer pointed by \a data
    549   \param[out] data The buffer where to put the result in.
    550   \param[out] actualLength The actual numbers of bytes written.
     544  \param[in] device the device you want to query
     545  \param[in] requestType the request type
     546  \param[in] request the request you want to perform
     547  \param[in] value the value of the request
     548  \param[in] index the index for the request
     549  \param[in] length the size of the buffer pointed by \a data
     550  \param[out] data the buffer where to put the result in
     551  \param[out] actualLength the actual numbers of bytes written
    551552 
    552   \retval B_OK The request succeeded.
    553   \retval B_DEV_INVALID_PIPE Invalid \a device parameter.
    554   \retval "other errors" Request failed.
     553  \retval B_OK the request succeeded
     554  \retval B_DEV_INVALID_PIPE invalid \a device parameter
     555  \retval "other errors" The request failed.
    555556*/
    556557
    557558/*!
    558559  \fn status_t (*usb_module_info::queue_interrupt)(usb_pipe pipe, void *data, size_t dataLength, usb_callback_func callback, void *callbackCookie)
    559560  \brief Asynchronously queue an interrupt transfer.
    560561 
    561   \param pipe The id of the pipe you want to query.
    562   \param data The data buffer you want to pass.
    563   \param dataLength The size of the data buffer.
    564   \param callback The callback function the stack should call after finishing.
    565   \param callbackCookie A cookie that will be supplied to your callback
    566     function when the transfer is finished.
     562  \param pipe the id of the pipe you want to query
     563  \param data the data buffer you want to pass
     564  \param dataLength the size of the data buffer
     565  \param callback the callback function the stack should call after finishing
     566  \param callbackCookie a cookie that will be supplied to your callback
     567    function when the transfer is finished
    567568 
    568   \return Whether or not the queueing of the transfer went well. The return
    569    value won't tell you if the transfer actually succeeded.
     569  \return This will return a value indicating whether or not the queueing of
     570    the transfer went well. The return value won't tell you if the transfer
     571    actually succeeded.
    570572  \retval B_OK The interrupt transfer is queued.
    571   \retval B_NO_MEMORY Error allocating objects.
     573  \retval B_NO_MEMORY error allocating objects
    572574  \retval B_DEV_INVALID_PIPE The \a pipe is not a valid interrupt pipe.
    573575*/
    574576
     
    587589  This method behaves like the queue_interrupt() method, except that it queues
    588590  bulk transfers and that it is based on an (array of) io vectors.
    589591 
    590   \param vector One or more io vectors. IO vectors are standard POSIX entities.
    591   \param vectorCount The number of elements in the \a vector array.
     592  \param vector This contains one or more io vectors. IO vectors are standard
     593    POSIX entities.
     594  \param vectorCount the number of elements in the \a vector array
    592595*/
    593596
    594597/*!
    595598  \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)
    596   \brief Asynchronously queue a isochronous transfer. Not implemented.
     599  \brief Asynchronously queue a isochronous transfer. This is not implemented.
    597600 
    598   Not implemented in the current Haiku USB Stack.
     601  This is not implemented in the current Haiku USB Stack.
    599602*/
    600603
    601604/*!
     
    606609  asynchronously. This means that the method will return as soon as the
    607610  transfer is queued.
    608611 
    609   \param callback The callback function for when the transfer is done.
    610   \param callbackCookie The cookie that the stack should pass to your callback
    611     function.
    612     \return Whether or not the queueing of the transfer went well. The return
    613    value won't tell you if the transfer actually succeeded.
    614   \retval B_OK The control transfer is queued.
    615   \retval B_NO_MEMORY Error allocating objects.
    616   \retval B_DEV_INVALID_PIPE The \a device argument is invalid.
     612  \param callback the callback function for when the transfer is done
     613  \param callbackCookie the cookie that the stack should pass to your callback
     614    functiont
     615  \return This will return a value indicating whether or not the queueing of
     616    the transfer went well. The return value won't tell you if the transfer
     617    actually succeeded.
     618  \retval B_OK the control transfer is queued
     619  \retval B_NO_MEMORY error allocating objects
     620  \retval B_DEV_INVALID_PIPE the \a device argument is invalid
    617621*/
    618622
    619623/*!
     
    621625  \brief Set some pipe features.
    622626 
    623627  The USB standard specifies some properties that should be able to be set on
    624    isochronous pipes. If your driver requires the properties to be changed, you
    625    should use this method.
     628  isochronous pipes. If your driver requires the properties to be changed, you
     629  should use this method.
    626630 
    627   \param pipe The id of the isochronous pipe you want to alter.
    628   \param maxNumQueuedPackets The maximum number of queued packets allowed on
    629     this pipe.
    630   \param maxBufferDurationMS The maximum time in ms that the buffers are valid.
    631   \param sampleSize The size of the samples through this pipe.
    632   \retval B_OK Pipe policy changed.
     631  \param pipe the id of the isochronous pipe you want to alter
     632  \param maxNumQueuedPackets the maximum number of queued packets allowed on
     633    this pipe
     634  \param maxBufferDurationMS the maximum time in ms that the buffers are valid
     635  \param sampleSize the size of the samples through this pipe
     636  \retval B_OK The pipe policy changed.
    633637  \retval B_DEV_INVALID_PIPE The \a pipe argument is invalid or not an
    634638    isochronous pipe.
    635639*/
     
    646650    performed. Make sure you don't delete any buffers that could still be used
    647651    by these transfers.
    648652 
    649   \param pipe The id of the pipe to clear.
     653  \param pipe the id of the pipe to clear
    650654 
    651655  \retval B_OK All the pending transfers on this pipe are deleted.
    652656  \retval B_DEV_INVALID_PIPE The supplied usb_id is not a valid pipe.
     
    657661  \fn status_t (*usb_module_info::usb_ioctl)(uint32 opcode, void *buffer, size_t bufferSize)
    658662  \brief Low level commands to the USB stack.
    659663 
    660   This method is used to give lowlevel commands to the Stack. There are
     664  This method is used to give low level commands to the Stack. There are
    661665  currently no uses documented.
    662666*/
    663667
     
    665669
    666670/*!
    667671  \def B_USB_MODULE_NAME
    668   \brief The identifier string for the USB Stack interface module.
     672  \brief the identifier string for the USB Stack interface module
    669673*/