blob: 402e693ac3797f5d21b55c2ab8907d0c56db50c9 [file] [log] [blame]
/* -*- Mode: C; indent-tabs-mode:t ; c-basic-offset:8 -*- */
/*
* Hotplug functions for libusb
* Copyright © 2012-2021 Nathan Hjelm <hjelmn@mac.com>
* Copyright © 2012-2013 Peter Stuge <peter@stuge.se>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
#include "libusbi.h"
/**
* @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 libusb_hotplug Device hotplug event notification
*
* \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
* supports hotplug notification by calling \ref libusb_has_capability() with
* parameter \ref LIBUSB_CAP_HAS_HOTPLUG).
*
* This interface allows you to request notification for the arrival and departure
* of matching USB devices.
*
* To receive hotplug notification you register a callback by calling
* \ref libusb_hotplug_register_callback(). This function will optionally return
* 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
* the callback to be deregistered. Note that when callbacks are called from
* libusb_hotplug_register_callback() because of the \ref LIBUSB_HOTPLUG_ENUMERATE
* flag, the callback return value is ignored. In other words, you cannot cause a
* callback to be deregistered by returning 1 when it is called from
* libusb_hotplug_register_callback().
*
* Callbacks for a particular context are automatically deregistered by libusb_exit().
*
* As of 1.0.16 there are two supported hotplug events:
* - LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED: A device has arrived and is ready to use
* - LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT: A device has left and is no longer available
*
* A hotplug event can listen for either or both of these events.
*
* Note: If you receive notification that a device has left and you have any
* libusb_device_handles for the device it is up to you to call libusb_close()
* 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. 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 *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, &dev_handle);
if (LIBUSB_SUCCESS != rc) {
printf("Could not open USB device\n");
}
} else if (LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT == event) {
if (dev_handle) {
libusb_close(dev_handle);
dev_handle = NULL;
}
} else {
printf("Unhandled event %d\n", event);
}
count++;
return 0;
}
int main (void) {
libusb_hotplug_callback_handle callback_handle;
int rc;
libusb_init(NULL);
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,
&callback_handle);
if (LIBUSB_SUCCESS != rc) {
printf("Error creating a hotplug callback\n");
libusb_exit(NULL);
return EXIT_FAILURE;
}
while (count < 2) {
libusb_handle_events_completed(NULL, NULL);
nanosleep(&(struct timespec){0, 10000000UL}, NULL);
}
libusb_hotplug_deregister_callback(NULL, callback_handle);
libusb_exit(NULL);
return 0;
}
\endcode
*/
#define VALID_HOTPLUG_EVENTS \
(LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED | \
LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT)
#define VALID_HOTPLUG_FLAGS \
(LIBUSB_HOTPLUG_ENUMERATE)
void usbi_hotplug_init(struct libusb_context *ctx)
{
/* check for hotplug support */
if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG))
return;
usbi_mutex_init(&ctx->hotplug_cbs_lock);
list_init(&ctx->hotplug_cbs);
ctx->next_hotplug_cb_handle = 1;
usbi_atomic_store(&ctx->hotplug_ready, 1);
}
void usbi_hotplug_exit(struct libusb_context *ctx)
{
struct usbi_hotplug_callback *hotplug_cb, *next_cb;
struct usbi_hotplug_message *msg;
struct libusb_device *dev, *next_dev;
/* check for hotplug support */
if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG))
return;
/* free all registered hotplug callbacks */
for_each_hotplug_cb_safe(ctx, hotplug_cb, next_cb) {
list_del(&hotplug_cb->list);
free(hotplug_cb);
}
/* free all pending hotplug messages */
while (!list_empty(&ctx->hotplug_msgs)) {
msg = list_first_entry(&ctx->hotplug_msgs, struct usbi_hotplug_message, list);
/* if the device left, the message holds a reference
* and we must drop it */
if (msg->event == LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT)
libusb_unref_device(msg->device);
list_del(&msg->list);
free(msg);
}
/* free all discovered devices. due to parent references loop until no devices are freed. */
for_each_device_safe(ctx, dev, next_dev) {
/* remove the device from the usb_devs list only if there are no
* references held, otherwise leave it on the list so that a
* warning message will be shown */
if (usbi_atomic_load(&dev->refcnt) == 1) {
list_del(&dev->list);
}
if (dev->parent_dev && usbi_atomic_load(&dev->parent_dev->refcnt) == 1) {
/* the parent was before this device in the list and will be released.
remove it from the list. this is safe as parent_dev can not be
equal to next_dev. */
assert (dev->parent_dev != next_dev);
list_del(&dev->parent_dev->list);
}
libusb_unref_device(dev);
}
usbi_mutex_destroy(&ctx->hotplug_cbs_lock);
}
static int usbi_hotplug_match_cb(struct libusb_device *dev,
libusb_hotplug_event event, struct usbi_hotplug_callback *hotplug_cb)
{
if (!(hotplug_cb->flags & event)) {
return 0;
}
if ((hotplug_cb->flags & USBI_HOTPLUG_VENDOR_ID_VALID) &&
hotplug_cb->vendor_id != dev->device_descriptor.idVendor) {
return 0;
}
if ((hotplug_cb->flags & USBI_HOTPLUG_PRODUCT_ID_VALID) &&
hotplug_cb->product_id != dev->device_descriptor.idProduct) {
return 0;
}
if ((hotplug_cb->flags & USBI_HOTPLUG_DEV_CLASS_VALID) &&
hotplug_cb->dev_class != dev->device_descriptor.bDeviceClass) {
return 0;
}
return hotplug_cb->cb(DEVICE_CTX(dev), dev, event, hotplug_cb->user_data);
}
void usbi_hotplug_notification(struct libusb_context *ctx, struct libusb_device *dev,
libusb_hotplug_event event)
{
struct usbi_hotplug_message *msg;
unsigned int event_flags;
/* Only generate a notification if hotplug is ready. This prevents hotplug
* notifications from being generated during initial enumeration or if the
* backend does not support hotplug. */
if (!usbi_atomic_load(&ctx->hotplug_ready))
return;
msg = calloc(1, sizeof(*msg));
if (!msg) {
usbi_err(ctx, "error allocating hotplug message");
return;
}
msg->event = event;
msg->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);
event_flags = ctx->event_flags;
ctx->event_flags |= USBI_EVENT_HOTPLUG_MSG_PENDING;
list_add_tail(&msg->list, &ctx->hotplug_msgs);
if (!event_flags)
usbi_signal_event(&ctx->event);
usbi_mutex_unlock(&ctx->event_data_lock);
}
void usbi_hotplug_process(struct libusb_context *ctx, struct list_head *hotplug_msgs)
{
struct usbi_hotplug_callback *hotplug_cb, *next_cb;
struct usbi_hotplug_message *msg;
int r;
usbi_mutex_lock(&ctx->hotplug_cbs_lock);
/* dispatch all pending hotplug messages */
while (!list_empty(hotplug_msgs)) {
msg = list_first_entry(hotplug_msgs, struct usbi_hotplug_message, list);
for_each_hotplug_cb_safe(ctx, hotplug_cb, next_cb) {
/* skip callbacks that have unregistered */
if (hotplug_cb->flags & USBI_HOTPLUG_NEEDS_FREE)
continue;
usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
r = usbi_hotplug_match_cb(msg->device, msg->event, hotplug_cb);
usbi_mutex_lock(&ctx->hotplug_cbs_lock);
if (r) {
list_del(&hotplug_cb->list);
free(hotplug_cb);
}
}
/* if the device left, the message holds a reference
* and we must drop it */
if (msg->event == LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT)
libusb_unref_device(msg->device);
list_del(&msg->list);
free(msg);
}
/* free any callbacks that have unregistered */
for_each_hotplug_cb_safe(ctx, hotplug_cb, next_cb) {
if (hotplug_cb->flags & USBI_HOTPLUG_NEEDS_FREE) {
usbi_dbg(ctx, "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);
}
int API_EXPORTED libusb_hotplug_register_callback(libusb_context *ctx,
int events, int flags,
int vendor_id, int product_id, int dev_class,
libusb_hotplug_callback_fn cb_fn, void *user_data,
libusb_hotplug_callback_handle *callback_handle)
{
struct usbi_hotplug_callback *hotplug_cb;
/* check for sane values */
if (!events || (~VALID_HOTPLUG_EVENTS & events) ||
(~VALID_HOTPLUG_FLAGS & 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;
ctx = usbi_get_context(ctx);
hotplug_cb = calloc(1, sizeof(*hotplug_cb));
if (!hotplug_cb)
return LIBUSB_ERROR_NO_MEM;
hotplug_cb->flags = (uint8_t)events;
if (LIBUSB_HOTPLUG_MATCH_ANY != vendor_id) {
hotplug_cb->flags |= USBI_HOTPLUG_VENDOR_ID_VALID;
hotplug_cb->vendor_id = (uint16_t)vendor_id;
}
if (LIBUSB_HOTPLUG_MATCH_ANY != product_id) {
hotplug_cb->flags |= USBI_HOTPLUG_PRODUCT_ID_VALID;
hotplug_cb->product_id = (uint16_t)product_id;
}
if (LIBUSB_HOTPLUG_MATCH_ANY != dev_class) {
hotplug_cb->flags |= USBI_HOTPLUG_DEV_CLASS_VALID;
hotplug_cb->dev_class = (uint8_t)dev_class;
}
hotplug_cb->cb = cb_fn;
hotplug_cb->user_data = user_data;
usbi_mutex_lock(&ctx->hotplug_cbs_lock);
/* protect the handle by the context hotplug lock */
hotplug_cb->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(&hotplug_cb->list, &ctx->hotplug_cbs);
usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
usbi_dbg(ctx, "new hotplug cb %p with handle %d", hotplug_cb, hotplug_cb->handle);
if ((flags & LIBUSB_HOTPLUG_ENUMERATE) && (events & LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED)) {
ssize_t i, len;
struct libusb_device **devs;
len = libusb_get_device_list(ctx, &devs);
if (len < 0) {
libusb_hotplug_deregister_callback(ctx, hotplug_cb->handle);
return (int)len;
}
for (i = 0; i < len; i++) {
usbi_hotplug_match_cb(devs[i],
LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED,
hotplug_cb);
}
libusb_free_device_list(devs, 1);
}
if (callback_handle)
*callback_handle = hotplug_cb->handle;
return LIBUSB_SUCCESS;
}
void API_EXPORTED libusb_hotplug_deregister_callback(libusb_context *ctx,
libusb_hotplug_callback_handle callback_handle)
{
struct usbi_hotplug_callback *hotplug_cb;
int deregistered = 0;
/* check for hotplug support */
if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG))
return;
usbi_dbg(ctx, "deregister hotplug cb %d", callback_handle);
ctx = usbi_get_context(ctx);
usbi_mutex_lock(&ctx->hotplug_cbs_lock);
for_each_hotplug_cb(ctx, hotplug_cb) {
if (callback_handle == hotplug_cb->handle) {
/* mark this callback for deregistration */
hotplug_cb->flags |= USBI_HOTPLUG_NEEDS_FREE;
deregistered = 1;
break;
}
}
usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
if (deregistered) {
unsigned int event_flags;
usbi_mutex_lock(&ctx->event_data_lock);
event_flags = ctx->event_flags;
ctx->event_flags |= USBI_EVENT_HOTPLUG_CB_DEREGISTERED;
if (!event_flags)
usbi_signal_event(&ctx->event);
usbi_mutex_unlock(&ctx->event_data_lock);
}
}
DEFAULT_VISIBILITY
void * LIBUSB_CALL libusb_hotplug_get_user_data(libusb_context *ctx,
libusb_hotplug_callback_handle callback_handle)
{
struct usbi_hotplug_callback *hotplug_cb;
void *user_data = NULL;
/* check for hotplug support */
if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG))
return NULL;
usbi_dbg(ctx, "get hotplug cb %d user data", callback_handle);
ctx = usbi_get_context(ctx);
usbi_mutex_lock(&ctx->hotplug_cbs_lock);
for_each_hotplug_cb(ctx, hotplug_cb) {
if (callback_handle == hotplug_cb->handle) {
user_data = hotplug_cb->user_data;
break;
}
}
usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
return user_data;
}