headers/os/drivers/USB3.h

   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                                                                                 uint32 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, configuration of timeouts, etc */
 215         status_t                                                (*usb_ioctl)(uint32 opcode, void *buffer,
 216                                                                                 size_t bufferSize);
 217
 218         /*
 219          * Enumeration of device topology - With these commands you can enumerate
 220          * the roothubs and enumerate child devices of hubs. Note that the index
 221          * provided to get_nth_child does not map to the port where the child
 222          * device is attached to. To get this information you would call
 223          * get_device_parent which provides you with the parent hub and the port
 224          * index of a device. To test whether an enumerated child is a hub you
 225          * can either examine the device descriptor or you can call get_nth_child
 226          * and check the returned status. A value of B_OK indicates that the call
 227          * succeeded and the returned info is valid, B_ENTRY_NOT_FOUND indicates
 228          * that you have reached the last index. Any other error indicates that
 229          * the provided arguments are invalid (i.e. not a hub or invalid pointers)
 230          * or an internal error occured. Note that there are no guarantees that
 231          * the device handle you get stays valid while you are using it. If it gets
 232          * invalid any further use will simply return an error. You should install
 233          * notify hooks to avoid such situations.
 234          */
 235         status_t                                                (*get_nth_roothub)(uint32 index,
 236                                                                                 usb_device *rootHub);
 237         status_t                                                (*get_nth_child)(usb_device hub,
 238                                                                                 uint8 index, usb_device *childDevice);
 239         status_t                                                (*get_device_parent)(usb_device device,
 240                                                                                 usb_device *parentHub,
 241                                                                                 uint8 *portIndex);
 242
 243         /*
 244          * Hub interaction - These commands are only valid when used with a hub
 245          * device handle. Use reset_port to trigger a reset of the port with index
 246          * portIndex. This will cause a disconnect event for the attached device.
 247          * With disable_port you can specify that the port at portIndex shall be
 248          * disabled. This will also cause a disconnect event for the attached
 249          * device. Use reset_port to reenable a previously disabled port.
 250          */
 251         status_t                                                (*reset_port)(usb_device hub,
 252                                                                                 uint8 portIndex);
 253         status_t                                                (*disable_port)(usb_device hub,
 254                                                                                 uint8 portIndex);
 255 };
 256
 257
 258 #define B_USB_MODULE_NAME               "bus_managers/usb/v3"
 259
 260
 261 #ifdef __cplusplus
 262 }
 263 #endif
 264
 265 #endif /* !_USB_V3_H_ */