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