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