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 request_length; 78 int16 actual_length; 79 status_t status; 80 } usb_iso_packet_descriptor; 81 82 // Flags for queue_isochronous 83 #define USB_ISO_ASAP 0x01 84 85 typedef void (*usb_callback_func)(void *cookie, status_t status, void *data, 86 size_t actualLength); 87 88 89 /* The usb_module_info represents the public API of the USB Stack. */ 90 struct usb_module_info { 91 bus_manager_info binfo; 92 93 /* 94 * Use register_driver() to inform the Stack of your interest to support 95 * USB devices. Support descriptors are used to indicate support for a 96 * specific device class/subclass/protocol or vendor/product. 97 * A value of 0 can be used as a wildcard for all fields. 98 * 99 * Would you like to be notified about all added hubs (class 0x09) you 100 * would use a support descriptor like this for register_driver: 101 * usb_support_descriptor hub_devs = { 9, 0, 0, 0, 0 }; 102 * 103 * If you intend to support just any device, or you at least want to be 104 * notified about any device, just pass NULL as the supportDescriptor and 105 * 0 as the supportDescriptorCount to register_driver. 106 */ 107 status_t (*register_driver)(const char *driverName, 108 const usb_support_descriptor *supportDescriptors, 109 size_t supportDescriptorCount, 110 const char *optionalRepublishDriverName); 111 112 /* 113 * Install notification hooks using your registered driverName. The 114 * device_added hook will be called for every device that matches the 115 * support descriptors you provided in register_driver. 116 * When first installing the hooks you will receive a notification about 117 * any already present matching device. If you return B_OK in this hook, 118 * you can use the id that is provided. If the hook indicates an error, 119 * the resources will be deallocated and you may not use the usb_device 120 * that is provided. In this case you will not receive a device_removed 121 * notification for the device either. 122 */ 123 status_t (*install_notify)(const char *driverName, 124 const usb_notify_hooks *hooks); 125 status_t (*uninstall_notify)(const char *driverName); 126 127 /* Get the device descriptor of a device. */ 128 const usb_device_descriptor *(*get_device_descriptor)(usb_device device); 129 130 /* Get the nth supported configuration of a device*/ 131 const usb_configuration_info *(*get_nth_configuration)(usb_device device, 132 uint index); 133 134 /* Get the current configuration */ 135 const usb_configuration_info *(*get_configuration)(usb_device device); 136 137 /* Set the current configuration */ 138 status_t (*set_configuration)(usb_device device, 139 const usb_configuration_info *configuration); 140 141 status_t (*set_alt_interface)(usb_device device, 142 const usb_interface_info *interface); 143 144 /* 145 * Standard device requests - convenience functions 146 * The provided handle may be a usb_device, usb_pipe or usb_interface 147 */ 148 status_t (*set_feature)(usb_id handle, uint16 selector); 149 status_t (*clear_feature)(usb_id handle, uint16 selector); 150 status_t (*get_status)(usb_id handle, uint16 *status); 151 152 status_t (*get_descriptor)(usb_device device, 153 uint8 descriptorType, uint8 index, 154 uint16 languageID, void *data, 155 size_t dataLength, 156 size_t *actualLength); 157 158 /* Generic device request function - synchronous */ 159 status_t (*send_request)(usb_device device, 160 uint8 requestType, uint8 request, 161 uint16 value, uint16 index, 162 uint16 length, void *data, 163 size_t *actualLength); 164 165 /* 166 * Asynchronous request queueing. These functions return immediately 167 * and the return code only tells whether the _queuing_ of the request 168 * was successful or not. It doesn't indicate transfer success or error. 169 * 170 * When the transfer is finished, the provided callback function is 171 * called with the transfer status, a pointer to the data buffer and 172 * the actually transfered length as well as with the callbackCookie 173 * that was used when queuing the request. 174 */ 175 status_t (*queue_interrupt)(usb_pipe pipe, 176 void *data, size_t dataLength, 177 usb_callback_func callback, 178 void *callbackCookie); 179 180 status_t (*queue_bulk)(usb_pipe pipe, 181 void *data, size_t dataLength, 182 usb_callback_func callback, 183 void *callbackCookie); 184 185 status_t (*queue_bulk_v)(usb_pipe pipe, 186 iovec *vector, size_t vectorCount, 187 usb_callback_func callback, 188 void *callbackCookie); 189 190 status_t (*queue_isochronous)(usb_pipe pipe, 191 void *data, size_t dataLength, 192 usb_iso_packet_descriptor *packetDesc, 193 uint32 packetCount, 194 uint32 *startingFrameNumber, 195 uint32 flags, 196 usb_callback_func callback, 197 void *callbackCookie); 198 199 status_t (*queue_request)(usb_device device, 200 uint8 requestType, uint8 request, 201 uint16 value, uint16 index, 202 uint16 length, void *data, 203 usb_callback_func callback, 204 void *callbackCookie); 205 206 status_t (*set_pipe_policy)(usb_pipe pipe, 207 uint8 maxNumQueuedPackets, 208 uint16 maxBufferDurationMS, 209 uint16 sampleSize); 210 211 /* Cancel all pending async requests in a pipe */ 212 status_t (*cancel_queued_transfers)(usb_pipe pipe); 213 214 /* tuning, timeouts, etc */ 215 status_t (*usb_ioctl)(uint32 opcode, void *buffer, 216 size_t bufferSize); 217 }; 218 219 220 #define B_USB_MODULE_NAME "bus_managers/usb/v3" 221 222 223 #ifdef __cplusplus 224 } 225 #endif 226 227 #endif /* !_USB_V3_H_ */ 228