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