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