1 /* 2 * Version 2 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_V2_H_ 9 #define _USB_V2_H_ 10 11 #include <KernelExport.h> 12 #include <bus_manager.h> 13 14 #include <USB_spec.h> 15 #include <USB_rle.h> 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 typedef struct usb_module_info usb_module_info; 22 23 /* these are opaque handles to internal stack objects */ 24 typedef struct usb_device usb_device; 25 typedef struct usb_interface usb_interface; 26 typedef struct usb_pipe 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)(const 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 void (*usb_callback_func)(void *cookie, status_t status, void *data, 77 size_t actualLength); 78 79 80 /* The usb_module_info represents the public API of the USB Stack. */ 81 struct usb_module_info { 82 bus_manager_info binfo; 83 84 /* 85 * Use register_driver() to inform the Stack of your interest to support 86 * USB devices. Support descriptors are used to indicate support for a 87 * specific device class/subclass/protocol or vendor/product. 88 * A value of 0 can be used as a wildcard for all fields. 89 * 90 * Would you like to be notified about all added hubs (class 0x09) you 91 * would a support descriptor like this to register_driver: 92 * usb_support_descriptor hub_devs = { 9, 0, 0, 0, 0 }; 93 * 94 * If you intend to support just any device, or you at least want to be 95 * notified about any device, just pass NULL as the supportDescriptor and 96 * 0 as the supportDescriptorCount to register_driver. 97 */ 98 status_t (*register_driver)(const char *driverName, 99 const usb_support_descriptor *supportDescriptors, 100 size_t supportDescriptorCount, 101 const char *optionalRepublishDriverName); 102 103 /* 104 * Install notification hooks using your registered driverName. The 105 * device_added hook will be called for every device that matches the 106 * support descriptors you provided in register_driver. 107 * When first installing the hooks you will receive a notification about 108 * any already present matching device. If you return B_OK in this hook, 109 * you can use the id that is provided. If the hook indicates an error, 110 * the resources will be deallocated and you may not use the usb_device 111 * that is provided. In this case you will not receive a device_removed 112 * notification for the device either. 113 */ 114 status_t (*install_notify)(const char *driverName, 115 const usb_notify_hooks *hooks); 116 status_t (*uninstall_notify)(const char *driverName); 117 118 /* Get the device descriptor of a device. */ 119 const usb_device_descriptor *(*get_device_descriptor)(const usb_device *device); 120 121 /* Get the nth supported configuration of a device*/ 122 const usb_configuration_info *(*get_nth_configuration)(const usb_device *device, 123 uint index); 124 125 /* Get the current configuration */ 126 const usb_configuration_info *(*get_configuration)(const usb_device *device); 127 128 /* Set the current configuration */ 129 status_t (*set_configuration)(const usb_device *device, 130 const usb_configuration_info *configuration); 131 132 status_t (*set_alt_interface)(const usb_device *device, 133 const usb_interface_info *interface); 134 135 /* 136 * Standard device requests - convenience functions 137 * The provided object may be a usb_device, usb_pipe or usb_interface 138 */ 139 status_t (*set_feature)(const void *object, uint16 selector); 140 status_t (*clear_feature)(const void *object, uint16 selector); 141 status_t (*get_status)(const void *object, uint16 *status); 142 143 status_t (*get_descriptor)(const usb_device *device, 144 uint8 descriptorType, uint8 index, 145 uint16 languageID, void *data, 146 size_t dataLength, 147 size_t *actualLength); 148 149 /* Generic device request function - synchronous */ 150 status_t (*send_request)(const usb_device *device, 151 uint8 requestType, uint8 request, 152 uint16 value, uint16 index, 153 uint16 length, void *data, 154 size_t dataLength, 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)(const usb_pipe *pipe, 168 void *data, size_t dataLength, 169 usb_callback_func callback, 170 void *callbackCookie); 171 172 status_t (*queue_bulk)(const usb_pipe *pipe, 173 void *data, size_t dataLength, 174 usb_callback_func callback, 175 void *callbackCookie); 176 177 status_t (*queue_isochronous)(const usb_pipe *pipe, 178 void *data, size_t dataLength, 179 rlea *rleArray, 180 uint16 bufferDurationMS, 181 usb_callback_func callback, 182 void *callbackCookie); 183 184 status_t (*queue_request)(const usb_device *device, 185 uint8 requestType, uint8 request, 186 uint16 value, uint16 index, 187 uint16 length, void *data, 188 size_t dataLength, 189 usb_callback_func callback, 190 void *callbackCookie); 191 192 status_t (*set_pipe_policy)(const usb_pipe *pipe, 193 uint8 maxNumQueuedPackets, 194 uint16 maxBufferDurationMS, 195 uint16 sampleSize); 196 197 /* Cancel all pending async requests in a pipe */ 198 status_t (*cancel_queued_transfers)(const usb_pipe *pipe); 199 200 /* tuning, timeouts, etc */ 201 status_t (*usb_ioctl)(uint32 opcode, void *buffer, 202 size_t bufferSize); 203 }; 204 205 206 #define B_USB_MODULE_NAME "bus_managers/usb/v2" 207 208 209 #ifdef __cplusplus 210 } 211 #endif 212 213 #endif /* !_USB_V2_H_ */ 214