81071f5e8a
- Add the beginnings of the documentation for the USB module - Fix some mistakes here and there - Almost finished the support kit. Tried to update everything to the standards git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@20724 a95241bf-73f2-0310-859d-f6bbb57e9c96
478 lines
18 KiB
Plaintext
478 lines
18 KiB
Plaintext
/*
|
|
* Copyright 2007, Haiku, Inc. All Rights Reserved.
|
|
* Distributed under the terms of the MIT License.
|
|
*
|
|
* Documentation by:
|
|
* Niels Sascha Reedijk <niels.reedijk@gmail.com>
|
|
* Corresponds to:
|
|
* /trunk/headers/os/drivers/USB3.h rev 19915
|
|
*/
|
|
|
|
/*!
|
|
\file USB3.h
|
|
\ingroup drivers
|
|
\brief Interface for the USB module.
|
|
*/
|
|
|
|
/*!
|
|
\typedef struct usb_module_info usb_module_info
|
|
\brief The main interface object. See the usb_module_info documentation.
|
|
*/
|
|
|
|
/*!
|
|
\typedef uint32 usb_id
|
|
\brief Uniquely identify various USB objects that are used in the module.
|
|
*/
|
|
|
|
/*!
|
|
\typedef usb_id usb_device
|
|
\brief Uniquely identify USB devices.
|
|
*/
|
|
|
|
/*!
|
|
\typedef usb_id usb_interface
|
|
\brief Uniquely identify USB interfaces.
|
|
*/
|
|
|
|
/*!
|
|
\typedef usb_id usb_pipe
|
|
\brief Uniquely identify USB pipes.
|
|
*/
|
|
|
|
/*!
|
|
\typedef struct usb_endpoint_info usb_endpoint_info
|
|
\brief Container for USB endpoint descriptors.
|
|
\see Documentation for usb_endpoint_info.
|
|
*/
|
|
|
|
/*!
|
|
\typedef struct usb_interface_info usb_interface_info
|
|
\brief Container for USB interface descriptors.
|
|
\see Documentation for usb_interface_info.
|
|
*/
|
|
|
|
/*!
|
|
\typedef usb_interface_list usb_interface_list
|
|
\brief Container that holds a list of USB interface descriptors.
|
|
\see Documentation for usb_interface_list.
|
|
*/
|
|
|
|
/*!
|
|
\typedef struct usb_configuration_info usb_configuration_info
|
|
\brief Container for USB configuration descriptors.
|
|
\see Documentation for usb_configuration_info.
|
|
*/
|
|
|
|
///// usb_notify_hooks /////
|
|
|
|
/*!
|
|
\struct usb_notify_hooks
|
|
\brief Hooks that the USB stack can callback in case of events.
|
|
*/
|
|
|
|
/*!
|
|
\fn status_t (*usb_notify_hooks::device_added)(usb_device device, void **cookie)
|
|
\brief Called by the stack in case a device is added.
|
|
|
|
As soon as you have registered hooks using the
|
|
usb_module_info::install_notify() method, this hook will be called as soon as
|
|
a device is inserted that matches your provided usb_support_descriptor.
|
|
|
|
\param device A unique id that identifies this USB device.
|
|
\param[in] cookie You can store a pointer to an object in this variable.
|
|
When the device is removed, this cookie will be provided to you.
|
|
\return You should return \c B_OK in case of success. If you return an error
|
|
value, the \a device id will become invalid and you will not be notified if
|
|
this device is removed.
|
|
\see device_removed()
|
|
*/
|
|
|
|
/*!
|
|
\var status_t (*usb_notify_hooks::device_removed)(void *cookie)
|
|
\brief Called by the stack in case a device you are using is removed.
|
|
|
|
If you have accepted a device in the device_added() hook, this hook will
|
|
be called as soon as the device is removed.
|
|
|
|
\param cookie The cookie you provided in the device_added() hook. Make sure
|
|
that you free the cookie, if necessary.
|
|
\return Currently the return value of this hook is ignored. It is recommended
|
|
to return \c B_OK though.
|
|
*/
|
|
|
|
///// usb_support_descriptor /////
|
|
|
|
/*!
|
|
\struct usb_support_descriptor
|
|
\brief Description of device descriptor that the driver can handle.
|
|
|
|
Support descriptors can be used to match any form of class, subclass or
|
|
protocol, or a vendor and/or product. If any field has the value \c 0, it
|
|
is treated as a wildcard.
|
|
|
|
For example, if you want to watch for all the hubs, which have a device
|
|
class of \c 0x09, you would pass this descriptor:
|
|
|
|
\code
|
|
usb_support_descriptor hub_devs = { 9, 0, 0, 0, 0 };
|
|
\endcode
|
|
|
|
See usb_module_info::register_driver() for more information on how to use
|
|
this object.
|
|
*/
|
|
|
|
/*!
|
|
\var usb_support_descriptor::dev_class
|
|
\brief The supported device classes.
|
|
*/
|
|
|
|
/*!
|
|
\var usb_support_descriptor::dev_subclass
|
|
\brief The suported device subclasses.
|
|
*/
|
|
|
|
/*!
|
|
\var usb_support_descriptor::dev_protocol
|
|
\brief The supported device protocols.
|
|
*/
|
|
|
|
/*!
|
|
\var usb_support_descriptor::vendor
|
|
\brief The supported device vendor.
|
|
*/
|
|
|
|
/*!
|
|
\var usb_support_descriptor::product
|
|
\brief The supported device products.
|
|
*/
|
|
|
|
///// usb_endpoint_info /////
|
|
|
|
///// usb_interface_info /////
|
|
|
|
///// usb_interface_list /////
|
|
|
|
///// usb_configuration_info /////
|
|
|
|
///// usb_iso_packet_descriptor /////
|
|
|
|
///// usb_callback_func /////
|
|
|
|
/*!
|
|
\typedef typedef void (*usb_callback_func)(void *cookie, status_t status, void *data, size_t actualLength)
|
|
\brief Callback function for asynchronous transfers.
|
|
|
|
\param cookie The cookie you supplied when you queued the transfer.
|
|
\param status The status of the transfer (whether it succeeded or not).
|
|
\param data The provided buffer.
|
|
\param actualLength The amount of bytes read or written during the transfer.
|
|
*/
|
|
|
|
///// usb_module_info /////
|
|
|
|
/*!
|
|
\struct usb_module_info
|
|
\brief Interface for drivers to interact with Haiku's USB stack.
|
|
*/
|
|
|
|
/*!
|
|
\var usb_module_info::binfo
|
|
\brief Instance of the bus_manager_info object.
|
|
*/
|
|
|
|
/*!
|
|
\fn status_t (*usb_module_info::register_driver)(const char *driverName, const usb_support_descriptor *supportDescriptors, size_t supportDescriptorCount, const char *optionalRepublishDriverName)
|
|
\brief Register your driver.
|
|
|
|
To let the USB stack know that a driver is available to support devices, a
|
|
driver needs to register itself first. To let the stack know which devices
|
|
it needs to notify the driver of, have a look at usb_support_descriptor.
|
|
|
|
It is possible to supply a list of support constructors. You should allocate
|
|
an array of support constructors, and give the amount of constructors in the
|
|
array using the \a supportDescriptorCount parameter.
|
|
|
|
In case your driver supports all devices, or more likely, in case you want to
|
|
monitor all devices plugged in and removed, it is safe to pass \c NULL to the
|
|
\a supportDescriptors paramater and zero (0) to \a supportDescriptorCount.
|
|
|
|
\param driverName A unique name that identifies your driver. Avoid names like
|
|
\c webcam or \c mouse, instead use vendor names and device types to avoid
|
|
nameclashes. The install_notify() and uninstall_notify() functions use the
|
|
driver name as an identifier.
|
|
\param supportDescriptors An array of the type usb_support_descriptor. Pass
|
|
the amount of objects in the next parameter.
|
|
\param supportDescriptorCount The number of objects in the array supplied in
|
|
the previous parameter.
|
|
\param optionalRepublishDriverName Undocumented parameter. It is safe to
|
|
pass \c NULL.
|
|
\retval B_OK The driver is registered. You can now call install_notify()
|
|
\retval B_BAD_VALUE You passed \c NULL as \a driverName.
|
|
\retval B_ERROR General internal error in the USB stack. You may retry the
|
|
request in this case.
|
|
\retval B_NO_MEMORY Error allocating some internal objects. The system is
|
|
out of memory.
|
|
*/
|
|
|
|
/*!
|
|
\fn status_t (*usb_module_info::install_notify)(const char *driverName, const usb_notify_hooks *hooks)
|
|
\brief Install notify hooks for your driver.
|
|
|
|
After your driver is registered, you need to pass hooks to your driver that
|
|
are called whenever a device that matches your \link usb_support_descriptor
|
|
support descriptor \endlink .
|
|
|
|
As soon as the hooks are installed you'll receive callbacks for devices that
|
|
are already attached, so make sure your driver is initialized properly when
|
|
calling this method.
|
|
|
|
\param driverName The name you passed in register_driver().
|
|
\param hooks The hooks the stack should call in case the status of devices
|
|
that match your support descriptor changes.
|
|
\retval B_OK Hooks are installed succesfully.
|
|
\retval B_NAME_NOT_FOUND Invalid \a driverName.
|
|
|
|
\see usb_notify_hooks for information on how your hooks should behave.
|
|
\see uninstall_notify()
|
|
*/
|
|
|
|
/*!
|
|
\fn status_t (*usb_module_info::uninstall_notify)(const char *driverName)
|
|
\brief Uninstall notify hooks for your driver.
|
|
|
|
If your driver needs to stop, you can uninstall the notifier hooks. This will
|
|
clear the stored hooks in the driver and you will not receive any
|
|
notifications when new devices are attached. This method will also call
|
|
usb_notify_hooks::device_removed() for all the devices that you are using and
|
|
all the stack's resources that are allocated to your driver are cleared.
|
|
|
|
\param driverName The name you passed in register_driver().
|
|
\retval B_OK Hooks are uninstalled.
|
|
\retval B_NAME_NOT_FOUND Invalid \a driverName.
|
|
*/
|
|
|
|
/*!
|
|
\fn const usb_device_descriptor *(*usb_module_info::get_device_descriptor)(usb_device device)
|
|
\brief Get the device descriptor.
|
|
|
|
\param device The id of the device you want to query.
|
|
\return The standard usb_device_descriptor, or \c NULL in case of an error.
|
|
*/
|
|
|
|
/*!
|
|
\fn const usb_configuration_info *(*usb_module_info::get_nth_configuration)(usb_device device, uint index)
|
|
\brief Get a configuration descriptor by index.
|
|
|
|
\param device The id of the device you want to query.
|
|
\param index The (zero based) offset of the list of configurations.
|
|
\return The usb_configuration_info with the standard usb configuration
|
|
descriptor, or \c NULL if the \a id is invalid or the \a index is out of
|
|
bounds.
|
|
*/
|
|
|
|
/*!
|
|
\fn const usb_configuration_info *(*usb_module_info::get_configuration)(usb_device device)
|
|
\brief Get the current configuration.
|
|
|
|
\param id The id of the device you want to query.
|
|
\retval The usb_configuration_info with the standard usb configuration
|
|
descriptor, or \c NULL if the \a id is invalid.
|
|
*/
|
|
|
|
/*!
|
|
\fn status_t (*usb_module_info::set_configuration)(usb_device device, const usb_configuration_info *configuration)
|
|
\brief Change the current configuration.
|
|
|
|
Changing the configuration will destroy all the current endpoints. If the
|
|
\a configuration points to the current configuration, the request will be
|
|
ignored and \c B_OK will be returned.
|
|
|
|
\param device The id of the device you want to query.
|
|
\param configuration The pointer to the new configuration you want to set.
|
|
\retval B_OK The new configuration is set succesfully.
|
|
\retval B_DEV_INVALID_PIPE The \a device parameter is invalid.
|
|
\retval B_BAD_VALUE The configuration does not exist.
|
|
|
|
\note This method also allows you to completely unconfigure the device, which
|
|
means that all the current endpoints, pipes and transfers will be freed.
|
|
Pass \c NULL to the parameter \a configuration if you want to do that.
|
|
*/
|
|
|
|
/*!
|
|
\fn status_t (*usb_module_info::set_alt_interface)(usb_device device, const usb_interface_info *interface)
|
|
\brief Set an alternative interface. Not implemented.
|
|
|
|
This method currently always returns \c B_ERROR.
|
|
*/
|
|
|
|
/*!
|
|
\fn status_t (*usb_module_info::set_feature)(usb_id handle, uint16 selector)
|
|
\brief Convenience function for standard control pipe set feature requests.
|
|
|
|
Both the set_feature() and clear_feature() requests work on all the Stack's
|
|
objects: devices, interfaces and pipes.
|
|
|
|
\param handle The object you want to query.
|
|
\param selector The value you want to pass in the feature request.
|
|
\return \c B_OK in case the request succeeded and the device responded
|
|
positively, or an error code in case it failed.
|
|
*/
|
|
|
|
/*!
|
|
\fn status_t (*usb_module_info::clear_feature)(usb_id handle, uint16 selector)
|
|
\brief Convenience function for standard control pipe clear feature requests.
|
|
|
|
\see set_feature() to see how this method works.
|
|
*/
|
|
|
|
/*!
|
|
\fn status_t (*usb_module_info::get_status)(usb_id handle, uint16 *status)
|
|
\brief Convenience function for standard usb status requests.
|
|
|
|
\param[in] handle The object you want to query.
|
|
\param[out] status A variable in which the device can store it's status.
|
|
\return \c B_OK in case the request succeeded and the device responded
|
|
positively, or an error code in case it failed.
|
|
*/
|
|
|
|
/*!
|
|
\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)
|
|
\brief Convenience function to get a descriptor from a device.
|
|
|
|
\param[in] device The device you want to query.
|
|
\param[in] descriptorType The type of descriptor you are requesting.
|
|
\param[in] index In case there are multiple descriptors of this type, you
|
|
select which one you want.
|
|
\param[in] languageID The language you want the descriptor in (if applicable,
|
|
like with string_descriptors).
|
|
\param[out] data The buffer in which the descriptor can be written.
|
|
\param[in] dataLength The size of the buffer (in bytes).
|
|
\param[out] actualLength A pointer to a variable in which the actual number
|
|
of bytes written can be stored.
|
|
\retval B_OK The request succeeded, and the descriptor is written.
|
|
\retval B_DEV_INVALID_PIPE Invalid \a device parameter.
|
|
\retval "other errors" Request failed.
|
|
*/
|
|
|
|
/*!
|
|
\fn status_t (*usb_module_info::send_request)(usb_device device, uint8 requestType, uint8 request, uint16 value, uint16 index, uint16 length, void *data, size_t *actualLength)
|
|
\brief Send a generic, synchronous request over the default control pipe.
|
|
|
|
See queue_request() for an asynchronous version of this method.
|
|
|
|
Most of the standard values of a request are defined in USB_spec.h.
|
|
|
|
\param[in] device The device you want to query.
|
|
\param[in] requestType The request type.
|
|
\param[in] request The request you want to perform.
|
|
\param[in] value The value of the request.
|
|
\param[in] index The index for the request.
|
|
\param[in] length The size of the buffer pointed by \a data
|
|
\param[out] data The buffer where to put the result in.
|
|
\param[out] actualLength The actual numbers of bytes written.
|
|
|
|
\retval B_OK The request succeeded.
|
|
\retval B_DEV_INVALID_PIPE Invalid \a device parameter.
|
|
\retval "other errors" Request failed.
|
|
*/
|
|
|
|
/*!
|
|
\fn status_t (*usb_module_info::queue_interrupt)(usb_pipe pipe, void *data, size_t dataLength, usb_callback_func callback, void *callbackCookie)
|
|
\brief Asynchronously queue an interrupt transfer.
|
|
|
|
\param pipe The id of the pipe you want to query.
|
|
\param data The data buffer you want to pass.
|
|
\param dataLength The size of the data buffer.
|
|
\param callback The callback function the stack should call after finishing.
|
|
\param callbackCookie A cookie that will be supplied to your callback
|
|
function when the transfer is finished.
|
|
|
|
\return Whether or not the queueing of the transfer went well. The return
|
|
value won't tell you if the transfer actually succeeded.
|
|
\retval B_OK The interrupt transfer is queued.
|
|
\retval B_NO_MEMORY Error allocating objects.
|
|
\retval B_DEV_INVALID_PIPE The \a pipe is invalid.
|
|
*/
|
|
|
|
/*!
|
|
\fn status_t (*usb_module_info::queue_bulk)(usb_pipe pipe, void *data, size_t dataLength, usb_callback_func callback, void *callbackCookie)
|
|
\brief Asynchronously queue a bulk transfer.
|
|
|
|
This method behaves like the queue_interrupt() method, except that it queues
|
|
a bulk transfer.
|
|
*/
|
|
|
|
/*!
|
|
\fn status_t (*usb_module_info::queue_bulk_v)(usb_pipe pipe, iovec *vector, size_t vectorCount, usb_callback_func callback, void *callbackCookie)
|
|
\brief Asynchronously queue a bulk vector.
|
|
|
|
This method behaves like the queue_interrupt() method, except that it queues
|
|
bulk transfers and that it is based on an (array of) io vectors.
|
|
|
|
\param vector One or more io vectors. IO vectors are standard POSIX entities.
|
|
\param vectorCount The number of elements in the \a vector array.
|
|
*/
|
|
|
|
/*!
|
|
\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)
|
|
\brief Asynchronously queue a isochronous transfer. Not implemented.
|
|
|
|
Not implemented in the current Haiku USB Stack.
|
|
*/
|
|
|
|
/*!
|
|
\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)
|
|
\brief Asynchronously queue a control pipe request.
|
|
|
|
This method does roughly the same as send_request(), however, it works
|
|
asynchronously. This means that the method will return as soon as the
|
|
transfer is queued.
|
|
|
|
\param callback The callback function for when the transfer is done.
|
|
\param callbackCookie The cookie that the stack should pass to your callback
|
|
function.
|
|
\return Whether or not the queueing of the transfer went well. The return
|
|
value won't tell you if the transfer actually succeeded.
|
|
\retval B_OK The control transfer is queued.
|
|
\retval B_NO_MEMORY Error allocating objects.
|
|
\retval B_DEV_INVALID_PIPE The \a callback is invalid.
|
|
*/
|
|
|
|
/*!
|
|
\fn status_t (*usb_module_info::set_pipe_policy)(usb_pipe pipe, uint8 maxNumQueuedPackets, uint16 maxBufferDurationMS, uint16 sampleSize)
|
|
\brief Set some pipe features.
|
|
|
|
The USB standard specifies some properties that should be able to be set on
|
|
isochronous pipes. If your driver requires the properties to be changed, you
|
|
should use this method.
|
|
|
|
\param pipe The id of the isochronous pipe you want to alter.
|
|
\param maxNumQueuedPackets The maximum number of queued packets allowed on
|
|
this pipe.
|
|
\param maxBufferDurationMS The maximum time in ms that the buffers are valid.
|
|
\param sampleSize The size of the samples through this pipe.
|
|
\retval B_OK Pipe policy changed.
|
|
\retval B_DEV_INVALID_PIPE The \a pipe argument is invalid or not an
|
|
isochronous pipe.
|
|
*/
|
|
|
|
/*!
|
|
\fn status_t (*usb_module_info::cancel_queued_transfers)(usb_pipe pipe)
|
|
\brief Cancel pending transfers. Not Implemented.
|
|
|
|
Call this method to cancel pending transfers in a \a pipe.
|
|
|
|
\warning This is currently not implemented!
|
|
|
|
\param pipe The id of the pipe to clear. The method will always return
|
|
\c B_ERROR.
|
|
*/
|
|
|
|
/*!
|
|
\fn status_t (*usb_module_info::usb_ioctl)(uint32 opcode, void *buffer, size_t bufferSize)
|
|
\brief Low level commands to the USB stack.
|
|
|
|
This method is used to give lowlevel commands to the Stack. There are
|
|
currently no uses documented.
|
|
*/
|