269 lines
9.5 KiB
C
269 lines
9.5 KiB
C
/*
|
|
* Version 3 USB Device Driver API
|
|
*
|
|
* Copyright 2006, Haiku Inc. All Rights Reserved.
|
|
* Distributed under the terms of the MIT License.
|
|
*/
|
|
|
|
#ifndef _USB_V3_H_
|
|
#define _USB_V3_H_
|
|
|
|
#include <KernelExport.h>
|
|
#include <bus_manager.h>
|
|
#include <iovec.h>
|
|
|
|
#include <USB_spec.h>
|
|
#include <USB_isochronous.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
typedef struct usb_module_info usb_module_info;
|
|
|
|
typedef uint32 usb_id;
|
|
typedef usb_id usb_device;
|
|
typedef usb_id usb_interface;
|
|
typedef usb_id usb_pipe;
|
|
|
|
typedef struct usb_endpoint_info usb_endpoint_info;
|
|
typedef struct usb_interface_info usb_interface_info;
|
|
typedef struct usb_interface_list usb_interface_list;
|
|
typedef struct usb_configuration_info usb_configuration_info;
|
|
|
|
typedef struct usb_notify_hooks {
|
|
status_t (*device_added)(usb_device device, void **cookie);
|
|
status_t (*device_removed)(void *cookie);
|
|
} usb_notify_hooks;
|
|
|
|
typedef struct usb_support_descriptor {
|
|
uint8 dev_class;
|
|
uint8 dev_subclass;
|
|
uint8 dev_protocol;
|
|
uint16 vendor;
|
|
uint16 product;
|
|
} usb_support_descriptor;
|
|
|
|
struct usb_endpoint_info {
|
|
usb_endpoint_descriptor *descr; /* descriptor and handle */
|
|
usb_pipe handle; /* of this endpoint/pipe */
|
|
};
|
|
|
|
struct usb_interface_info {
|
|
usb_interface_descriptor *descr; /* descriptor and handle */
|
|
usb_interface handle; /* of this interface */
|
|
|
|
size_t endpoint_count; /* count and list of endpoints */
|
|
usb_endpoint_info *endpoint; /* in this interface */
|
|
|
|
size_t generic_count; /* unparsed descriptors in */
|
|
usb_descriptor **generic; /* this interface */
|
|
};
|
|
|
|
struct usb_interface_list {
|
|
size_t alt_count; /* count and list of alternate */
|
|
usb_interface_info *alt; /* interfaces available */
|
|
|
|
usb_interface_info *active; /* currently active alternate */
|
|
};
|
|
|
|
struct usb_configuration_info {
|
|
usb_configuration_descriptor *descr; /* descriptor of this config */
|
|
|
|
size_t interface_count;/* interfaces in this config */
|
|
usb_interface_list *interface;
|
|
};
|
|
|
|
// Flags for queue_isochronous
|
|
#define USB_ISO_ASAP 0x01
|
|
|
|
typedef void (*usb_callback_func)(void *cookie, status_t status, void *data,
|
|
size_t actualLength);
|
|
|
|
|
|
/* The usb_module_info represents the public API of the USB Stack. */
|
|
struct usb_module_info {
|
|
bus_manager_info binfo;
|
|
|
|
/*
|
|
* Use register_driver() to inform the Stack of your interest to support
|
|
* USB devices. Support descriptors are used to indicate support for a
|
|
* specific device class/subclass/protocol or vendor/product.
|
|
* A value of 0 can be used as a wildcard for all fields.
|
|
*
|
|
* Would you like to be notified about all added hubs (class 0x09) you
|
|
* would use a support descriptor like this for register_driver:
|
|
* usb_support_descriptor hub_devs = { 9, 0, 0, 0, 0 };
|
|
*
|
|
* If you intend to support just any device, or you at least want to be
|
|
* notified about any device, just pass NULL as the supportDescriptor and
|
|
* 0 as the supportDescriptorCount to register_driver.
|
|
*/
|
|
status_t (*register_driver)(const char *driverName,
|
|
const usb_support_descriptor *supportDescriptors,
|
|
size_t supportDescriptorCount,
|
|
const char *optionalRepublishDriverName);
|
|
|
|
/*
|
|
* Install notification hooks using your registered driverName. The
|
|
* device_added hook will be called for every device that matches the
|
|
* support descriptors you provided in register_driver.
|
|
* When first installing the hooks you will receive a notification about
|
|
* any already present matching device. If you return B_OK in this hook,
|
|
* you can use the id that is provided. If the hook indicates an error,
|
|
* the resources will be deallocated and you may not use the usb_device
|
|
* that is provided. In this case you will not receive a device_removed
|
|
* notification for the device either.
|
|
*/
|
|
status_t (*install_notify)(const char *driverName,
|
|
const usb_notify_hooks *hooks);
|
|
status_t (*uninstall_notify)(const char *driverName);
|
|
|
|
/* Get the device descriptor of a device. */
|
|
const usb_device_descriptor *(*get_device_descriptor)(usb_device device);
|
|
|
|
/* Get the nth supported configuration of a device*/
|
|
const usb_configuration_info *(*get_nth_configuration)(usb_device device,
|
|
uint32 index);
|
|
|
|
/* Get the current configuration */
|
|
const usb_configuration_info *(*get_configuration)(usb_device device);
|
|
|
|
/* Set the current configuration */
|
|
status_t (*set_configuration)(usb_device device,
|
|
const usb_configuration_info *configuration);
|
|
|
|
status_t (*set_alt_interface)(usb_device device,
|
|
const usb_interface_info *interface);
|
|
|
|
/*
|
|
* Standard device requests - convenience functions
|
|
* The provided handle may be a usb_device, usb_pipe or usb_interface
|
|
*/
|
|
status_t (*set_feature)(usb_id handle, uint16 selector);
|
|
status_t (*clear_feature)(usb_id handle, uint16 selector);
|
|
status_t (*get_status)(usb_id handle, uint16 *status);
|
|
|
|
status_t (*get_descriptor)(usb_device device,
|
|
uint8 descriptorType, uint8 index,
|
|
uint16 languageID, void *data,
|
|
size_t dataLength,
|
|
size_t *actualLength);
|
|
|
|
/* Generic device request function - synchronous */
|
|
status_t (*send_request)(usb_device device,
|
|
uint8 requestType, uint8 request,
|
|
uint16 value, uint16 index,
|
|
uint16 length, void *data,
|
|
size_t *actualLength);
|
|
|
|
/*
|
|
* Asynchronous request queueing. These functions return immediately
|
|
* and the return code only tells whether the _queuing_ of the request
|
|
* was successful or not. It doesn't indicate transfer success or error.
|
|
*
|
|
* When the transfer is finished, the provided callback function is
|
|
* called with the transfer status, a pointer to the data buffer and
|
|
* the actually transfered length as well as with the callbackCookie
|
|
* that was used when queuing the request.
|
|
*/
|
|
status_t (*queue_interrupt)(usb_pipe pipe,
|
|
void *data, size_t dataLength,
|
|
usb_callback_func callback,
|
|
void *callbackCookie);
|
|
|
|
status_t (*queue_bulk)(usb_pipe pipe,
|
|
void *data, size_t dataLength,
|
|
usb_callback_func callback,
|
|
void *callbackCookie);
|
|
|
|
status_t (*queue_bulk_v)(usb_pipe pipe,
|
|
iovec *vector, size_t vectorCount,
|
|
usb_callback_func callback,
|
|
void *callbackCookie);
|
|
|
|
status_t (*queue_bulk_v_physical)(usb_pipe pipe,
|
|
physical_entry *vectors, size_t vectorCount,
|
|
usb_callback_func callback,
|
|
void *callbackCookie);
|
|
|
|
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);
|
|
|
|
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);
|
|
|
|
status_t (*set_pipe_policy)(usb_pipe pipe,
|
|
uint8 maxNumQueuedPackets,
|
|
uint16 maxBufferDurationMS,
|
|
uint16 sampleSize);
|
|
|
|
/* Cancel all pending async requests in a pipe */
|
|
status_t (*cancel_queued_transfers)(usb_pipe pipe);
|
|
|
|
/* Cancel all pending async requests in a device control pipe */
|
|
status_t (*cancel_queued_requests)(usb_device device);
|
|
|
|
/* Tuning, configuration of timeouts, etc */
|
|
status_t (*usb_ioctl)(uint32 opcode, void *buffer,
|
|
size_t bufferSize);
|
|
|
|
/*
|
|
* Enumeration of device topology - With these commands you can enumerate
|
|
* the roothubs and enumerate child devices of hubs. Note that the index
|
|
* provided to get_nth_child does not map to the port where the child
|
|
* device is attached to. To get this information you would call
|
|
* get_device_parent which provides you with the parent hub and the port
|
|
* index of a device. To test whether an enumerated child is a hub you
|
|
* can either examine the device descriptor or you can call get_nth_child
|
|
* and check the returned status. A value of B_OK indicates that the call
|
|
* succeeded and the returned info is valid, B_ENTRY_NOT_FOUND indicates
|
|
* that you have reached the last index. Any other error indicates that
|
|
* the provided arguments are invalid (i.e. not a hub or invalid pointers)
|
|
* or an internal error occured. Note that there are no guarantees that
|
|
* the device handle you get stays valid while you are using it. If it gets
|
|
* invalid any further use will simply return an error. You should install
|
|
* notify hooks to avoid such situations.
|
|
*/
|
|
status_t (*get_nth_roothub)(uint32 index,
|
|
usb_device *rootHub);
|
|
status_t (*get_nth_child)(usb_device hub,
|
|
uint8 index, usb_device *childDevice);
|
|
status_t (*get_device_parent)(usb_device device,
|
|
usb_device *parentHub,
|
|
uint8 *portIndex);
|
|
|
|
/*
|
|
* Hub interaction - These commands are only valid when used with a hub
|
|
* device handle. Use reset_port to trigger a reset of the port with index
|
|
* portIndex. This will cause a disconnect event for the attached device.
|
|
* With disable_port you can specify that the port at portIndex shall be
|
|
* disabled. This will also cause a disconnect event for the attached
|
|
* device. Use reset_port to reenable a previously disabled port.
|
|
*/
|
|
status_t (*reset_port)(usb_device hub,
|
|
uint8 portIndex);
|
|
status_t (*disable_port)(usb_device hub,
|
|
uint8 portIndex);
|
|
};
|
|
|
|
|
|
#define B_USB_MODULE_NAME "bus_managers/usb/v3.1"
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* !_USB_V3_H_ */
|