Interface for drivers to interact with Haiku's USB stack. More...

Public Attributes
bus_manager_info	binfo
	Instance of the bus_manager_info object.

status_t(*	cancel_queued_transfers )(usb_pipe pipe)
	Cancel pending transfers on a pipe. All the pending transfers will be cancelled. The stack will perform the callback on all of them that are cancelled.

status_t(*	clear_feature )(usb_id handle, uint16 selector)
	Convenience function for standard control pipe clear feature requests.

const usb_configuration_info (	get_configuration )(usb_device device)
	Get the current configuration.

status_t(*	get_descriptor )(usb_device device, uint8 descriptorType, uint8 index, uint16 languageID, void data, size_t dataLength, size_t actualLength)
	Convenience function to get a descriptor from a device.

const usb_device_descriptor (	get_device_descriptor )(usb_device device)
	Get the device descriptor.

const usb_configuration_info (	get_nth_configuration )(usb_device device, uint32 index)
	Get a configuration descriptor by index.

status_t(*	get_status )(usb_id handle, uint16 *status)
	Convenience function for standard usb status requests.

status_t(*	install_notify )(const char driverName, const usb_notify_hooks hooks)
	Install notify hooks for your driver.

status_t(*	queue_bulk )(usb_pipe pipe, void data, size_t dataLength, usb_callback_func callback, void callbackCookie)
	Asynchronously queue a bulk transfer.

status_t(*	queue_bulk_v )(usb_pipe pipe, iovec vector, size_t vectorCount, usb_callback_func callback, void callbackCookie)
	Asynchronously queue a bulk vector.

status_t(*	queue_interrupt )(usb_pipe pipe, void data, size_t dataLength, usb_callback_func callback, void callbackCookie)
	Asynchronously queue an interrupt transfer.

status_t(*	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)
	Asynchronously queue a isochronous transfer. Not implemented.

status_t(*	queue_request )(usb_device device, uint8 requestType, uint8 request, uint16 value, uint16 index, uint16 length, void data, usb_callback_func callback, void callbackCookie)
	Asynchronously queue a control pipe request.

status_t(*	register_driver )(const char driverName, const usb_support_descriptor supportDescriptors, size_t supportDescriptorCount, const char *optionalRepublishDriverName)
	Register your driver.

status_t(*	send_request )(usb_device device, uint8 requestType, uint8 request, uint16 value, uint16 index, uint16 length, void data, size_t actualLength)
	Send a generic, synchronous request over the default control pipe.

status_t(*	set_alt_interface )(usb_device device, const usb_interface_info *interface)
	Set an alternative interface. Not implemented.

status_t(*	set_configuration )(usb_device device, const usb_configuration_info *configuration)
	Change the current configuration.

status_t(*	set_feature )(usb_id handle, uint16 selector)
	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.

status_t(*	set_pipe_policy )(usb_pipe pipe, uint8 maxNumQueuedPackets, uint16 maxBufferDurationMS, uint16 sampleSize)
	Set some pipe features.

status_t(*	uninstall_notify )(const char *driverName)
	Uninstall notify hooks for your driver.

status_t(*	usb_ioctl )(uint32 opcode, void *buffer, size_t bufferSize)
	Low level commands to the USB stack.

Detailed Description

Interface for drivers to interact with Haiku's USB stack.

Member Data Documentation

◆ cancel_queued_transfers

status_t(* usb_module_info::cancel_queued_transfers)(usb_pipe pipe)

Cancel pending transfers on a pipe. All the pending transfers will be cancelled. The stack will perform the callback on all of them that are cancelled.

Attention: There might be transfers that are being executed the moment you call this method. These will be executed, and their callbacks will be performed. Make sure you don't delete any buffers that could still be used by these transfers.

Parameters

pipe	The id of the pipe to clear.

Return values

B_OK	All the pending transfers on this pipe are deleted.
B_DEV_INVALID_PIPE	The supplied usb_id is not a valid pipe.
other errors	There was an error clearing the pipe.

◆ clear_feature

status_t(* usb_module_info::clear_feature)(usb_id handle, uint16 selector)

Convenience function for standard control pipe clear feature requests.

See also: set_feature() to see how this method works.

◆ get_configuration

const usb_configuration_info *(* usb_module_info::get_configuration)(usb_device device)

Get the current configuration.

Parameters

id	The id of the device you want to query.

Return values

This	will return usb_configuration_info with the standard usb configuration descriptor, or it will return`NULL` if the id is invalid.

◆ get_descriptor

status_t(* usb_module_info::get_descriptor)(usb_device device, uint8 descriptorType, uint8 index, uint16 languageID, void *data, size_t dataLength, size_t *actualLength)

Convenience function to get a descriptor from a device.

Parameters

[in]	device	The device you want to query.
[in]	descriptorType	The type of descriptor you are requesting.
[in]	index	In case there are multiple descriptors of this type, you select which one you want.
[in]	languageID	The language you want the descriptor in (if applicable, as with string_descriptors).
[out]	data	The buffer in which the descriptor can be written.
[in]	dataLength	The size of the buffer (in bytes).
[out]	actualLength	A pointer to a variable in which the actual number of bytes written can be stored.

Returns: A status code.

Return values

B_OK	The request succeeded, and the descriptor is written.
B_DEV_INVALID_PIPE	Invalid device parameter.
other errors	Request failed.

◆ get_device_descriptor

const usb_device_descriptor *(* usb_module_info::get_device_descriptor)(usb_device device)

Get the device descriptor.

Parameters

device The id of the device you want to query.

Returns: The standard usb_device_descriptor, or NULL in case of an error.

◆ get_nth_configuration

const usb_configuration_info *(* usb_module_info::get_nth_configuration)(usb_device device, uint index)

Get a configuration descriptor by index.

Parameters

device	The id of the device you want to query.
index	The (zero based) offset of the list of configurations.

Returns: This will normally return the usb_configuration_info with the standard usb configuration descriptor. NULL will be returned if the id is invalid or the index is out of bounds.

◆ get_status

status_t(* usb_module_info::get_status)(usb_id handle, uint16 *status)

Convenience function for standard usb status requests.

Parameters

[in]	handle	The object you want to query.
[out]	status	A variable in which the device can store its status.

Returns: B_OK is returned in case the request succeeded and the device responded positively, or an error code is returned in case it failed.

◆ install_notify

status_t(* usb_module_info::install_notify)(const char *driverName, const usb_notify_hooks *hooks)

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 support descriptor .

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.

Parameters

driverName	The name you passed in register_driver().
hooks	The hooks the stack should call in case the status of devices that match your support descriptor changes.

Return values

B_OK	Hooks are installed succesfully.
B_NAME_NOT_FOUND	Invalid driverName.

See also: usb_notify_hooks for information on how your hooks should behave.; uninstall_notify()

◆ queue_bulk

status_t(* usb_module_info::queue_bulk)(usb_pipe pipe, void *data, size_t dataLength, usb_callback_func callback, void *callbackCookie)

Asynchronously queue a bulk transfer.

This method behaves like the queue_interrupt() method, except that it queues a bulk transfer.

◆ queue_bulk_v

status_t(* usb_module_info::queue_bulk_v)(usb_pipe pipe, iovec *vector, size_t vectorCount, usb_callback_func callback, void *callbackCookie)

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.

Parameters

vector	One or more io vectors. IO vectors are standard POSIX entities.
vectorCount	The number of elements in the vector array.

◆ queue_interrupt

status_t(* usb_module_info::queue_interrupt)(usb_pipe pipe, void *data, size_t dataLength, usb_callback_func callback, void *callbackCookie)

Asynchronously queue an interrupt transfer.

Parameters

pipe	The id of the pipe you want to query.
data	The data buffer you want to pass.
dataLength	The size of the data buffer.
callback	The callback function the stack should call after finishing.
callbackCookie	A cookie that will be supplied to your callback function when the transfer is finished.

Returns: This will return a value indicating whether or not the queueing of the transfer went well. The return value won't tell you if the transfer actually succeeded.

Return values

B_OK	The interrupt transfer is queued.
B_NO_MEMORY	Error allocating objects.
B_DEV_INVALID_PIPE	The pipe is not a valid interrupt pipe.

◆ queue_isochronous

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)

Asynchronously queue a isochronous transfer. Not implemented.

This is not implemented in the current Haiku USB Stack.

◆ queue_request

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)

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.

Parameters

callback	The callback function for when the transfer is done.
callbackCookie	The cookie that the stack should pass to your callback function.

Returns: Whether or not the queueing of the transfer went well. The return value won't tell you if the transfer actually succeeded.

Return values

B_OK	The control transfer is queued.
B_NO_MEMORY	Error allocating objects.
B_DEV_INVALID_PIPE	The device argument is invalid.

◆ register_driver

status_t(* usb_module_info::register_driver)(const char *driverName, const usb_support_descriptor *supportDescriptors, size_t supportDescriptorCount, const char *optionalRepublishDriverName)

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 about 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 supportDescriptorCount parameter.

In case your driver supports all devices or, more likely, you want to monitor all devices plugged in and removed, it is safe to pass NULL to the supportDescriptors paramater and zero (0) to supportDescriptorCount.

Parameters

driverName	A unique name that identifies your driver. Avoid names like `webcam` or `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.
supportDescriptors	An array of the type usb_support_descriptor. Pass the amount of objects in the next parameter.
supportDescriptorCount	The number of objects in the array supplied in the previous parameter.
optionalRepublishDriverName	Unused parameter. You should pass `NULL`.

Return values

B_OK	The driver is registered. You can now call install_notify()
B_BAD_VALUE	You passed `NULL` as driverName.
B_ERROR	General internal error in the USB stack. You may retry the request in this case.
B_NO_MEMORY	Error allocating some internal objects. The system is out of memory.

◆ send_request

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)

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.

Parameters

[in]	device	The device you want to query.
[in]	requestType	The request type.
[in]	request	The request you want to perform.
[in]	value	The value of the request.
[in]	index	The index for the request.
[in]	length	The size of the buffer pointed by data
[out]	data	The buffer where to put the result in.
[out]	actualLength	The actual numbers of bytes written.

Returns: A status code.

Return values

B_OK	The request succeeded.
B_DEV_INVALID_PIPE	Invalid device parameter.
other errors	Request failed.

◆ set_alt_interface

status_t(* usb_module_info::set_alt_interface)(usb_device device, const usb_interface_info *interface)

Set an alternative interface. Not implemented.

This method currently always returns B_ERROR.

◆ set_configuration

status_t(* usb_module_info::set_configuration)(usb_device device, const usb_configuration_info *configuration)

Change the current configuration.

Changing the configuration will destroy all the current endpoints. If the configuration points to the current configuration, the request will be ignored and B_OK will be returned.

Parameters

device	The id of the device you want to query.
configuration	The pointer to the new configuration you want to set.

Return values

B_OK	The new configuration is set succesfully.
B_DEV_INVALID_PIPE	The device parameter is invalid.
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 NULL to the parameter configuration if you want to do that.

◆ set_feature

status_t(* usb_module_info::set_feature)(usb_id handle, uint16 selector)

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.

Parameters

handle	The object you want to query.
selector	The value you want to pass in the feature request.

Returns: B_OK in case the request succeeded and the device responded positively, or an error code in case it failed.

◆ set_pipe_policy

status_t(* usb_module_info::set_pipe_policy)(usb_pipe pipe, uint8 maxNumQueuedPackets, uint16 maxBufferDurationMS, uint16 sampleSize)

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.

Parameters

pipe	The id of the isochronous pipe you want to alter.
maxNumQueuedPackets	The maximum number of queued packets allowed on this pipe.
maxBufferDurationMS	The maximum time in ms that the buffers are valid.
sampleSize	The size of the samples through this pipe.

Return values

B_OK	Pipe policy changed.
B_DEV_INVALID_PIPE	The pipe argument is invalid or not an isochronous pipe.

◆ uninstall_notify

status_t(* usb_module_info::uninstall_notify)(const char *driverName)

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.

Parameters

driverName The name you passed in register_driver().

Return values

B_OK	Hooks are uninstalled.
B_NAME_NOT_FOUND	Invalid driverName.

◆ usb_ioctl

status_t(* usb_module_info::usb_ioctl)(uint32 opcode, void *buffer, size_t bufferSize)

Low level commands to the USB stack.

This method is used to give lowlevel commands to the Stack. There are currently no uses documented.

Public Attributes

Detailed Description

Member Data Documentation

◆ cancel_queued_transfers

◆ clear_feature

◆ get_configuration

◆ get_descriptor

◆ get_device_descriptor

◆ get_nth_configuration

◆ get_status

◆ install_notify

◆ queue_bulk

◆ queue_bulk_v

◆ queue_interrupt

◆ queue_isochronous

◆ queue_request

◆ register_driver

◆ send_request

◆ set_alt_interface

◆ set_configuration

◆ set_feature

◆ set_pipe_policy

◆ uninstall_notify

◆ usb_ioctl