libusb/hotplug.c

   1 /* -*- Mode: C; indent-tabs-mode:t ; c-basic-offset:8 -*- */
   2 /*
   3  * Hotplug functions for libusb
   4  * Copyright © 2012-2021 Nathan Hjelm <hjelmn@mac.com>
   5  * Copyright © 2012-2013 Peter Stuge <peter@stuge.se>
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2.1 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public
  18  * License along with this library; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  20  */
  21
  22 #include "libusbi.h"
  23
  24 /**
  25  * @defgroup libusb_hotplug Device hotplug event notification
  26  * This page details how to use the libusb hotplug interface, where available.
  27  *
  28  * Be mindful that not all platforms currently implement hotplug notification and
  29  * that you should first call on \ref libusb_has_capability() with parameter
  30  * \ref LIBUSB_CAP_HAS_HOTPLUG to confirm that hotplug support is available.
  31  *
  32  * \page libusb_hotplug Device hotplug event notification
  33  *
  34  * \section hotplug_intro Introduction
  35  *
  36  * Version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102, has added support
  37  * for hotplug events on <b>some</b> platforms (you should test if your platform
  38  * supports hotplug notification by calling \ref libusb_has_capability() with
  39  * parameter \ref LIBUSB_CAP_HAS_HOTPLUG).
  40  *
  41  * This interface allows you to request notification for the arrival and departure
  42  * of matching USB devices.
  43  *
  44  * To receive hotplug notification you register a callback by calling
  45  * \ref libusb_hotplug_register_callback(). This function will optionally return
  46  * a callback handle that can be passed to \ref libusb_hotplug_deregister_callback().
  47  *
  48  * A callback function must return an int (0 or 1) indicating whether the callback is
  49  * expecting additional events. Returning 0 will rearm the callback and 1 will cause
  50  * the callback to be deregistered. Note that when callbacks are called from
  51  * libusb_hotplug_register_callback() because of the \ref LIBUSB_HOTPLUG_ENUMERATE
  52  * flag, the callback return value is ignored. In other words, you cannot cause a
  53  * callback to be deregistered by returning 1 when it is called from
  54  * libusb_hotplug_register_callback().
  55  *
  56  * Callbacks for a particular context are automatically deregistered by libusb_exit().
  57  *
  58  * As of 1.0.16 there are two supported hotplug events:
  59  *  - LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED: A device has arrived and is ready to use
  60  *  - LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT: A device has left and is no longer available
  61  *
  62  * A hotplug event can listen for either or both of these events.
  63  *
  64  * Note: If you receive notification that a device has left and you have any
  65  * libusb_device_handles for the device it is up to you to call libusb_close()
  66  * on each device handle to free up any remaining resources associated with the device.
  67  * Once a device has left any libusb_device_handle associated with the device
  68  * are invalid and will remain so even if the device comes back.
  69  *
  70  * When handling a LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED event it is considered
  71  * safe to call any libusb function that takes a libusb_device. It also safe to
  72  * open a device and submit asynchronous transfers. However, most other functions
  73  * that take a libusb_device_handle are <b>not</b> safe to call. Examples of such
  74  * functions are any of the \ref libusb_syncio "synchronous API" functions or the blocking
  75  * functions that retrieve various \ref libusb_desc "USB descriptors". These functions must
  76  * be used outside of the context of the hotplug callback.
  77  *
  78  * When handling a LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT event the only safe function
  79  * is libusb_get_device_descriptor().
  80  *
  81  * The following code provides an example of the usage of the hotplug interface:
  82 \code
  83 #include <stdio.h>
  84 #include <stdlib.h>
  85 #include <time.h>
  86 #include <libusb.h>
  87
  88 static int count = 0;
  89
  90 int hotplug_callback(struct libusb_context *ctx, struct libusb_device *dev,
  91                      libusb_hotplug_event event, void *user_data) {
  92   static libusb_device_handle *dev_handle = NULL;
  93   struct libusb_device_descriptor desc;
  94   int rc;
  95
  96   (void)libusb_get_device_descriptor(dev, &desc);
  97
  98   if (LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED == event) {
  99     rc = libusb_open(dev, &dev_handle);
 100     if (LIBUSB_SUCCESS != rc) {
 101       printf("Could not open USB device\n");
 102     }
 103   } else if (LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT == event) {
 104     if (dev_handle) {
 105       libusb_close(dev_handle);
 106       dev_handle = NULL;
 107     }
 108   } else {
 109     printf("Unhandled event %d\n", event);
 110   }
 111   count++;
 112
 113   return 0;
 114 }
 115
 116 int main (void) {
 117   libusb_hotplug_callback_handle callback_handle;
 118   int rc;
 119
 120   libusb_init(NULL);
 121
 122   rc = libusb_hotplug_register_callback(NULL, LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED |
 123                                         LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT, 0, 0x045a, 0x5005,
 124                                         LIBUSB_HOTPLUG_MATCH_ANY, hotplug_callback, NULL,
 125                                         &callback_handle);
 126   if (LIBUSB_SUCCESS != rc) {
 127     printf("Error creating a hotplug callback\n");
 128     libusb_exit(NULL);
 129     return EXIT_FAILURE;
 130   }
 131
 132   while (count < 2) {
 133     libusb_handle_events_completed(NULL, NULL);
 134     nanosleep(&(struct timespec){0, 10000000UL}, NULL);
 135   }
 136
 137   libusb_hotplug_deregister_callback(NULL, callback_handle);
 138   libusb_exit(NULL);
 139
 140   return 0;
 141 }
 142 \endcode
 143  */
 144
 145 #define VALID_HOTPLUG_EVENTS                    \
 146         (LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED |  \
 147          LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT)
 148
 149 #define VALID_HOTPLUG_FLAGS                     \
 150         (LIBUSB_HOTPLUG_ENUMERATE)
 151
 152 void usbi_hotplug_init(struct libusb_context *ctx)
 153 {
 154         /* check for hotplug support */
 155         if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG))
 156                 return;
 157
 158         usbi_mutex_init(&ctx->hotplug_cbs_lock);
 159         list_init(&ctx->hotplug_cbs);
 160         ctx->next_hotplug_cb_handle = 1;
 161         usbi_atomic_store(&ctx->hotplug_ready, 1);
 162 }
 163
 164 void usbi_hotplug_exit(struct libusb_context *ctx)
 165 {
 166         struct usbi_hotplug_callback *hotplug_cb, *next_cb;
 167         struct usbi_hotplug_message *msg;
 168         struct libusb_device *dev, *next_dev;
 169
 170         /* check for hotplug support */
 171         if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG))
 172                 return;
 173
 174         if (!usbi_atomic_load(&ctx->hotplug_ready))
 175                 return;
 176
 177         /* free all registered hotplug callbacks */
 178         for_each_hotplug_cb_safe(ctx, hotplug_cb, next_cb) {
 179                 list_del(&hotplug_cb->list);
 180                 free(hotplug_cb);
 181         }
 182
 183         /* free all pending hotplug messages */
 184         while (!list_empty(&ctx->hotplug_msgs)) {
 185                 msg = list_first_entry(&ctx->hotplug_msgs, struct usbi_hotplug_message, list);
 186
 187                 /* if the device left, the message holds a reference
 188                  * and we must drop it */
 189                 if (msg->event == LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT)
 190                         libusb_unref_device(msg->device);
 191
 192                 list_del(&msg->list);
 193                 free(msg);
 194         }
 195
 196         /* free all discovered devices. due to parent references loop until no devices are freed. */
 197         for_each_device_safe(ctx, dev, next_dev) {
 198                 /* remove the device from the usb_devs list only if there are no
 199                  * references held, otherwise leave it on the list so that a
 200                  * warning message will be shown */
 201                 if (usbi_atomic_load(&dev->refcnt) == 1) {
 202                         list_del(&dev->list);
 203                 }
 204                 if (dev->parent_dev && usbi_atomic_load(&dev->parent_dev->refcnt) == 1) {
 205                         /* the parent was before this device in the list and will be released.
 206                            remove it from the list. this is safe as parent_dev can not be
 207                            equal to next_dev. */
 208                         assert (dev->parent_dev != next_dev);
 209                         list_del(&dev->parent_dev->list);
 210                 }
 211                 libusb_unref_device(dev);
 212         }
 213
 214         usbi_mutex_destroy(&ctx->hotplug_cbs_lock);
 215 }
 216
 217 static int usbi_hotplug_match_cb(struct libusb_device *dev,
 218         libusb_hotplug_event event, struct usbi_hotplug_callback *hotplug_cb)
 219 {
 220         if (!(hotplug_cb->flags & event)) {
 221                 return 0;
 222         }
 223
 224         if ((hotplug_cb->flags & USBI_HOTPLUG_VENDOR_ID_VALID) &&
 225             hotplug_cb->vendor_id != dev->device_descriptor.idVendor) {
 226                 return 0;
 227         }
 228
 229         if ((hotplug_cb->flags & USBI_HOTPLUG_PRODUCT_ID_VALID) &&
 230             hotplug_cb->product_id != dev->device_descriptor.idProduct) {
 231                 return 0;
 232         }
 233
 234         if ((hotplug_cb->flags & USBI_HOTPLUG_DEV_CLASS_VALID) &&
 235             hotplug_cb->dev_class != dev->device_descriptor.bDeviceClass) {
 236                 return 0;
 237         }
 238
 239         return hotplug_cb->cb(DEVICE_CTX(dev), dev, event, hotplug_cb->user_data);
 240 }
 241
 242 void usbi_hotplug_notification(struct libusb_context *ctx, struct libusb_device *dev,
 243         libusb_hotplug_event event)
 244 {
 245         struct usbi_hotplug_message *msg;
 246         unsigned int event_flags;
 247
 248         /* Only generate a notification if hotplug is ready. This prevents hotplug
 249          * notifications from being generated during initial enumeration or if the
 250          * backend does not support hotplug. */
 251         if (!usbi_atomic_load(&ctx->hotplug_ready))
 252                 return;
 253
 254         msg = calloc(1, sizeof(*msg));
 255         if (!msg) {
 256                 usbi_err(ctx, "error allocating hotplug message");
 257                 return;
 258         }
 259
 260         msg->event = event;
 261         msg->device = dev;
 262
 263         /* Take the event data lock and add this message to the list.
 264          * Only signal an event if there are no prior pending events. */
 265         usbi_mutex_lock(&ctx->event_data_lock);
 266         event_flags = ctx->event_flags;
 267         ctx->event_flags |= USBI_EVENT_HOTPLUG_MSG_PENDING;
 268         list_add_tail(&msg->list, &ctx->hotplug_msgs);
 269         if (!event_flags)
 270                 usbi_signal_event(&ctx->event);
 271         usbi_mutex_unlock(&ctx->event_data_lock);
 272 }
 273
 274 void usbi_hotplug_process(struct libusb_context *ctx, struct list_head *hotplug_msgs)
 275 {
 276         struct usbi_hotplug_callback *hotplug_cb, *next_cb;
 277         struct usbi_hotplug_message *msg;
 278         int r;
 279
 280         usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 281
 282         /* dispatch all pending hotplug messages */
 283         while (!list_empty(hotplug_msgs)) {
 284                 msg = list_first_entry(hotplug_msgs, struct usbi_hotplug_message, list);
 285
 286                 for_each_hotplug_cb_safe(ctx, hotplug_cb, next_cb) {
 287                         /* skip callbacks that have unregistered */
 288                         if (hotplug_cb->flags & USBI_HOTPLUG_NEEDS_FREE)
 289                                 continue;
 290
 291                         usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 292                         r = usbi_hotplug_match_cb(msg->device, msg->event, hotplug_cb);
 293                         usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 294
 295                         if (r) {
 296                                 list_del(&hotplug_cb->list);
 297                                 free(hotplug_cb);
 298                         }
 299                 }
 300
 301                 /* if the device left, the message holds a reference
 302                  * and we must drop it */
 303                 if (msg->event == LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT)
 304                         libusb_unref_device(msg->device);
 305
 306                 list_del(&msg->list);
 307                 free(msg);
 308         }
 309
 310         /* free any callbacks that have unregistered */
 311         for_each_hotplug_cb_safe(ctx, hotplug_cb, next_cb) {
 312                 if (hotplug_cb->flags & USBI_HOTPLUG_NEEDS_FREE) {
 313                         usbi_dbg(ctx, "freeing hotplug cb %p with handle %d",
 314                                 hotplug_cb, hotplug_cb->handle);
 315                         list_del(&hotplug_cb->list);
 316                         free(hotplug_cb);
 317                 }
 318         }
 319
 320         usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 321 }
 322
 323 int API_EXPORTED libusb_hotplug_register_callback(libusb_context *ctx,
 324         int events, int flags,
 325         int vendor_id, int product_id, int dev_class,
 326         libusb_hotplug_callback_fn cb_fn, void *user_data,
 327         libusb_hotplug_callback_handle *callback_handle)
 328 {
 329         struct usbi_hotplug_callback *hotplug_cb;
 330
 331         /* check for sane values */
 332         if (!events || (~VALID_HOTPLUG_EVENTS & events) ||
 333             (~VALID_HOTPLUG_FLAGS & flags) ||
 334             (LIBUSB_HOTPLUG_MATCH_ANY != vendor_id && (~0xffff & vendor_id)) ||
 335             (LIBUSB_HOTPLUG_MATCH_ANY != product_id && (~0xffff & product_id)) ||
 336             (LIBUSB_HOTPLUG_MATCH_ANY != dev_class && (~0xff & dev_class)) ||
 337             !cb_fn) {
 338                 return LIBUSB_ERROR_INVALID_PARAM;
 339         }
 340
 341         /* check for hotplug support */
 342         if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG))
 343                 return LIBUSB_ERROR_NOT_SUPPORTED;
 344
 345         ctx = usbi_get_context(ctx);
 346
 347         hotplug_cb = calloc(1, sizeof(*hotplug_cb));
 348         if (!hotplug_cb)
 349                 return LIBUSB_ERROR_NO_MEM;
 350
 351         hotplug_cb->flags = (uint8_t)events;
 352         if (LIBUSB_HOTPLUG_MATCH_ANY != vendor_id) {
 353                 hotplug_cb->flags |= USBI_HOTPLUG_VENDOR_ID_VALID;
 354                 hotplug_cb->vendor_id = (uint16_t)vendor_id;
 355         }
 356         if (LIBUSB_HOTPLUG_MATCH_ANY != product_id) {
 357                 hotplug_cb->flags |= USBI_HOTPLUG_PRODUCT_ID_VALID;
 358                 hotplug_cb->product_id = (uint16_t)product_id;
 359         }
 360         if (LIBUSB_HOTPLUG_MATCH_ANY != dev_class) {
 361                 hotplug_cb->flags |= USBI_HOTPLUG_DEV_CLASS_VALID;
 362                 hotplug_cb->dev_class = (uint8_t)dev_class;
 363         }
 364         hotplug_cb->cb = cb_fn;
 365         hotplug_cb->user_data = user_data;
 366
 367         usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 368
 369         /* protect the handle by the context hotplug lock */
 370         hotplug_cb->handle = ctx->next_hotplug_cb_handle++;
 371
 372         /* handle the unlikely case of overflow */
 373         if (ctx->next_hotplug_cb_handle < 0)
 374                 ctx->next_hotplug_cb_handle = 1;
 375
 376         list_add(&hotplug_cb->list, &ctx->hotplug_cbs);
 377
 378         usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 379
 380         usbi_dbg(ctx, "new hotplug cb %p with handle %d", hotplug_cb, hotplug_cb->handle);
 381
 382         if ((flags & LIBUSB_HOTPLUG_ENUMERATE) && (events & LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED)) {
 383                 ssize_t i, len;
 384                 struct libusb_device **devs;
 385
 386                 len = libusb_get_device_list(ctx, &devs);
 387                 if (len < 0) {
 388                         libusb_hotplug_deregister_callback(ctx, hotplug_cb->handle);
 389                         return (int)len;
 390                 }
 391
 392                 for (i = 0; i < len; i++) {
 393                         usbi_hotplug_match_cb(devs[i],
 394                                         LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED,
 395                                         hotplug_cb);
 396                 }
 397
 398                 libusb_free_device_list(devs, 1);
 399         }
 400
 401         if (callback_handle)
 402                 *callback_handle = hotplug_cb->handle;
 403
 404         return LIBUSB_SUCCESS;
 405 }
 406
 407 void API_EXPORTED libusb_hotplug_deregister_callback(libusb_context *ctx,
 408         libusb_hotplug_callback_handle callback_handle)
 409 {
 410         struct usbi_hotplug_callback *hotplug_cb;
 411         int deregistered = 0;
 412
 413         /* check for hotplug support */
 414         if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG))
 415                 return;
 416
 417         usbi_dbg(ctx, "deregister hotplug cb %d", callback_handle);
 418
 419         ctx = usbi_get_context(ctx);
 420
 421         usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 422         for_each_hotplug_cb(ctx, hotplug_cb) {
 423                 if (callback_handle == hotplug_cb->handle) {
 424                         /* mark this callback for deregistration */
 425                         hotplug_cb->flags |= USBI_HOTPLUG_NEEDS_FREE;
 426                         deregistered = 1;
 427                         break;
 428                 }
 429         }
 430         usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 431
 432         if (deregistered) {
 433                 unsigned int event_flags;
 434
 435                 usbi_mutex_lock(&ctx->event_data_lock);
 436                 event_flags = ctx->event_flags;
 437                 ctx->event_flags |= USBI_EVENT_HOTPLUG_CB_DEREGISTERED;
 438                 if (!event_flags)
 439                         usbi_signal_event(&ctx->event);
 440                 usbi_mutex_unlock(&ctx->event_data_lock);
 441         }
 442 }
 443
 444 DEFAULT_VISIBILITY
 445 void * LIBUSB_CALL libusb_hotplug_get_user_data(libusb_context *ctx,
 446         libusb_hotplug_callback_handle callback_handle)
 447 {
 448         struct usbi_hotplug_callback *hotplug_cb;
 449         void *user_data = NULL;
 450
 451         /* check for hotplug support */
 452         if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG))
 453                 return NULL;
 454
 455         usbi_dbg(ctx, "get hotplug cb %d user data", callback_handle);
 456
 457         ctx = usbi_get_context(ctx);
 458
 459         usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 460         for_each_hotplug_cb(ctx, hotplug_cb) {
 461                 if (callback_handle == hotplug_cb->handle) {
 462                         user_data = hotplug_cb->user_data;
 463                         break;
 464                 }
 465         }
 466         usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 467
 468         return user_data;
 469 }