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_isochronous.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 // Flags for queue_isochronous 78 #define USB_ISO_ASAP 0x01 79 80 typedef void (*usb_callback_func)(void *cookie, status_t status, void *data, 81 size_t actualLength); 82 83 84 /* The usb_module_info represents the public API of the USB Stack. */ 85 struct usb_module_info { 86 bus_manager_info binfo; 87 88 /* 89 * Use register_driver() to inform the Stack of your interest to support 90 * USB devices. Support descriptors are used to indicate support for a 91 * specific device class/subclass/protocol or vendor/product. 92 * A value of 0 can be used as a wildcard for all fields. 93 * 94 * Would you like to be notified about all added hubs (class 0x09) you 95 * would use a support descriptor like this for register_driver: 96 * usb_support_descriptor hub_devs = { 9, 0, 0, 0, 0 }; 97 * 98 * If you intend to support just any device, or you at least want to be 99 * notified about any device, just pass NULL as the supportDescriptor and 100 * 0 as the supportDescriptorCount to register_driver. 101 */ 102 status_t (*register_driver)(const char *driverName, 103 const usb_support_descriptor *supportDescriptors, 104 size_t supportDescriptorCount, 105 const char *optionalRepublishDriverName); 106 107 /* 108 * Install notification hooks using your registered driverName. The 109 * device_added hook will be called for every device that matches the 110 * support descriptors you provided in register_driver. 111 * When first installing the hooks you will receive a notification about 112 * any already present matching device. If you return B_OK in this hook, 113 * you can use the id that is provided. If the hook indicates an error, 114 * the resources will be deallocated and you may not use the usb_device 115 * that is provided. In this case you will not receive a device_removed 116 * notification for the device either. 117 */ 118 status_t (*install_notify)(const char *driverName, 119 const usb_notify_hooks *hooks); 120 status_t (*uninstall_notify)(const char *driverName); 121 122 /* Get the device descriptor of a device. */ 123 const usb_device_descriptor *(*get_device_descriptor)(usb_device device); 124 125 /* Get the nth supported configuration of a device*/ 126 const usb_configuration_info *(*get_nth_configuration)(usb_device device, 127 uint32 index); 128 129 /* Get the current configuration */ 130 const usb_configuration_info *(*get_configuration)(usb_device device); 131 132 /* Set the current configuration */ 133 status_t (*set_configuration)(usb_device device, 134 const usb_configuration_info *configuration); 135 136 status_t (*set_alt_interface)(usb_device device, 137 const usb_interface_info *interface); 138 139 /* 140 * Standard device requests - convenience functions 141 * The provided handle may be a usb_device, usb_pipe or usb_interface 142 */ 143 status_t (*set_feature)(usb_id handle, uint16 selector); 144 status_t (*clear_feature)(usb_id handle, uint16 selector); 145 status_t (*get_status)(usb_id handle, uint16 *status); 146 147 status_t (*get_descriptor)(usb_device device, 148 uint8 descriptorType, uint8 index, 149 uint16 languageID, void *data, 150 size_t dataLength, 151 size_t *actualLength); 152 153 /* Generic device request function - synchronous */ 154 status_t (*send_request)(usb_device device, 155 uint8 requestType, uint8 request, 156 uint16 value, uint16 index, 157 uint16 length, void *data, 158 size_t *actualLength); 159 160 /* 161 * Asynchronous request queueing. These functions return immediately 162 * and the return code only tells whether the _queuing_ of the request 163 * was successful or not. It doesn't indicate transfer success or error. 164 * 165 * When the transfer is finished, the provided callback function is 166 * called with the transfer status, a pointer to the data buffer and 167 * the actually transfered length as well as with the callbackCookie 168 * that was used when queuing the request. 169 */ 170 status_t (*queue_interrupt)(usb_pipe pipe, 171 void *data, size_t dataLength, 172 usb_callback_func callback, 173 void *callbackCookie); 174 175 status_t (*queue_bulk)(usb_pipe pipe, 176 void *data, size_t dataLength, 177 usb_callback_func callback, 178 void *callbackCookie); 179 180 status_t (*queue_bulk_v)(usb_pipe pipe, 181 iovec *vector, size_t vectorCount, 182 usb_callback_func callback, 183 void *callbackCookie); 184 185 status_t (*queue_isochronous)(usb_pipe pipe, 186 void *data, size_t dataLength, 187 usb_iso_packet_descriptor *packetDesc, 188 uint32 packetCount, 189 uint32 *startingFrameNumber, 190 uint32 flags, 191 usb_callback_func callback, 192 void *callbackCookie); 193 194 status_t (*queue_request)(usb_device device, 195 uint8 requestType, uint8 request, 196 uint16 value, uint16 index, 197 uint16 length, void *data, 198 usb_callback_func callback, 199 void *callbackCookie); 200 201 status_t (*set_pipe_policy)(usb_pipe pipe, 202 uint8 maxNumQueuedPackets, 203 uint16 maxBufferDurationMS, 204 uint16 sampleSize); 205 206 /* Cancel all pending async requests in a pipe */ 207 status_t (*cancel_queued_transfers)(usb_pipe pipe); 208 209 /* Tuning, configuration of timeouts, etc */ 210 status_t (*usb_ioctl)(uint32 opcode, void *buffer, 211 size_t bufferSize); 212 213 /* 214 * Enumeration of device topology - With these commands you can enumerate 215 * the roothubs and enumerate child devices of hubs. Note that the index 216 * provided to get_nth_child does not map to the port where the child 217 * device is attached to. To get this information you would call 218 * get_device_parent which provides you with the parent hub and the port 219 * index of a device. To test whether an enumerated child is a hub you 220 * can either examine the device descriptor or you can call get_nth_child 221 * and check the returned status. A value of B_OK indicates that the call 222 * succeeded and the returned info is valid, B_ENTRY_NOT_FOUND indicates 223 * that you have reached the last index. Any other error indicates that 224 * the provided arguments are invalid (i.e. not a hub or invalid pointers) 225 * or an internal error occured. Note that there are no guarantees that 226 * the device handle you get stays valid while you are using it. If it gets 227 * invalid any further use will simply return an error. You should install 228 * notify hooks to avoid such situations. 229 */ 230 status_t (*get_nth_roothub)(uint32 index, 231 usb_device *rootHub); 232 status_t (*get_nth_child)(usb_device hub, 233 uint8 index, usb_device *childDevice); 234 status_t (*get_device_parent)(usb_device device, 235 usb_device *parentHub, 236 uint8 *portIndex); 237 238 /* 239 * Hub interaction - These commands are only valid when used with a hub 240 * device handle. Use reset_port to trigger a reset of the port with index 241 * portIndex. This will cause a disconnect event for the attached device. 242 * With disable_port you can specify that the port at portIndex shall be 243 * disabled. This will also cause a disconnect event for the attached 244 * device. Use reset_port to reenable a previously disabled port. 245 */ 246 status_t (*reset_port)(usb_device hub, 247 uint8 portIndex); 248 status_t (*disable_port)(usb_device hub, 249 uint8 portIndex); 250 251 /* Cancel all pending async requests in a device control pipe */ 252 status_t (*cancel_queued_requests)(usb_device device); 253 254 }; 255 256 257 #define B_USB_MODULE_NAME "bus_managers/usb/v3" 258 259 260 #ifdef __cplusplus 261 } 262 #endif 263 264 #endif /* !_USB_V3_H_ */ 265