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 usb2_proc_debug
  28
  29 #include <dev/usb/usb_core.h>
  30 #include <dev/usb/usb_process.h>
  31 #include <dev/usb/usb_debug.h>
  32 #include <dev/usb/usb_util.h>
  33
  34 #include <sys/proc.h>
  35 #include <sys/kthread.h>
  36 #include <sys/sched.h>
  37
  38 #if (__FreeBSD_version < 700000)
  39 #define thread_lock(td) mtx_lock_spin(&sched_lock)
  40 #define thread_unlock(td) mtx_unlock_spin(&sched_lock)
  41 #endif
  42
  43 #if (__FreeBSD_version >= 800000)
  44 #define USB_THREAD_CREATE(f, s, p, ...) \
  45                 kproc_create((f), (s), (p), RFHIGHPID, 0, __VA_ARGS__)
  46 #define USB_THREAD_SUSPEND(p)   kproc_suspend(p,0)
  47 #define USB_THREAD_EXIT(err)    kproc_exit(err)
  48 #else
  49 #define USB_THREAD_CREATE(f, s, p, ...) \
  50                 kthread_create((f), (s), (p), RFHIGHPID, 0, __VA_ARGS__)
  51 #define USB_THREAD_SUSPEND(p)   kthread_suspend(p,0)
  52 #define USB_THREAD_EXIT(err)    kthread_exit(err)
  53 #endif
  54
  55 #if USB_DEBUG
  56 static int usb2_proc_debug;
  57
  58 SYSCTL_NODE(_hw_usb, OID_AUTO, proc, CTLFLAG_RW, 0, "USB process");
  59 SYSCTL_INT(_hw_usb_proc, OID_AUTO, debug, CTLFLAG_RW, &usb2_proc_debug, 0,
  60     "Debug level");
  61 #endif
  62
  63 /*------------------------------------------------------------------------*
  64  *      usb2_process
  65  *
  66  * This function is the USB process dispatcher.
  67  *------------------------------------------------------------------------*/
  68 static void
  69 usb2_process(void *arg)
  70 {
  71         struct usb2_process *up = arg;
  72         struct usb2_proc_msg *pm;
  73         struct thread *td;
  74
  75         /* adjust priority */
  76         td = curthread;
  77         thread_lock(td);
  78         sched_prio(td, up->up_prio);
  79         thread_unlock(td);
  80
  81         mtx_lock(up->up_mtx);
  82
  83         up->up_curtd = td;
  84
  85         while (1) {
  86
  87                 if (up->up_gone)
  88                         break;
  89
  90                 /*
  91                  * NOTE to reimplementors: dequeueing a command from the
  92                  * "used" queue and executing it must be atomic, with regard
  93                  * to the "up_mtx" mutex. That means any attempt to queue a
  94                  * command by another thread must be blocked until either:
  95                  *
  96                  * 1) the command sleeps
  97                  *
  98                  * 2) the command returns
  99                  *
 100                  * Here is a practical example that shows how this helps
 101                  * solving a problem:
 102                  *
 103                  * Assume that you want to set the baud rate on a USB serial
 104                  * device. During the programming of the device you don't
 105                  * want to receive nor transmit any data, because it will be
 106                  * garbage most likely anyway. The programming of our USB
 107                  * device takes 20 milliseconds and it needs to call
 108                  * functions that sleep.
 109                  *
 110                  * Non-working solution: Before we queue the programming
 111                  * command, we stop transmission and reception of data. Then
 112                  * we queue a programming command. At the end of the
 113                  * programming command we enable transmission and reception
 114                  * of data.
 115                  *
 116                  * Problem: If a second programming command is queued while the
 117                  * first one is sleeping, we end up enabling transmission
 118                  * and reception of data too early.
 119                  *
 120                  * Working solution: Before we queue the programming command,
 121                  * we stop transmission and reception of data. Then we queue
 122                  * a programming command. Then we queue a second command
 123                  * that only enables transmission and reception of data.
 124                  *
 125                  * Why it works: If a second programming command is queued
 126                  * while the first one is sleeping, then the queueing of a
 127                  * second command to enable the data transfers, will cause
 128                  * the previous one, which is still on the queue, to be
 129                  * removed from the queue, and re-inserted after the last
 130                  * baud rate programming command, which then gives the
 131                  * desired result.
 132                  */
 133                 pm = TAILQ_FIRST(&up->up_qhead);
 134
 135                 if (pm) {
 136                         DPRINTF("Message pm=%p, cb=%p (enter)\n",
 137                             pm, pm->pm_callback);
 138
 139                         (pm->pm_callback) (pm);
 140
 141                         if (pm == TAILQ_FIRST(&up->up_qhead)) {
 142                                 /* nothing changed */
 143                                 TAILQ_REMOVE(&up->up_qhead, pm, pm_qentry);
 144                                 pm->pm_qentry.tqe_prev = NULL;
 145                         }
 146                         DPRINTF("Message pm=%p (leave)\n", pm);
 147
 148                         continue;
 149                 }
 150                 /* end if messages - check if anyone is waiting for sync */
 151                 if (up->up_dsleep) {
 152                         up->up_dsleep = 0;
 153                         usb2_cv_broadcast(&up->up_drain);
 154                 }
 155                 up->up_msleep = 1;
 156                 usb2_cv_wait(&up->up_cv, up->up_mtx);
 157         }
 158
 159         up->up_ptr = NULL;
 160         usb2_cv_signal(&up->up_cv);
 161         mtx_unlock(up->up_mtx);
 162
 163         USB_THREAD_EXIT(0);
 164 }
 165
 166 /*------------------------------------------------------------------------*
 167  *      usb2_proc_create
 168  *
 169  * This function will create a process using the given "prio" that can
 170  * execute callbacks. The mutex pointed to by "p_mtx" will be applied
 171  * before calling the callbacks and released after that the callback
 172  * has returned. The structure pointed to by "up" is assumed to be
 173  * zeroed before this function is called.
 174  *
 175  * Return values:
 176  *    0: success
 177  * Else: failure
 178  *------------------------------------------------------------------------*/
 179 int
 180 usb2_proc_create(struct usb2_process *up, struct mtx *p_mtx,
 181     const char *pmesg, uint8_t prio)
 182 {
 183         up->up_mtx = p_mtx;
 184         up->up_prio = prio;
 185
 186         TAILQ_INIT(&up->up_qhead);
 187
 188         usb2_cv_init(&up->up_cv, "wmsg");
 189         usb2_cv_init(&up->up_drain, "dmsg");
 190
 191         if (USB_THREAD_CREATE(&usb2_process, up,
 192             &up->up_ptr, pmesg)) {
 193                 DPRINTFN(0, "Unable to create USB process.");
 194                 up->up_ptr = NULL;
 195                 goto error;
 196         }
 197         return (0);
 198
 199 error:
 200         usb2_proc_free(up);
 201         return (ENOMEM);
 202 }
 203
 204 /*------------------------------------------------------------------------*
 205  *      usb2_proc_free
 206  *
 207  * NOTE: If the structure pointed to by "up" is all zero, this
 208  * function does nothing.
 209  *
 210  * NOTE: Messages that are pending on the process queue will not be
 211  * removed nor called.
 212  *------------------------------------------------------------------------*/
 213 void
 214 usb2_proc_free(struct usb2_process *up)
 215 {
 216         /* check if not initialised */
 217         if (up->up_mtx == NULL)
 218                 return;
 219
 220         usb2_proc_drain(up);
 221
 222         usb2_cv_destroy(&up->up_cv);
 223         usb2_cv_destroy(&up->up_drain);
 224
 225         /* make sure that we do not enter here again */
 226         up->up_mtx = NULL;
 227 }
 228
 229 /*------------------------------------------------------------------------*
 230  *      usb2_proc_msignal
 231  *
 232  * This function will queue one of the passed USB process messages on
 233  * the USB process queue. The first message that is not already queued
 234  * will get queued. If both messages are already queued the one queued
 235  * last will be removed from the queue and queued in the end. The USB
 236  * process mutex must be locked when calling this function. This
 237  * function exploits the fact that a process can only do one callback
 238  * at a time. The message that was queued is returned.
 239  *------------------------------------------------------------------------*/
 240 void   *
 241 usb2_proc_msignal(struct usb2_process *up, void *_pm0, void *_pm1)
 242 {
 243         struct usb2_proc_msg *pm0 = _pm0;
 244         struct usb2_proc_msg *pm1 = _pm1;
 245         struct usb2_proc_msg *pm2;
 246         usb2_size_t d;
 247         uint8_t t;
 248
 249         /* check if gone, return dummy value */
 250         if (up->up_gone)
 251                 return (_pm0);
 252
 253         mtx_assert(up->up_mtx, MA_OWNED);
 254
 255         t = 0;
 256
 257         if (pm0->pm_qentry.tqe_prev) {
 258                 t |= 1;
 259         }
 260         if (pm1->pm_qentry.tqe_prev) {
 261                 t |= 2;
 262         }
 263         if (t == 0) {
 264                 /*
 265                  * No entries are queued. Queue "pm0" and use the existing
 266                  * message number.
 267                  */
 268                 pm2 = pm0;
 269         } else if (t == 1) {
 270                 /* Check if we need to increment the message number. */
 271                 if (pm0->pm_num == up->up_msg_num) {
 272                         up->up_msg_num++;
 273                 }
 274                 pm2 = pm1;
 275         } else if (t == 2) {
 276                 /* Check if we need to increment the message number. */
 277                 if (pm1->pm_num == up->up_msg_num) {
 278                         up->up_msg_num++;
 279                 }
 280                 pm2 = pm0;
 281         } else if (t == 3) {
 282                 /*
 283                  * Both entries are queued. Re-queue the entry closest to
 284                  * the end.
 285                  */
 286                 d = (pm1->pm_num - pm0->pm_num);
 287
 288                 /* Check sign after subtraction */
 289                 if (d & 0x80000000) {
 290                         pm2 = pm0;
 291                 } else {
 292                         pm2 = pm1;
 293                 }
 294
 295                 TAILQ_REMOVE(&up->up_qhead, pm2, pm_qentry);
 296         } else {
 297                 pm2 = NULL;             /* panic - should not happen */
 298         }
 299
 300         DPRINTF(" t=%u, num=%u\n", t, up->up_msg_num);
 301
 302         /* Put message last on queue */
 303
 304         pm2->pm_num = up->up_msg_num;
 305         TAILQ_INSERT_TAIL(&up->up_qhead, pm2, pm_qentry);
 306
 307         /* Check if we need to wakeup the USB process. */
 308
 309         if (up->up_msleep) {
 310                 up->up_msleep = 0;      /* save "cv_signal()" calls */
 311                 usb2_cv_signal(&up->up_cv);
 312         }
 313         return (pm2);
 314 }
 315
 316 /*------------------------------------------------------------------------*
 317  *      usb2_proc_is_gone
 318  *
 319  * Return values:
 320  *    0: USB process is running
 321  * Else: USB process is tearing down
 322  *------------------------------------------------------------------------*/
 323 uint8_t
 324 usb2_proc_is_gone(struct usb2_process *up)
 325 {
 326         if (up->up_gone)
 327                 return (1);
 328
 329         mtx_assert(up->up_mtx, MA_OWNED);
 330         return (0);
 331 }
 332
 333 /*------------------------------------------------------------------------*
 334  *      usb2_proc_mwait
 335  *
 336  * This function will return when the USB process message pointed to
 337  * by "pm" is no longer on a queue. This function must be called
 338  * having "up->up_mtx" locked.
 339  *------------------------------------------------------------------------*/
 340 void
 341 usb2_proc_mwait(struct usb2_process *up, void *_pm0, void *_pm1)
 342 {
 343         struct usb2_proc_msg *pm0 = _pm0;
 344         struct usb2_proc_msg *pm1 = _pm1;
 345
 346         /* check if gone */
 347         if (up->up_gone)
 348                 return;
 349
 350         mtx_assert(up->up_mtx, MA_OWNED);
 351
 352         if (up->up_curtd == curthread) {
 353                 /* Just remove the messages from the queue. */
 354                 if (pm0->pm_qentry.tqe_prev) {
 355                         TAILQ_REMOVE(&up->up_qhead, pm0, pm_qentry);
 356                         pm0->pm_qentry.tqe_prev = NULL;
 357                 }
 358                 if (pm1->pm_qentry.tqe_prev) {
 359                         TAILQ_REMOVE(&up->up_qhead, pm1, pm_qentry);
 360                         pm1->pm_qentry.tqe_prev = NULL;
 361                 }
 362         } else
 363                 while (pm0->pm_qentry.tqe_prev ||
 364                     pm1->pm_qentry.tqe_prev) {
 365                         /* check if config thread is gone */
 366                         if (up->up_gone)
 367                                 break;
 368                         up->up_dsleep = 1;
 369                         usb2_cv_wait(&up->up_drain, up->up_mtx);
 370                 }
 371 }
 372
 373 /*------------------------------------------------------------------------*
 374  *      usb2_proc_drain
 375  *
 376  * This function will tear down an USB process, waiting for the
 377  * currently executing command to return.
 378  *
 379  * NOTE: If the structure pointed to by "up" is all zero,
 380  * this function does nothing.
 381  *------------------------------------------------------------------------*/
 382 void
 383 usb2_proc_drain(struct usb2_process *up)
 384 {
 385         /* check if not initialised */
 386         if (up->up_mtx == NULL)
 387                 return;
 388         /* handle special case with Giant */
 389         if (up->up_mtx != &Giant)
 390                 mtx_assert(up->up_mtx, MA_NOTOWNED);
 391
 392         mtx_lock(up->up_mtx);
 393
 394         /* Set the gone flag */
 395
 396         up->up_gone = 1;
 397
 398         while (up->up_ptr) {
 399
 400                 /* Check if we need to wakeup the USB process */
 401
 402                 if (up->up_msleep || up->up_csleep) {
 403                         up->up_msleep = 0;
 404                         up->up_csleep = 0;
 405                         usb2_cv_signal(&up->up_cv);
 406                 }
 407                 /* Check if we are still cold booted */
 408
 409                 if (cold) {
 410                         USB_THREAD_SUSPEND(up->up_ptr);
 411                         printf("WARNING: A USB process has "
 412                             "been left suspended!\n");
 413                         break;
 414                 }
 415                 usb2_cv_wait(&up->up_cv, up->up_mtx);
 416         }
 417         /* Check if someone is waiting - should not happen */
 418
 419         if (up->up_dsleep) {
 420                 up->up_dsleep = 0;
 421                 usb2_cv_broadcast(&up->up_drain);
 422                 DPRINTF("WARNING: Someone is waiting "
 423                     "for USB process drain!\n");
 424         }
 425         mtx_unlock(up->up_mtx);
 426 }