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