3 * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
5 * Copyright (c) 2008 Hans Petter Selasky. All rights reserved.
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
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.
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
29 #ifdef USB_GLOBAL_INCLUDE_FILE
30 #include USB_GLOBAL_INCLUDE_FILE
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>
40 #include <sys/module.h>
42 #include <sys/mutex.h>
43 #include <sys/condvar.h>
44 #include <sys/sysctl.h>
46 #include <sys/unistd.h>
47 #include <sys/callout.h>
48 #include <sys/malloc.h>
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>
56 #define USB_DEBUG_VAR usb_proc_debug
57 #include <dev/usb/usb_debug.h>
58 #include <dev/usb/usb_util.h>
61 #include <sys/kthread.h>
62 #include <sys/sched.h>
63 #endif /* USB_GLOBAL_INCLUDE_FILE */
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)
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()
79 #define USB_THREAD_SUSPEND_CHECK() kthread_suspend_check(curthread)
81 #define USB_THREAD_SUSPEND(p) kthread_suspend(p,0)
82 #define USB_THREAD_EXIT(err) kthread_exit()
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)
92 static int usb_proc_debug;
94 static SYSCTL_NODE(_hw_usb, OID_AUTO, proc, CTLFLAG_RW | CTLFLAG_MPSAFE, 0,
96 SYSCTL_INT(_hw_usb_proc, OID_AUTO, debug, CTLFLAG_RWTUN, &usb_proc_debug, 0,
100 /*------------------------------------------------------------------------*
103 * This function is the USB process dispatcher.
104 *------------------------------------------------------------------------*/
106 usb_process(void *arg)
108 struct usb_process *up = arg;
109 struct usb_proc_msg *pm;
112 /* in case of attach error, check for suspended */
113 USB_THREAD_SUSPEND_CHECK();
115 /* adjust priority */
118 sched_prio(td, up->up_prio);
121 USB_MTX_LOCK(up->up_mtx);
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:
136 * 1) the command sleeps
138 * 2) the command returns
140 * Here is a practical example that shows how this helps
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.
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
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.
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.
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
173 pm = TAILQ_FIRST(&up->up_qhead);
176 DPRINTF("Message pm=%p, cb=%p (enter)\n",
177 pm, pm->pm_callback);
179 (pm->pm_callback) (pm);
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;
186 DPRINTF("Message pm=%p (leave)\n", pm);
190 /* end of messages - check if anyone is waiting for sync */
193 cv_broadcast(&up->up_drain);
196 cv_wait(&up->up_cv, up->up_mtx);
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)
211 /*------------------------------------------------------------------------*
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.
223 *------------------------------------------------------------------------*/
225 usb_proc_create(struct usb_process *up, struct mtx *p_mtx,
226 const char *pmesg, uint8_t prio)
231 TAILQ_INIT(&up->up_qhead);
233 cv_init(&up->up_cv, "-");
234 cv_init(&up->up_drain, "usbdrain");
236 if (USB_THREAD_CREATE(&usb_process, up,
237 &up->up_ptr, "%s", pmesg)) {
238 DPRINTFN(0, "Unable to create USB process.");
242 #if (__FreeBSD_version >= 800000)
252 /*------------------------------------------------------------------------*
255 * NOTE: If the structure pointed to by "up" is all zero, this
256 * function does nothing.
258 * NOTE: Messages that are pending on the process queue will not be
259 * removed nor called.
260 *------------------------------------------------------------------------*/
262 usb_proc_free(struct usb_process *up)
264 /* check if not initialised */
265 if (up->up_mtx == NULL)
270 cv_destroy(&up->up_cv);
271 cv_destroy(&up->up_drain);
273 /* make sure that we do not enter here again */
277 /*------------------------------------------------------------------------*
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 *------------------------------------------------------------------------*/
289 usb_proc_msignal(struct usb_process *up, void *_pm0, void *_pm1)
291 struct usb_proc_msg *pm0 = _pm0;
292 struct usb_proc_msg *pm1 = _pm1;
293 struct usb_proc_msg *pm2;
297 /* check if gone or in polling mode, return dummy value */
298 if (up->up_gone != 0 ||
299 USB_IN_POLLING_MODE_FUNC() != 0)
302 USB_MTX_ASSERT(up->up_mtx, MA_OWNED);
306 if (pm0->pm_qentry.tqe_prev) {
309 if (pm1->pm_qentry.tqe_prev) {
314 * No entries are queued. Queue "pm0" and use the existing
319 /* Check if we need to increment the message number. */
320 if (pm0->pm_num == up->up_msg_num) {
325 /* Check if we need to increment the message number. */
326 if (pm1->pm_num == up->up_msg_num) {
332 * Both entries are queued. Re-queue the entry closest to
335 d = (pm1->pm_num - pm0->pm_num);
337 /* Check sign after subtraction */
338 if (d & 0x80000000) {
344 TAILQ_REMOVE(&up->up_qhead, pm2, pm_qentry);
346 pm2 = NULL; /* panic - should not happen */
349 DPRINTF(" t=%u, num=%u\n", t, up->up_msg_num);
351 /* Put message last on queue */
353 pm2->pm_num = up->up_msg_num;
354 TAILQ_INSERT_TAIL(&up->up_qhead, pm2, pm_qentry);
356 /* Check if we need to wakeup the USB process. */
359 up->up_msleep = 0; /* save "cv_signal()" calls */
360 cv_signal(&up->up_cv);
365 /*------------------------------------------------------------------------*
369 * 0: USB process is running
370 * Else: USB process is tearing down
371 *------------------------------------------------------------------------*/
373 usb_proc_is_gone(struct usb_process *up)
379 * Allow calls when up_mtx is NULL, before the USB process
380 * structure is initialised.
382 if (up->up_mtx != NULL)
383 USB_MTX_ASSERT(up->up_mtx, MA_OWNED);
387 /*------------------------------------------------------------------------*
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 *------------------------------------------------------------------------*/
395 usb_proc_mwait(struct usb_process *up, void *_pm0, void *_pm1)
397 struct usb_proc_msg *pm0 = _pm0;
398 struct usb_proc_msg *pm1 = _pm1;
404 USB_MTX_ASSERT(up->up_mtx, MA_OWNED);
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;
412 if (pm1->pm_qentry.tqe_prev) {
413 TAILQ_REMOVE(&up->up_qhead, pm1, pm_qentry);
414 pm1->pm_qentry.tqe_prev = NULL;
417 while (pm0->pm_qentry.tqe_prev ||
418 pm1->pm_qentry.tqe_prev) {
419 /* check if config thread is gone */
423 cv_wait(&up->up_drain, up->up_mtx);
427 /*------------------------------------------------------------------------*
430 * This function will tear down an USB process, waiting for the
431 * currently executing command to return.
433 * NOTE: If the structure pointed to by "up" is all zero,
434 * this function does nothing.
435 *------------------------------------------------------------------------*/
437 usb_proc_drain(struct usb_process *up)
439 /* check if not initialised */
440 if (up->up_mtx == NULL)
442 /* handle special case with Giant */
443 if (up->up_mtx != &Giant)
444 USB_MTX_ASSERT(up->up_mtx, MA_NOTOWNED);
446 USB_MTX_LOCK(up->up_mtx);
448 /* Set the gone flag */
454 /* Check if we need to wakeup the USB process */
456 if (up->up_msleep || up->up_csleep) {
459 cv_signal(&up->up_cv);
461 #ifndef EARLY_AP_STARTUP
462 /* Check if we are still cold booted */
464 USB_THREAD_SUSPEND(up->up_ptr);
465 printf("WARNING: A USB process has "
466 "been left suspended\n");
470 cv_wait(&up->up_cv, up->up_mtx);
472 /* Check if someone is waiting - should not happen */
476 cv_broadcast(&up->up_drain);
477 DPRINTF("WARNING: Someone is waiting "
478 "for USB process drain!\n");
480 USB_MTX_UNLOCK(up->up_mtx);
483 /*------------------------------------------------------------------------*
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 *------------------------------------------------------------------------*/
492 usb_proc_rewakeup(struct usb_process *up)
494 /* check if not initialised */
495 if (up->up_mtx == NULL)
501 USB_MTX_ASSERT(up->up_mtx, MA_OWNED);
503 if (up->up_msleep == 0) {
505 cv_signal(&up->up_cv);
509 /*------------------------------------------------------------------------*
510 * usb_proc_is_called_from
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 *------------------------------------------------------------------------*/
516 usb_proc_is_called_from(struct usb_process *up)
518 return (up->up_curtd == curthread);