Home | History | Annotate | Download | only in usbhost
      1 /*
      2  * Copyright (C) 2010 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 #ifndef __USB_HOST_H
     18 #define __USB_HOST_H
     19 
     20 #ifdef __cplusplus
     21 extern "C" {
     22 #endif
     23 
     24 #include <stdint.h>
     25 
     26 #include <linux/version.h>
     27 #if LINUX_VERSION_CODE > KERNEL_VERSION(2, 6, 20)
     28 #include <linux/usb/ch9.h>
     29 #else
     30 #include <linux/usb_ch9.h>
     31 #endif
     32 
     33 struct usb_host_context;
     34 struct usb_endpoint_descriptor;
     35 
     36 struct usb_descriptor_iter {
     37     unsigned char*  config;
     38     unsigned char*  config_end;
     39     unsigned char*  curr_desc;
     40 };
     41 
     42 struct usb_request
     43 {
     44     struct usb_device *dev;
     45     void* buffer;
     46     int buffer_length;
     47     int actual_length;
     48     int max_packet_size;
     49     void *private_data; /* struct usbdevfs_urb* */
     50     int endpoint;
     51     void *client_data;  /* free for use by client */
     52 };
     53 
     54 /* Callback for notification when new USB devices are attached.
     55  * Return true to exit from usb_host_run.
     56  */
     57 typedef int (* usb_device_added_cb)(const char *dev_name, void *client_data);
     58 
     59 /* Callback for notification when USB devices are removed.
     60  * Return true to exit from usb_host_run.
     61  */
     62 typedef int (* usb_device_removed_cb)(const char *dev_name, void *client_data);
     63 
     64 /* Callback indicating that initial device discovery is done.
     65  * Return true to exit from usb_host_run.
     66  */
     67 typedef int (* usb_discovery_done_cb)(void *client_data);
     68 
     69 /* Call this to initialize the USB host library. */
     70 struct usb_host_context *usb_host_init(void);
     71 
     72 /* Call this to cleanup the USB host library. */
     73 void usb_host_cleanup(struct usb_host_context *context);
     74 
     75 /* Call this to get the inotify file descriptor. */
     76 int usb_host_get_fd(struct usb_host_context *context);
     77 
     78 /* Call this to initialize the usb host context. */
     79 int usb_host_load(struct usb_host_context *context,
     80                   usb_device_added_cb added_cb,
     81                   usb_device_removed_cb removed_cb,
     82                   usb_discovery_done_cb discovery_done_cb,
     83                   void *client_data);
     84 
     85 /* Call this to read and handle occuring usb event. */
     86 int usb_host_read_event(struct usb_host_context *context);
     87 
     88 /* Call this to monitor the USB bus for new and removed devices.
     89  * This is intended to be called from a dedicated thread,
     90  * as it will not return until one of the callbacks returns true.
     91  * added_cb will be called immediately for each existing USB device,
     92  * and subsequently each time a new device is added.
     93  * removed_cb is called when USB devices are removed from the bus.
     94  * discovery_done_cb is called after the initial discovery of already
     95  * connected devices is complete.
     96  */
     97 void usb_host_run(struct usb_host_context *context,
     98                   usb_device_added_cb added_cb,
     99                   usb_device_removed_cb removed_cb,
    100                   usb_discovery_done_cb discovery_done_cb,
    101                   void *client_data);
    102 
    103 /* Creates a usb_device object for a USB device */
    104 struct usb_device *usb_device_open(const char *dev_name);
    105 
    106 /* Releases all resources associated with the USB device */
    107 void usb_device_close(struct usb_device *device);
    108 
    109 /* Creates a usb_device object for already open USB device */
    110 struct usb_device *usb_device_new(const char *dev_name, int fd);
    111 
    112 /* Returns the file descriptor for the usb_device */
    113 int usb_device_get_fd(struct usb_device *device);
    114 
    115 /* Returns the name for the USB device, which is the same as
    116  * the dev_name passed to usb_device_open()
    117  */
    118 const char* usb_device_get_name(struct usb_device *device);
    119 
    120 /* Returns a unique ID for the device.
    121  *Currently this is generated from the dev_name path.
    122  */
    123 int usb_device_get_unique_id(struct usb_device *device);
    124 
    125 /* Returns a unique ID for the device name.
    126  * Currently this is generated from the device path.
    127  */
    128 int usb_device_get_unique_id_from_name(const char* name);
    129 
    130 /* Returns the device name for the unique ID.
    131  * Call free() to deallocate the returned string */
    132 char* usb_device_get_name_from_unique_id(int id);
    133 
    134 /* Returns the USB vendor ID from the device descriptor for the USB device */
    135 uint16_t usb_device_get_vendor_id(struct usb_device *device);
    136 
    137 /* Returns the USB product ID from the device descriptor for the USB device */
    138 uint16_t usb_device_get_product_id(struct usb_device *device);
    139 
    140 const struct usb_device_descriptor* usb_device_get_device_descriptor(struct usb_device *device);
    141 
    142 /* Returns a USB descriptor string for the given string ID.
    143  * Used to implement usb_device_get_manufacturer_name,
    144  * usb_device_get_product_name and usb_device_get_serial.
    145  * Call free() to free the result when you are done with it.
    146  */
    147 char* usb_device_get_string(struct usb_device *device, int id);
    148 
    149 /* Returns the manufacturer name for the USB device.
    150  * Call free() to free the result when you are done with it.
    151  */
    152 char* usb_device_get_manufacturer_name(struct usb_device *device);
    153 
    154 /* Returns the product name for the USB device.
    155  * Call free() to free the result when you are done with it.
    156  */
    157 char* usb_device_get_product_name(struct usb_device *device);
    158 
    159 /* Returns the USB serial number for the USB device.
    160  * Call free() to free the result when you are done with it.
    161  */
    162 char* usb_device_get_serial(struct usb_device *device);
    163 
    164 /* Returns true if we have write access to the USB device,
    165  * and false if we only have access to the USB device configuration.
    166  */
    167 int usb_device_is_writeable(struct usb_device *device);
    168 
    169 /* Initializes a usb_descriptor_iter, which can be used to iterate through all
    170  * the USB descriptors for a USB device.
    171  */
    172 void usb_descriptor_iter_init(struct usb_device *device, struct usb_descriptor_iter *iter);
    173 
    174 /* Returns the next USB descriptor for a device, or NULL if we have reached the
    175  * end of the list.
    176  */
    177 struct usb_descriptor_header *usb_descriptor_iter_next(struct usb_descriptor_iter *iter);
    178 
    179 /* Claims the specified interface of a USB device */
    180 int usb_device_claim_interface(struct usb_device *device, unsigned int interface);
    181 
    182 /* Releases the specified interface of a USB device */
    183 int usb_device_release_interface(struct usb_device *device, unsigned int interface);
    184 
    185 /* Requests the kernel to connect or disconnect its driver for the specified interface.
    186  * This can be used to ask the kernel to disconnect its driver for a device
    187  * so usb_device_claim_interface can claim it instead.
    188  */
    189 int usb_device_connect_kernel_driver(struct usb_device *device,
    190         unsigned int interface, int connect);
    191 
    192 /* Sets the current configuration for the device to the specified configuration */
    193 int usb_device_set_configuration(struct usb_device *device, int configuration);
    194 
    195 /* Sets the specified interface of a USB device */
    196 int usb_device_set_interface(struct usb_device *device, unsigned int interface,
    197                             unsigned int alt_setting);
    198 
    199 /* Sends a control message to the specified device on endpoint zero */
    200 int usb_device_control_transfer(struct usb_device *device,
    201                             int requestType,
    202                             int request,
    203                             int value,
    204                             int index,
    205                             void* buffer,
    206                             int length,
    207                             unsigned int timeout);
    208 
    209 /* Reads or writes on a bulk endpoint.
    210  * Returns number of bytes transferred, or negative value for error.
    211  */
    212 int usb_device_bulk_transfer(struct usb_device *device,
    213                             int endpoint,
    214                             void* buffer,
    215                             int length,
    216                             unsigned int timeout);
    217 
    218 /* Creates a new usb_request. */
    219 struct usb_request *usb_request_new(struct usb_device *dev,
    220         const struct usb_endpoint_descriptor *ep_desc);
    221 
    222 /* Releases all resources associated with the request */
    223 void usb_request_free(struct usb_request *req);
    224 
    225 /* Submits a read or write request on the specified device */
    226 int usb_request_queue(struct usb_request *req);
    227 
    228  /* Waits for the results of a previous usb_request_queue operation.
    229   * Returns a usb_request, or NULL for error.
    230   */
    231 struct usb_request *usb_request_wait(struct usb_device *dev);
    232 
    233 /* Cancels a pending usb_request_queue() operation. */
    234 int usb_request_cancel(struct usb_request *req);
    235 
    236 #ifdef __cplusplus
    237 }
    238 #endif
    239 #endif /* __USB_HOST_H */
    240