usb 1.7.2 → 1.8.1-libusb.4

package/libusb/libusb/hotplug.c

@@ -34,16 +34,16 @@
 #include "hotplug.h"
 
 /**
- * @defgroup hotplug  Device hotplug event notification
+ * @defgroup libusb_hotplug Device hotplug event notification
  * This page details how to use the libusb hotplug interface, where available.
  *
  * Be mindful that not all platforms currently implement hotplug notification and
  * that you should first call on \ref libusb_has_capability() with parameter
  * \ref LIBUSB_CAP_HAS_HOTPLUG to confirm that hotplug support is available.
  *
- * \page hotplug Device hotplug event notification
+ * \page libusb_hotplug Device hotplug event notification
  *
- * \section intro Introduction
+ * \section hotplug_intro Introduction
  *
  * Version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102, has added support
  * for hotplug events on <b>some</b> platforms (you should test if your platform
@@ -55,7 +55,7 @@
  *
  * To receive hotplug notification you register a callback by calling
  * \ref libusb_hotplug_register_callback(). This function will optionally return
- * a handle that can be passed to \ref libusb_hotplug_deregister_callback().
+ * a callback handle that can be passed to \ref libusb_hotplug_deregister_callback().
  *
  * A callback function must return an int (0 or 1) indicating whether the callback is
  * expecting additional events. Returning 0 will rearm the callback and 1 will cause
@@ -75,40 +75,47 @@
  *
  * Note: If you receive notification that a device has left and you have any
  * a libusb_device_handles for the device it is up to you to call libusb_close()
- * on each handle to free up any remaining resources associated with the device.
+ * on each device handle to free up any remaining resources associated with the device.
  * Once a device has left any libusb_device_handle associated with the device
  * are invalid and will remain so even if the device comes back.
  *
  * When handling a LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED event it is considered
- * safe to call any libusb function that takes a libusb_device. On the other hand,
- * when handling a LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT event the only safe function
+ * safe to call any libusb function that takes a libusb_device. It also safe to
+ * open a device and submit asynchronous transfers. However, most other functions
+ * that take a libusb_device_handle are <b>not</b> safe to call. Examples of such
+ * functions are any of the \ref libusb_syncio "synchronous API" functions or the blocking
+ * functions that retrieve various \ref libusb_desc "USB descriptors". These functions must
+ * be used outside of the context of the hotplug callback.
+ *
+ * When handling a LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT event the only safe function
  * is libusb_get_device_descriptor().
  *
  * The following code provides an example of the usage of the hotplug interface:
 \code
 #include <stdio.h>
 #include <stdlib.h>
+#include <time.h>
 #include <libusb.h>
 
 static int count = 0;
 
 int hotplug_callback(struct libusb_context *ctx, struct libusb_device *dev,
                      libusb_hotplug_event event, void *user_data) {
-  static libusb_device_handle *handle = NULL;
+  static libusb_device_handle *dev_handle = NULL;
   struct libusb_device_descriptor desc;
   int rc;
 
   (void)libusb_get_device_descriptor(dev, &desc);
 
   if (LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED == event) {
-    rc = libusb_open(dev, &handle);
+    rc = libusb_open(dev, &dev_handle);
     if (LIBUSB_SUCCESS != rc) {
       printf("Could not open USB device\n");
     }
   } else if (LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT == event) {
-    if (handle) {
-      libusb_close(handle);
-      handle = NULL;
+    if (dev_handle) {
+      libusb_close(dev_handle);
+      dev_handle = NULL;
     }
   } else {
     printf("Unhandled event %d\n", event);
@@ -119,7 +126,7 @@ int hotplug_callback(struct libusb_context *ctx, struct libusb_device *dev,
 }
 
 int main (void) {
-  libusb_hotplug_callback_handle handle;
+  libusb_hotplug_callback_handle callback_handle;
   int rc;
 
   libusb_init(NULL);
@@ -127,7 +134,7 @@ int main (void) {
   rc = libusb_hotplug_register_callback(NULL, LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED |
                                         LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT, 0, 0x045a, 0x5005,
                                         LIBUSB_HOTPLUG_MATCH_ANY, hotplug_callback, NULL,
-                                        &handle);
+                                        &callback_handle);
   if (LIBUSB_SUCCESS != rc) {
     printf("Error creating a hotplug callback\n");
     libusb_exit(NULL);
@@ -136,10 +143,10 @@ int main (void) {
 
   while (count < 2) {
     libusb_handle_events_completed(NULL, NULL);
-    usleep(10000);
+    nanosleep(&(struct timespec){0, 10000000UL}, NULL);
   }
 
-  libusb_hotplug_deregister_callback(NULL, handle);
+  libusb_hotplug_deregister_callback(NULL, callback_handle);
   libusb_exit(NULL);
 
   return 0;
@@ -147,36 +154,30 @@ int main (void) {
 \endcode
  */
 
-static int usbi_hotplug_match_cb (struct libusb_context *ctx,
+static int usbi_hotplug_match_cb(struct libusb_context *ctx,
 	struct libusb_device *dev, libusb_hotplug_event event,
 	struct libusb_hotplug_callback *hotplug_cb)
 {
-	/* Handle lazy deregistration of callback */
-	if (hotplug_cb->needs_free) {
-		/* Free callback */
-		return 1;
-	}
-
-	if (!(hotplug_cb->events & event)) {
+	if (!(hotplug_cb->flags & event)) {
 		return 0;
 	}
 
-	if (LIBUSB_HOTPLUG_MATCH_ANY != hotplug_cb->vendor_id &&
+	if ((hotplug_cb->flags & USBI_HOTPLUG_VENDOR_ID_VALID) &&
 	    hotplug_cb->vendor_id != dev->device_descriptor.idVendor) {
 		return 0;
 	}
 
-	if (LIBUSB_HOTPLUG_MATCH_ANY != hotplug_cb->product_id &&
+	if ((hotplug_cb->flags & USBI_HOTPLUG_PRODUCT_ID_VALID) &&
 	    hotplug_cb->product_id != dev->device_descriptor.idProduct) {
 		return 0;
 	}
 
-	if (LIBUSB_HOTPLUG_MATCH_ANY != hotplug_cb->dev_class &&
+	if ((hotplug_cb->flags & USBI_HOTPLUG_DEV_CLASS_VALID) &&
 	    hotplug_cb->dev_class != dev->device_descriptor.bDeviceClass) {
 		return 0;
 	}
 
-	return hotplug_cb->cb (ctx, dev, event, hotplug_cb->user_data);
+	return hotplug_cb->cb(ctx, dev, event, hotplug_cb->user_data);
 }
 
 void usbi_hotplug_match(struct libusb_context *ctx, struct libusb_device *dev,
@@ -188,8 +189,13 @@ void usbi_hotplug_match(struct libusb_context *ctx, struct libusb_device *dev,
 	usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 
 	list_for_each_entry_safe(hotplug_cb, next, &ctx->hotplug_cbs, list, struct libusb_hotplug_callback) {
+		if (hotplug_cb->flags & USBI_HOTPLUG_NEEDS_FREE) {
+			/* process deregistration in usbi_hotplug_deregister() */
+			continue;
+		}
+
 		usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
-		ret = usbi_hotplug_match_cb (ctx, dev, event, hotplug_cb);
+		ret = usbi_hotplug_match_cb(ctx, dev, event, hotplug_cb);
 		usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 
 		if (ret) {
@@ -199,69 +205,102 @@ void usbi_hotplug_match(struct libusb_context *ctx, struct libusb_device *dev,
 	}
 
 	usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
+}
+
+void usbi_hotplug_notification(struct libusb_context *ctx, struct libusb_device *dev,
+	libusb_hotplug_event event)
+{
+	int pending_events;
+	struct libusb_hotplug_message *message = calloc(1, sizeof(*message));
 
-	/* the backend is expected to call the callback for each active transfer */
+	if (!message) {
+		usbi_err(ctx, "error allocating hotplug message");
+		return;
+	}
+
+	message->event = event;
+	message->device = dev;
+
+	/* Take the event data lock and add this message to the list.
+	 * Only signal an event if there are no prior pending events. */
+	usbi_mutex_lock(&ctx->event_data_lock);
+	pending_events = usbi_pending_events(ctx);
+	list_add_tail(&message->list, &ctx->hotplug_msgs);
+	if (!pending_events)
+		usbi_signal_event(ctx);
+	usbi_mutex_unlock(&ctx->event_data_lock);
 }
 
 int API_EXPORTED libusb_hotplug_register_callback(libusb_context *ctx,
 	libusb_hotplug_event events, libusb_hotplug_flag flags,
 	int vendor_id, int product_id, int dev_class,
 	libusb_hotplug_callback_fn cb_fn, void *user_data,
-	libusb_hotplug_callback_handle *handle)
+	libusb_hotplug_callback_handle *callback_handle)
 {
-	libusb_hotplug_callback *new_callback;
-	static int handle_id = 1;
-
-	/* check for hotplug support */
-	if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG)) {
-		return LIBUSB_ERROR_NOT_SUPPORTED;
-	}
+	struct libusb_hotplug_callback *new_callback;
 
 	/* check for sane values */
-	if ((LIBUSB_HOTPLUG_MATCH_ANY != vendor_id && (~0xffff & vendor_id)) ||
+	if ((!events || (~(LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED | LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT) & events)) ||
+	    (flags && (~LIBUSB_HOTPLUG_ENUMERATE & flags)) ||
+	    (LIBUSB_HOTPLUG_MATCH_ANY != vendor_id && (~0xffff & vendor_id)) ||
 	    (LIBUSB_HOTPLUG_MATCH_ANY != product_id && (~0xffff & product_id)) ||
 	    (LIBUSB_HOTPLUG_MATCH_ANY != dev_class && (~0xff & dev_class)) ||
 	    !cb_fn) {
 		return LIBUSB_ERROR_INVALID_PARAM;
 	}
 
+	/* check for hotplug support */
+	if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG)) {
+		return LIBUSB_ERROR_NOT_SUPPORTED;
+	}
+
 	USBI_GET_CONTEXT(ctx);
 
-	new_callback = (libusb_hotplug_callback *)calloc(1, sizeof (*new_callback));
+	new_callback = calloc(1, sizeof(*new_callback));
 	if (!new_callback) {
 		return LIBUSB_ERROR_NO_MEM;
 	}
 
-	new_callback->ctx = ctx;
-	new_callback->vendor_id = vendor_id;
-	new_callback->product_id = product_id;
-	new_callback->dev_class = dev_class;
-	new_callback->flags = flags;
-	new_callback->events = events;
+	new_callback->flags = (uint8_t)events;
+	if (LIBUSB_HOTPLUG_MATCH_ANY != vendor_id) {
+		new_callback->flags |= USBI_HOTPLUG_VENDOR_ID_VALID;
+		new_callback->vendor_id = (uint16_t)vendor_id;
+	}
+	if (LIBUSB_HOTPLUG_MATCH_ANY != product_id) {
+		new_callback->flags |= USBI_HOTPLUG_PRODUCT_ID_VALID;
+		new_callback->product_id = (uint16_t)product_id;
+	}
+	if (LIBUSB_HOTPLUG_MATCH_ANY != dev_class) {
+		new_callback->flags |= USBI_HOTPLUG_DEV_CLASS_VALID;
+		new_callback->dev_class = (uint8_t)dev_class;
+	}
 	new_callback->cb = cb_fn;
 	new_callback->user_data = user_data;
-	new_callback->needs_free = 0;
 
 	usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 
-	/* protect the handle by the context hotplug lock. it doesn't matter if the same handle
-	 * is used for different contexts only that the handle is unique for this context */
-	new_callback->handle = handle_id++;
+	/* protect the handle by the context hotplug lock */
+	new_callback->handle = ctx->next_hotplug_cb_handle++;
+
+	/* handle the unlikely case of overflow */
+	if (ctx->next_hotplug_cb_handle < 0)
+		ctx->next_hotplug_cb_handle = 1;
 
 	list_add(&new_callback->list, &ctx->hotplug_cbs);
 
 	usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 
+	usbi_dbg("new hotplug cb %p with handle %d", new_callback, new_callback->handle);
 
-	if (flags & LIBUSB_HOTPLUG_ENUMERATE) {
-		int i, len;
+	if ((flags & LIBUSB_HOTPLUG_ENUMERATE) && (events & LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED)) {
+		ssize_t i, len;
 		struct libusb_device **devs;
 
-		len = (int) libusb_get_device_list(ctx, &devs);
+		len = libusb_get_device_list(ctx, &devs);
 		if (len < 0) {
 			libusb_hotplug_deregister_callback(ctx,
 							new_callback->handle);
-			return len;
+			return (int)len;
 		}
 
 		for (i = 0; i < len; i++) {
@@ -274,19 +313,17 @@ int API_EXPORTED libusb_hotplug_register_callback(libusb_context *ctx,
 	}
 
 
-	if (handle) {
-		*handle = new_callback->handle;
-	}
+	if (callback_handle)
+		*callback_handle = new_callback->handle;
 
 	return LIBUSB_SUCCESS;
 }
 
-void API_EXPORTED libusb_hotplug_deregister_callback (struct libusb_context *ctx,
-	libusb_hotplug_callback_handle handle)
+void API_EXPORTED libusb_hotplug_deregister_callback(struct libusb_context *ctx,
+	libusb_hotplug_callback_handle callback_handle)
 {
 	struct libusb_hotplug_callback *hotplug_cb;
-	libusb_hotplug_message message;
-	ssize_t ret;
+	int deregistered = 0;
 
 	/* check for hotplug support */
 	if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG)) {
@@ -295,33 +332,42 @@ void API_EXPORTED libusb_hotplug_deregister_callback (struct libusb_context *ctx
 
 	USBI_GET_CONTEXT(ctx);
 
+	usbi_dbg("deregister hotplug cb %d", callback_handle);
+
 	usbi_mutex_lock(&ctx->hotplug_cbs_lock);
-	list_for_each_entry(hotplug_cb, &ctx->hotplug_cbs, list,
-			    struct libusb_hotplug_callback) {
-		if (handle == hotplug_cb->handle) {
+	list_for_each_entry(hotplug_cb, &ctx->hotplug_cbs, list, struct libusb_hotplug_callback) {
+		if (callback_handle == hotplug_cb->handle) {
 			/* Mark this callback for deregistration */
-			hotplug_cb->needs_free = 1;
+			hotplug_cb->flags |= USBI_HOTPLUG_NEEDS_FREE;
+			deregistered = 1;
 		}
 	}
 	usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 
-	/* wakeup handle_events to do the actual free */
-	memset(&message, 0, sizeof(message));
-	ret = usbi_write(ctx->hotplug_pipe[1], &message, sizeof(message));
-	if (sizeof(message) != ret) {
-		usbi_err(ctx, "error writing hotplug message");
+	if (deregistered) {
+		int pending_events;
+
+		usbi_mutex_lock(&ctx->event_data_lock);
+		pending_events = usbi_pending_events(ctx);
+		ctx->event_flags |= USBI_EVENT_HOTPLUG_CB_DEREGISTERED;
+		if (!pending_events)
+			usbi_signal_event(ctx);
+		usbi_mutex_unlock(&ctx->event_data_lock);
 	}
 }
 
-void usbi_hotplug_deregister_all(struct libusb_context *ctx) {
+void usbi_hotplug_deregister(struct libusb_context *ctx, int forced)
+{
 	struct libusb_hotplug_callback *hotplug_cb, *next;
 
 	usbi_mutex_lock(&ctx->hotplug_cbs_lock);
-	list_for_each_entry_safe(hotplug_cb, next, &ctx->hotplug_cbs, list,
-				 struct libusb_hotplug_callback) {
-		list_del(&hotplug_cb->list);
-		free(hotplug_cb);
+	list_for_each_entry_safe(hotplug_cb, next, &ctx->hotplug_cbs, list, struct libusb_hotplug_callback) {
+		if (forced || (hotplug_cb->flags & USBI_HOTPLUG_NEEDS_FREE)) {
+			usbi_dbg("freeing hotplug cb %p with handle %d", hotplug_cb,
+				 hotplug_cb->handle);
+			list_del(&hotplug_cb->list);
+			free(hotplug_cb);
+		}
 	}
-
 	usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 }

package/libusb/libusb/hotplug.h

@@ -19,12 +19,34 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  */
 
-#if !defined(USBI_HOTPLUG_H)
+#ifndef USBI_HOTPLUG_H
 #define USBI_HOTPLUG_H
 
-#ifndef LIBUSBI_H
 #include "libusbi.h"
-#endif
+
+enum usbi_hotplug_flags {
+	/* This callback is interested in device arrivals */
+	USBI_HOTPLUG_DEVICE_ARRIVED = LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED,
+
+	/* This callback is interested in device removals */
+	USBI_HOTPLUG_DEVICE_LEFT = LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT,
+
+	/* IMPORTANT: The values for the below entries must start *after*
+	 * the highest value of the above entries!!!
+	 */
+
+	/* The vendor_id field is valid for matching */
+	USBI_HOTPLUG_VENDOR_ID_VALID = (1U << 3),
+
+	/* The product_id field is valid for matching */
+	USBI_HOTPLUG_PRODUCT_ID_VALID = (1U << 4),
+
+	/* The dev_class field is valid for matching */
+	USBI_HOTPLUG_DEV_CLASS_VALID = (1U << 5),
+
+	/* This callback has been unregistered and needs to be freed */
+	USBI_HOTPLUG_NEEDS_FREE = (1U << 6),
+};
 
 /** \ingroup hotplug
  * The hotplug callback structure. The user populates this structure with
@@ -32,23 +54,17 @@
  * to receive notification of hotplug events.
  */
 struct libusb_hotplug_callback {
-	/** Context this callback is associated with */
-	struct libusb_context *ctx;
+	/** Flags that control how this callback behaves */
+	uint8_t flags;
 
-	/** Vendor ID to match or LIBUSB_HOTPLUG_MATCH_ANY */
-	int vendor_id;
+	/** Vendor ID to match (if flags says this is valid) */
+	uint16_t vendor_id;
 
-	/** Product ID to match or LIBUSB_HOTPLUG_MATCH_ANY */
-	int product_id;
+	/** Product ID to match (if flags says this is valid) */
+	uint16_t product_id;
 
-	/** Device class to match or LIBUSB_HOTPLUG_MATCH_ANY */
-	int dev_class;
-
-	/** Hotplug callback flags */
-	libusb_hotplug_flag flags;
-
-	/** Event(s) that will trigger this callback */
-	libusb_hotplug_event events;
+	/** Device class to match (if flags says this is valid) */
+	uint8_t dev_class;
 
 	/** Callback function to invoke for matching event/device */
 	libusb_hotplug_callback_fn cb;
@@ -59,24 +75,25 @@ struct libusb_hotplug_callback {
 	/** User data that will be passed to the callback function */
 	void *user_data;
 
-	/** Callback is marked for deletion */
-	int needs_free;
-
 	/** List this callback is registered in (ctx->hotplug_cbs) */
 	struct list_head list;
 };
 
-typedef struct libusb_hotplug_callback libusb_hotplug_callback;
-
 struct libusb_hotplug_message {
+	/** The hotplug event that occurred */
 	libusb_hotplug_event event;
+
+	/** The device for which this hotplug event occurred */
 	struct libusb_device *device;
-};
 
-typedef struct libusb_hotplug_message libusb_hotplug_message;
+	/** List this message is contained in (ctx->hotplug_msgs) */
+	struct list_head list;
+};
 
-void usbi_hotplug_deregister_all(struct libusb_context *ctx);
+void usbi_hotplug_deregister(struct libusb_context *ctx, int forced);
 void usbi_hotplug_match(struct libusb_context *ctx, struct libusb_device *dev,
 			libusb_hotplug_event event);
+void usbi_hotplug_notification(struct libusb_context *ctx, struct libusb_device *dev,
+			libusb_hotplug_event event);
 
 #endif