1 /* 2 * Version 3 USB Device Driver API 3 * 4 * Copyright 2006, Haiku Inc. All Rights Reserved. 5 * Distributed under the terms of the MIT License. 6 */ 7 8 #ifndef _USB_V3_H_ 9 #define _USB_V3_H_ 10 11 #include <KernelExport.h> 12 #include <bus_manager.h> 13 #include <iovec.h> 14 15 #include <USB_spec.h> 16 #include <USB_rle.h> 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 typedef struct usb_module_info usb_module_info; 23 24 typedef uint32 usb_id; 25 typedef usb_id usb_device; 26 typedef usb_id usb_interface; 27 typedef usb_id usb_pipe; 28 29 typedef struct usb_endpoint_info usb_endpoint_info; 30 typedef struct usb_interface_info usb_interface_info; 31 typedef struct usb_interface_list usb_interface_list; 32 typedef struct usb_configuration_info usb_configuration_info; 33 34 typedef struct usb_notify_hooks { 35 status_t (*device_added)(usb_device device, void **cookie); 36 status_t (*device_removed)(void *cookie); 37 } usb_notify_hooks; 38 39 typedef struct usb_support_descriptor { 40 uint8 dev_class; 41 uint8 dev_subclass; 42 uint8 dev_protocol; 43 uint16 vendor; 44 uint16 product; 45 } usb_support_descriptor; 46 47 struct usb_endpoint_info { 48 usb_endpoint_descriptor *descr; /* descriptor and handle */ 49 usb_pipe handle; /* of this endpoint/pipe */ 50 }; 51 52 struct usb_interface_info { 53 usb_interface_descriptor *descr; /* descriptor and handle */ 54 usb_interface handle; /* of this interface */ 55 56 size_t endpoint_count; /* count and list of endpoints */ 57 usb_endpoint_info *endpoint; /* in this interface */ 58 59 size_t generic_count; /* unparsed descriptors in */ 60 usb_descriptor **generic; /* this interface */ 61 }; 62 63 struct usb_interface_list { 64 size_t alt_count; /* count and list of alternate */ 65 usb_interface_info *alt; /* interfaces available */ 66 67 usb_interface_info *active; /* currently active alternate */ 68 }; 69 70 struct usb_configuration_info { 71 usb_configuration_descriptor *descr; /* descriptor of this config */ 72 73 size_t interface_count;/* interfaces in this config */ 74 usb_interface_list *interface; 75 }; 76 77 typedef void (*usb_callback_func)(void *cookie, uint32 status, void *data, 78 uint32 actualLength); 79 80 81 /* The usb_module_info represents the public API of the USB Stack. */ 82 struct usb_module_info { 83 bus_manager_info binfo; 84 85 /* 86 * Use register_driver() to inform the Stack of your interest to support 87 * USB devices. Support descriptors are used to indicate support for a 88 * specific device class/subclass/protocol or vendor/product. 89 * A value of 0 can be used as a wildcard for all fields. 90 * 91 * Would you like to be notified about all added hubs (class 0x09) you 92 * would a support descriptor like this to register_driver: 93 * usb_support_descriptor hub_devs = { 9, 0, 0, 0, 0 }; 94 * 95 * If you intend to support just any device, or you at least want to be 96 * notified about any device, just pass NULL as the supportDescriptor and 97 * 0 as the supportDescriptorCount to register_driver. 98 */ 99 status_t (*register_driver)(const char *driverName, 100 const usb_support_descriptor *supportDescriptors, 101 size_t supportDescriptorCount, 102 const char *optionalRepublishDriverName); 103 104 /* 105 * Install notification hooks using your registered driverName. The 106 * device_added hook will be called for every device that matches the 107 * support descriptors you provided in register_driver. 108 * When first installing the hooks you will receive a notification about 109 * any already present matching device. If you return B_OK in this hook, 110 * you can use the id that is provided. If the hook indicates an error, 111 * the resources will be deallocated and you may not use the usb_device 112 * that is provided. In this case you will not receive a device_removed 113 * notification for the device either. 114 */ 115 status_t (*install_notify)(const char *driverName, 116 const usb_notify_hooks *hooks); 117 status_t (*uninstall_notify)(const char *driverName); 118 119 /* Get the device descriptor of a device. */ 120 const usb_device_descriptor *(*get_device_descriptor)(usb_device device); 121 122 /* Get the nth supported configuration of a device*/ 123 const usb_configuration_info *(*get_nth_configuration)(usb_device device, 124 uint index); 125 126 /* Get the current configuration */ 127 const usb_configuration_info *(*get_configuration)(usb_device device); 128 129 /* Set the current configuration */ 130 status_t (*set_configuration)(usb_device device, 131 const usb_configuration_info *configuration); 132 133 status_t (*set_alt_interface)(usb_device device, 134 const usb_interface_info *interface); 135 136 /* 137 * Standard device requests - convenience functions 138 * The provided handle may be a usb_device, usb_pipe or usb_interface 139 */ 140 status_t (*set_feature)(usb_id handle, uint16 selector); 141 status_t (*clear_feature)(usb_id handle, uint16 selector); 142 status_t (*get_status)(usb_id handle, uint16 *status); 143 144 status_t (*get_descriptor)(usb_device device, 145 uint8 descriptorType, uint8 index, 146 uint16 languageID, void *data, 147 size_t dataLength, 148 size_t *actualLength); 149 150 /* Generic device request function - synchronous */ 151 status_t (*send_request)(usb_device device, 152 uint8 requestType, uint8 request, 153 uint16 value, uint16 index, 154 uint16 length, void *data, 155 size_t *actualLength); 156 157 /* 158 * Asynchronous request queueing. These functions return immediately 159 * and the return code only tells whether the _queuing_ of the request 160 * was successful or not. It doesn't indicate transfer success or error. 161 * 162 * When the transfer is finished, the provided callback function is 163 * called with the transfer status, a pointer to the data buffer and 164 * the actually transfered length as well as with the callbackCookie 165 * that was used when queuing the request. 166 */ 167 status_t (*queue_interrupt)(usb_pipe pipe, 168 void *data, size_t dataLength, 169 usb_callback_func callback, 170 void *callbackCookie); 171 172 status_t (*queue_bulk)(usb_pipe pipe, 173 void *data, size_t dataLength, 174 usb_callback_func callback, 175 void *callbackCookie); 176 177 status_t (*queue_bulk_v)(usb_pipe pipe, 178 iovec *vector, size_t vectorCount, 179 usb_callback_func callback, 180 void *callbackCookie); 181 182 status_t (*queue_isochronous)(usb_pipe pipe, 183 void *data, size_t dataLength, 184 rlea *rleArray, 185 uint16 bufferDurationMS, 186 usb_callback_func callback, 187 void *callbackCookie); 188 189 status_t (*queue_request)(usb_device device, 190 uint8 requestType, uint8 request, 191 uint16 value, uint16 index, 192 uint16 length, void *data, 193 usb_callback_func callback, 194 void *callbackCookie); 195 196 status_t (*set_pipe_policy)(usb_pipe pipe, 197 uint8 maxNumQueuedPackets, 198 uint16 maxBufferDurationMS, 199 uint16 sampleSize); 200 201 /* Cancel all pending async requests in a pipe */ 202 status_t (*cancel_queued_transfers)(usb_pipe pipe); 203 204 /* tuning, timeouts, etc */ 205 status_t (*usb_ioctl)(uint32 opcode, void *buffer, 206 size_t bufferSize); 207 }; 208 209 210 /* 211 * These status are passed to the usb_callback_func callbacks. They indicate 212 * the status of a completed queued transfer. Multiple of these status codes 213 * may be combined. For example it is possible to have: 214 * B_USB_STATUS_DEVICE_TIMEOUT | B_USB_STATUS_DEVICE_STALLED 215 * This indicates that a timeout happened and that the used pipe is now 216 * stalled. 217 */ 218 #define B_USB_STATUS_SUCCESS 0x0000 219 #define B_USB_STATUS_DEVICE_CRC_ERROR 0x0002 220 #define B_USB_STATUS_DEVICE_TIMEOUT 0x0004 221 #define B_USB_STATUS_DEVICE_STALLED 0x0008 222 #define B_USB_STATUS_IRP_CANCELLED_BY_REQUEST 0x0010 223 #define B_USB_STATUS_DRIVER_INTERNAL_ERROR 0x0020 224 #define B_USB_STATUS_ADAPTER_HARDWARE_ERROR 0x0040 225 #define B_USB_STATUS_ISOCH_IRP_ABORTED 0x0080 226 227 228 #define B_USB_MODULE_NAME "bus_managers/usb/v3" 229 230 231 #ifdef __cplusplus 232 } 233 #endif 234 235 #endif /* !_USB_V3_H_ */ 236