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