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 static 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