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