sys/dev/usb/usb_process.c

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