Public Attributes | List of all members
usb_module_info Struct Reference

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. More...
 
status_t(* clear_feature )(usb_id handle, uint16 selector)
 Convenience function for standard control pipe clear feature requests. More...
 
const usb_configuration_info *(* get_configuration )(usb_device device)
 Get the current configuration. More...
 
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. More...
 
const usb_device_descriptor *(* get_device_descriptor )(usb_device device)
 Get the device descriptor. More...
 
const usb_configuration_info *(* get_nth_configuration )(usb_device device, uint32 index)
 Get a configuration descriptor by index. More...
 
status_t(* get_status )(usb_id handle, uint16 *status)
 Convenience function for standard usb status requests. More...
 
status_t(* install_notify )(const char *driverName, const usb_notify_hooks *hooks)
 Install notify hooks for your driver. More...
 
status_t(* queue_bulk )(usb_pipe pipe, void *data, size_t dataLength, usb_callback_func callback, void *callbackCookie)
 Asynchronously queue a bulk transfer. More...
 
status_t(* queue_bulk_v )(usb_pipe pipe, iovec *vector, size_t vectorCount, usb_callback_func callback, void *callbackCookie)
 Asynchronously queue a bulk vector. More...
 
status_t(* queue_interrupt )(usb_pipe pipe, void *data, size_t dataLength, usb_callback_func callback, void *callbackCookie)
 Asynchronously queue an interrupt transfer. More...
 
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. More...
 
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. More...
 
status_t(* register_driver )(const char *driverName, const usb_support_descriptor *supportDescriptors, size_t supportDescriptorCount, const char *optionalRepublishDriverName)
 Register your driver. More...
 
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. More...
 
status_t(* set_alt_interface )(usb_device device, const usb_interface_info *interface)
 Set an alternative interface. Not implemented. More...
 
status_t(* set_configuration )(usb_device device, const usb_configuration_info *configuration)
 Change the current configuration. More...
 
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. More...
 
status_t(* set_pipe_policy )(usb_pipe pipe, uint8 maxNumQueuedPackets, uint16 maxBufferDurationMS, uint16 sampleSize)
 Set some pipe features. More...
 
status_t(* uninstall_notify )(const char *driverName)
 Uninstall notify hooks for your driver. More...
 
status_t(* usb_ioctl )(uint32 opcode, void *buffer, size_t bufferSize)
 Low level commands to the USB stack. More...
 

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
pipeThe id of the pipe to clear.
Return values
B_OKAll the pending transfers on this pipe are deleted.
B_DEV_INVALID_PIPEThe supplied usb_id is not a valid pipe.
other errorsThere 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
idThe id of the device you want to query.
Return values
Thiswill return usb_configuration_info with the standard usb configuration descriptor, or it will returnNULL 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]deviceThe device you want to query.
[in]descriptorTypeThe type of descriptor you are requesting.
[in]indexIn case there are multiple descriptors of this type, you select which one you want.
[in]languageIDThe language you want the descriptor in (if applicable, as with string_descriptors).
[out]dataThe buffer in which the descriptor can be written.
[in]dataLengthThe size of the buffer (in bytes).
[out]actualLengthA pointer to a variable in which the actual number of bytes written can be stored.
Returns
A status code.
Return values
B_OKThe request succeeded, and the descriptor is written.
B_DEV_INVALID_PIPEInvalid device parameter.
other errorsRequest failed.

◆ get_device_descriptor

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

Get the device descriptor.

Parameters
deviceThe 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
deviceThe id of the device you want to query.
indexThe (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]handleThe object you want to query.
[out]statusA 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
driverNameThe name you passed in register_driver().
hooksThe hooks the stack should call in case the status of devices that match your support descriptor changes.
Return values
B_OKHooks are installed succesfully.
B_NAME_NOT_FOUNDInvalid 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
vectorOne or more io vectors. IO vectors are standard POSIX entities.
vectorCountThe 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
pipeThe id of the pipe you want to query.
dataThe data buffer you want to pass.
dataLengthThe size of the data buffer.
callbackThe callback function the stack should call after finishing.
callbackCookieA 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_OKThe interrupt transfer is queued.
B_NO_MEMORYError allocating objects.
B_DEV_INVALID_PIPEThe 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
callbackThe callback function for when the transfer is done.
callbackCookieThe 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_OKThe control transfer is queued.
B_NO_MEMORYError allocating objects.
B_DEV_INVALID_PIPEThe 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
driverNameA 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.
supportDescriptorsAn array of the type usb_support_descriptor. Pass the amount of objects in the next parameter.
supportDescriptorCountThe number of objects in the array supplied in the previous parameter.
optionalRepublishDriverNameUnused parameter. You should pass NULL.
Return values
B_OKThe driver is registered. You can now call install_notify()
B_BAD_VALUEYou passed NULL as driverName.
B_ERRORGeneral internal error in the USB stack. You may retry the request in this case.
B_NO_MEMORYError 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]deviceThe device you want to query.
[in]requestTypeThe request type.
[in]requestThe request you want to perform.
[in]valueThe value of the request.
[in]indexThe index for the request.
[in]lengthThe size of the buffer pointed by data
[out]dataThe buffer where to put the result in.
[out]actualLengthThe actual numbers of bytes written.
Returns
A status code.
Return values
B_OKThe request succeeded.
B_DEV_INVALID_PIPEInvalid device parameter.
other errorsRequest 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
deviceThe id of the device you want to query.
configurationThe pointer to the new configuration you want to set.
Return values
B_OKThe new configuration is set succesfully.
B_DEV_INVALID_PIPEThe device parameter is invalid.
B_BAD_VALUEThe 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
handleThe object you want to query.
selectorThe 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
pipeThe id of the isochronous pipe you want to alter.
maxNumQueuedPacketsThe maximum number of queued packets allowed on this pipe.
maxBufferDurationMSThe maximum time in ms that the buffers are valid.
sampleSizeThe size of the samples through this pipe.
Return values
B_OKPipe policy changed.
B_DEV_INVALID_PIPEThe 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
driverNameThe name you passed in register_driver().
Return values
B_OKHooks are uninstalled.
B_NAME_NOT_FOUNDInvalid 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.