sys/dev/usb/usb_process.c

   1 /* $FreeBSD$ */
   2 /*-
   3  * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   4  *
   5  * Copyright (c) 2008 Hans Petter Selasky. All rights reserved.
   6  *
   7  * Redistribution and use in source and binary forms, with or without
   8  * modification, are permitted provided that the following conditions
   9  * are met:
  10  * 1. Redistributions of source code must retain the above copyright
  11  *    notice, this list of conditions and the following disclaimer.
  12  * 2. Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26  * SUCH DAMAGE.
  27  */
  28
  29 #ifdef USB_GLOBAL_INCLUDE_FILE
  30 #include USB_GLOBAL_INCLUDE_FILE
  31 #else
  32 #include <sys/stdint.h>
  33 #include <sys/stddef.h>
  34 #include <sys/param.h>
  35 #include <sys/queue.h>
  36 #include <sys/types.h>
  37 #include <sys/systm.h>
  38 #include <sys/kernel.h>
  39 #include <sys/bus.h>
  40 #include <sys/module.h>
  41 #include <sys/lock.h>
  42 #include <sys/mutex.h>
  43 #include <sys/condvar.h>
  44 #include <sys/sysctl.h>
  45 #include <sys/sx.h>
  46 #include <sys/unistd.h>
  47 #include <sys/callout.h>
  48 #include <sys/malloc.h>
  49 #include <sys/priv.h>
  50
  51 #include <dev/usb/usb.h>
  52 #include <dev/usb/usbdi.h>
  53 #include <dev/usb/usbdi_util.h>
  54 #include <dev/usb/usb_process.h>
  55
  56 #define USB_DEBUG_VAR usb_proc_debug
  57 #include <dev/usb/usb_debug.h>
  58 #include <dev/usb/usb_util.h>
  59
  60 #include <sys/proc.h>
  61 #include <sys/kthread.h>
  62 #include <sys/sched.h>
  63 #endif                  /* USB_GLOBAL_INCLUDE_FILE */
  64
  65 #if (__FreeBSD_version < 700000)
  66 #define thread_lock(td) mtx_lock_spin(&sched_lock)
  67 #define thread_unlock(td) mtx_unlock_spin(&sched_lock)
  68 #endif
  69
  70 #if (__FreeBSD_version >= 800000)
  71 static struct proc *usbproc;
  72 static int usb_pcount;
  73 #define USB_THREAD_CREATE(f, s, p, ...) \
  74                 kproc_kthread_add((f), (s), &usbproc, (p), RFHIGHPID, \
  75                     0, "usb", __VA_ARGS__)
  76 #if (__FreeBSD_version >= 900000)
  77 #define USB_THREAD_SUSPEND_CHECK() kthread_suspend_check()
  78 #else
  79 #define USB_THREAD_SUSPEND_CHECK() kthread_suspend_check(curthread)
  80 #endif
  81 #define USB_THREAD_SUSPEND(p)   kthread_suspend(p,0)
  82 #define USB_THREAD_EXIT(err)    kthread_exit()
  83 #else
  84 #define USB_THREAD_CREATE(f, s, p, ...) \
  85                 kthread_create((f), (s), (p), RFHIGHPID, 0, __VA_ARGS__)
  86 #define USB_THREAD_SUSPEND_CHECK() kthread_suspend_check(curproc)
  87 #define USB_THREAD_SUSPEND(p)   kthread_suspend(p,0)
  88 #define USB_THREAD_EXIT(err)    kthread_exit(err)
  89 #endif
  90
  91 #ifdef USB_DEBUG
  92 static int usb_proc_debug;
  93
  94 static SYSCTL_NODE(_hw_usb, OID_AUTO, proc, CTLFLAG_RW | CTLFLAG_MPSAFE, 0,
  95     "USB process");
  96 SYSCTL_INT(_hw_usb_proc, OID_AUTO, debug, CTLFLAG_RWTUN, &usb_proc_debug, 0,
  97     "Debug level");
  98 #endif
  99
 100 /*------------------------------------------------------------------------*
 101  *      usb_process
 102  *
 103  * This function is the USB process dispatcher.
 104  *------------------------------------------------------------------------*/
 105 static void
 106 usb_process(void *arg)
 107 {
 108         struct usb_process *up = arg;
 109         struct usb_proc_msg *pm;
 110         struct thread *td;
 111
 112         /* in case of attach error, check for suspended */
 113         USB_THREAD_SUSPEND_CHECK();
 114
 115         /* adjust priority */
 116         td = curthread;
 117         thread_lock(td);
 118         sched_prio(td, up->up_prio);
 119         thread_unlock(td);
 120
 121         USB_MTX_LOCK(up->up_mtx);
 122
 123         up->up_curtd = td;
 124
 125         while (1) {
 126
 127                 if (up->up_gone)
 128                         break;
 129
 130                 /*
 131                  * NOTE to reimplementors: dequeueing a command from the
 132                  * "used" queue and executing it must be atomic, with regard
 133                  * to the "up_mtx" mutex. That means any attempt to queue a
 134                  * command by another thread must be blocked until either:
 135                  *
 136                  * 1) the command sleeps
 137                  *
 138                  * 2) the command returns
 139                  *
 140                  * Here is a practical example that shows how this helps
 141                  * solving a problem:
 142                  *
 143                  * Assume that you want to set the baud rate on a USB serial
 144                  * device. During the programming of the device you don't
 145                  * want to receive nor transmit any data, because it will be
 146                  * garbage most likely anyway. The programming of our USB
 147                  * device takes 20 milliseconds and it needs to call
 148                  * functions that sleep.
 149                  *
 150                  * Non-working solution: Before we queue the programming
 151                  * command, we stop transmission and reception of data. Then
 152                  * we queue a programming command. At the end of the
 153                  * programming command we enable transmission and reception
 154                  * of data.
 155                  *
 156                  * Problem: If a second programming command is queued while the
 157                  * first one is sleeping, we end up enabling transmission
 158                  * and reception of data too early.
 159                  *
 160                  * Working solution: Before we queue the programming command,
 161                  * we stop transmission and reception of data. Then we queue
 162                  * a programming command. Then we queue a second command
 163                  * that only enables transmission and reception of data.
 164                  *
 165                  * Why it works: If a second programming command is queued
 166                  * while the first one is sleeping, then the queueing of a
 167                  * second command to enable the data transfers, will cause
 168                  * the previous one, which is still on the queue, to be
 169                  * removed from the queue, and re-inserted after the last
 170                  * baud rate programming command, which then gives the
 171                  * desired result.
 172                  */
 173                 pm = TAILQ_FIRST(&up->up_qhead);
 174
 175                 if (pm) {
 176                         DPRINTF("Message pm=%p, cb=%p (enter)\n",
 177                             pm, pm->pm_callback);
 178
 179                         (pm->pm_callback) (pm);
 180
 181                         if (pm == TAILQ_FIRST(&up->up_qhead)) {
 182                                 /* nothing changed */
 183                                 TAILQ_REMOVE(&up->up_qhead, pm, pm_qentry);
 184                                 pm->pm_qentry.tqe_prev = NULL;
 185                         }
 186                         DPRINTF("Message pm=%p (leave)\n", pm);
 187
 188                         continue;
 189                 }
 190                 /* end of messages - check if anyone is waiting for sync */
 191                 if (up->up_dsleep) {
 192                         up->up_dsleep = 0;
 193                         cv_broadcast(&up->up_drain);
 194                 }
 195                 up->up_msleep = 1;
 196                 cv_wait(&up->up_cv, up->up_mtx);
 197         }
 198
 199         up->up_ptr = NULL;
 200         cv_signal(&up->up_cv);
 201         USB_MTX_UNLOCK(up->up_mtx);
 202 #if (__FreeBSD_version >= 800000)
 203         /* Clear the proc pointer if this is the last thread. */
 204         if (--usb_pcount == 0)
 205                 usbproc = NULL;
 206 #endif
 207
 208         USB_THREAD_EXIT(0);
 209 }
 210
 211 /*------------------------------------------------------------------------*
 212  *      usb_proc_create
 213  *
 214  * This function will create a process using the given "prio" that can
 215  * execute callbacks. The mutex pointed to by "p_mtx" will be applied
 216  * before calling the callbacks and released after that the callback
 217  * has returned. The structure pointed to by "up" is assumed to be
 218  * zeroed before this function is called.
 219  *
 220  * Return values:
 221  *    0: success
 222  * Else: failure
 223  *------------------------------------------------------------------------*/
 224 int
 225 usb_proc_create(struct usb_process *up, struct mtx *p_mtx,
 226     const char *pmesg, uint8_t prio)
 227 {
 228         up->up_mtx = p_mtx;
 229         up->up_prio = prio;
 230
 231         TAILQ_INIT(&up->up_qhead);
 232
 233         cv_init(&up->up_cv, "-");
 234         cv_init(&up->up_drain, "usbdrain");
 235
 236         if (USB_THREAD_CREATE(&usb_process, up,
 237             &up->up_ptr, "%s", pmesg)) {
 238                 DPRINTFN(0, "Unable to create USB process.");
 239                 up->up_ptr = NULL;
 240                 goto error;
 241         }
 242 #if (__FreeBSD_version >= 800000)
 243         usb_pcount++;
 244 #endif
 245         return (0);
 246
 247 error:
 248         usb_proc_free(up);
 249         return (ENOMEM);
 250 }
 251
 252 /*------------------------------------------------------------------------*
 253  *      usb_proc_free
 254  *
 255  * NOTE: If the structure pointed to by "up" is all zero, this
 256  * function does nothing.
 257  *
 258  * NOTE: Messages that are pending on the process queue will not be
 259  * removed nor called.
 260  *------------------------------------------------------------------------*/
 261 void
 262 usb_proc_free(struct usb_process *up)
 263 {
 264         /* check if not initialised */
 265         if (up->up_mtx == NULL)
 266                 return;
 267
 268         usb_proc_drain(up);
 269
 270         cv_destroy(&up->up_cv);
 271         cv_destroy(&up->up_drain);
 272
 273         /* make sure that we do not enter here again */
 274         up->up_mtx = NULL;
 275 }
 276
 277 /*------------------------------------------------------------------------*
 278  *      usb_proc_msignal
 279  *
 280  * This function will queue one of the passed USB process messages on
 281  * the USB process queue. The first message that is not already queued
 282  * will get queued. If both messages are already queued the one queued
 283  * last will be removed from the queue and queued in the end. The USB
 284  * process mutex must be locked when calling this function. This
 285  * function exploits the fact that a process can only do one callback
 286  * at a time. The message that was queued is returned.
 287  *------------------------------------------------------------------------*/
 288 void   *
 289 usb_proc_msignal(struct usb_process *up, void *_pm0, void *_pm1)
 290 {
 291         struct usb_proc_msg *pm0 = _pm0;
 292         struct usb_proc_msg *pm1 = _pm1;
 293         struct usb_proc_msg *pm2;
 294         usb_size_t d;
 295         uint8_t t;
 296
 297         /* check if gone or in polling mode, return dummy value */
 298         if (up->up_gone != 0 ||
 299             USB_IN_POLLING_MODE_FUNC() != 0)
 300                 return (_pm0);
 301
 302         USB_MTX_ASSERT(up->up_mtx, MA_OWNED);
 303
 304         t = 0;
 305
 306         if (pm0->pm_qentry.tqe_prev) {
 307                 t |= 1;
 308         }
 309         if (pm1->pm_qentry.tqe_prev) {
 310                 t |= 2;
 311         }
 312         if (t == 0) {
 313                 /*
 314                  * No entries are queued. Queue "pm0" and use the existing
 315                  * message number.
 316                  */
 317                 pm2 = pm0;
 318         } else if (t == 1) {
 319                 /* Check if we need to increment the message number. */
 320                 if (pm0->pm_num == up->up_msg_num) {
 321                         up->up_msg_num++;
 322                 }
 323                 pm2 = pm1;
 324         } else if (t == 2) {
 325                 /* Check if we need to increment the message number. */
 326                 if (pm1->pm_num == up->up_msg_num) {
 327                         up->up_msg_num++;
 328                 }
 329                 pm2 = pm0;
 330         } else if (t == 3) {
 331                 /*
 332                  * Both entries are queued. Re-queue the entry closest to
 333                  * the end.
 334                  */
 335                 d = (pm1->pm_num - pm0->pm_num);
 336
 337                 /* Check sign after subtraction */
 338                 if (d & 0x80000000) {
 339                         pm2 = pm0;
 340                 } else {
 341                         pm2 = pm1;
 342                 }
 343
 344                 TAILQ_REMOVE(&up->up_qhead, pm2, pm_qentry);
 345         } else {
 346                 pm2 = NULL;             /* panic - should not happen */
 347         }
 348
 349         DPRINTF(" t=%u, num=%u\n", t, up->up_msg_num);
 350
 351         /* Put message last on queue */
 352
 353         pm2->pm_num = up->up_msg_num;
 354         TAILQ_INSERT_TAIL(&up->up_qhead, pm2, pm_qentry);
 355
 356         /* Check if we need to wakeup the USB process. */
 357
 358         if (up->up_msleep) {
 359                 up->up_msleep = 0;      /* save "cv_signal()" calls */
 360                 cv_signal(&up->up_cv);
 361         }
 362         return (pm2);
 363 }
 364
 365 /*------------------------------------------------------------------------*
 366  *      usb_proc_is_gone
 367  *
 368  * Return values:
 369  *    0: USB process is running
 370  * Else: USB process is tearing down
 371  *------------------------------------------------------------------------*/
 372 uint8_t
 373 usb_proc_is_gone(struct usb_process *up)
 374 {
 375         if (up->up_gone)
 376                 return (1);
 377
 378         /*
 379          * Allow calls when up_mtx is NULL, before the USB process
 380          * structure is initialised.
 381          */
 382         if (up->up_mtx != NULL)
 383                 USB_MTX_ASSERT(up->up_mtx, MA_OWNED);
 384         return (0);
 385 }
 386
 387 /*------------------------------------------------------------------------*
 388  *      usb_proc_mwait
 389  *
 390  * This function will return when the USB process message pointed to
 391  * by "pm" is no longer on a queue. This function must be called
 392  * having "up->up_mtx" locked.
 393  *------------------------------------------------------------------------*/
 394 void
 395 usb_proc_mwait(struct usb_process *up, void *_pm0, void *_pm1)
 396 {
 397         struct usb_proc_msg *pm0 = _pm0;
 398         struct usb_proc_msg *pm1 = _pm1;
 399
 400         /* check if gone */
 401         if (up->up_gone)
 402                 return;
 403
 404         USB_MTX_ASSERT(up->up_mtx, MA_OWNED);
 405
 406         if (up->up_curtd == curthread) {
 407                 /* Just remove the messages from the queue. */
 408                 if (pm0->pm_qentry.tqe_prev) {
 409                         TAILQ_REMOVE(&up->up_qhead, pm0, pm_qentry);
 410                         pm0->pm_qentry.tqe_prev = NULL;
 411                 }
 412                 if (pm1->pm_qentry.tqe_prev) {
 413                         TAILQ_REMOVE(&up->up_qhead, pm1, pm_qentry);
 414                         pm1->pm_qentry.tqe_prev = NULL;
 415                 }
 416         } else
 417                 while (pm0->pm_qentry.tqe_prev ||
 418                     pm1->pm_qentry.tqe_prev) {
 419                         /* check if config thread is gone */
 420                         if (up->up_gone)
 421                                 break;
 422                         up->up_dsleep = 1;
 423                         cv_wait(&up->up_drain, up->up_mtx);
 424                 }
 425 }
 426
 427 /*------------------------------------------------------------------------*
 428  *      usb_proc_drain
 429  *
 430  * This function will tear down an USB process, waiting for the
 431  * currently executing command to return.
 432  *
 433  * NOTE: If the structure pointed to by "up" is all zero,
 434  * this function does nothing.
 435  *------------------------------------------------------------------------*/
 436 void
 437 usb_proc_drain(struct usb_process *up)
 438 {
 439         /* check if not initialised */
 440         if (up->up_mtx == NULL)
 441                 return;
 442         /* handle special case with Giant */
 443         if (up->up_mtx != &Giant)
 444                 USB_MTX_ASSERT(up->up_mtx, MA_NOTOWNED);
 445
 446         USB_MTX_LOCK(up->up_mtx);
 447
 448         /* Set the gone flag */
 449
 450         up->up_gone = 1;
 451
 452         while (up->up_ptr) {
 453
 454                 /* Check if we need to wakeup the USB process */
 455
 456                 if (up->up_msleep || up->up_csleep) {
 457                         up->up_msleep = 0;
 458                         up->up_csleep = 0;
 459                         cv_signal(&up->up_cv);
 460                 }
 461 #ifndef EARLY_AP_STARTUP
 462                 /* Check if we are still cold booted */
 463                 if (cold) {
 464                         USB_THREAD_SUSPEND(up->up_ptr);
 465                         printf("WARNING: A USB process has "
 466                             "been left suspended\n");
 467                         break;
 468                 }
 469 #endif
 470                 cv_wait(&up->up_cv, up->up_mtx);
 471         }
 472         /* Check if someone is waiting - should not happen */
 473
 474         if (up->up_dsleep) {
 475                 up->up_dsleep = 0;
 476                 cv_broadcast(&up->up_drain);
 477                 DPRINTF("WARNING: Someone is waiting "
 478                     "for USB process drain!\n");
 479         }
 480         USB_MTX_UNLOCK(up->up_mtx);
 481 }
 482
 483 /*------------------------------------------------------------------------*
 484  *      usb_proc_rewakeup
 485  *
 486  * This function is called to re-wakeup the given USB
 487  * process. This usually happens after that the USB system has been in
 488  * polling mode, like during a panic. This function must be called
 489  * having "up->up_mtx" locked.
 490  *------------------------------------------------------------------------*/
 491 void
 492 usb_proc_rewakeup(struct usb_process *up)
 493 {
 494         /* check if not initialised */
 495         if (up->up_mtx == NULL)
 496                 return;
 497         /* check if gone */
 498         if (up->up_gone)
 499                 return;
 500
 501         USB_MTX_ASSERT(up->up_mtx, MA_OWNED);
 502
 503         if (up->up_msleep == 0) {
 504                 /* re-wakeup */
 505                 cv_signal(&up->up_cv);
 506         }
 507 }
 508
 509 /*------------------------------------------------------------------------*
 510  *      usb_proc_is_called_from
 511  *
 512  * This function will return non-zero if called from inside the USB
 513  * process passed as first argument. Else this function returns zero.
 514  *------------------------------------------------------------------------*/
 515 int
 516 usb_proc_is_called_from(struct usb_process *up)
 517 {
 518         return (up->up_curtd == curthread);
 519 }