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
64static struct proc *usbproc;
65static 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
74static int usb_proc_debug;
75
76static SYSCTL_NODE(_hw_usb, OID_AUTO, proc, CTLFLAG_RW | CTLFLAG_MPSAFE, 0,
77    "USB process");
78SYSCTL_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 *------------------------------------------------------------------------*/
87static void
88usb_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 *------------------------------------------------------------------------*/
203int
204usb_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
224error:
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 *------------------------------------------------------------------------*/
238void
239usb_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 *------------------------------------------------------------------------*/
265void   *
266usb_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 *------------------------------------------------------------------------*/
349uint8_t
350usb_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/*------------------------------------------------------------------------*
365 *	usb_proc_mwait
366 *
367 * This function will return when the USB process message pointed to
368 * by "pm" is no longer on a queue. This function must be called
369 * having "up->up_mtx" locked.
370 *------------------------------------------------------------------------*/
371void
372usb_proc_mwait(struct usb_process *up, void *_pm0, void *_pm1)
373{
374	struct usb_proc_msg *pm0 = _pm0;
375	struct usb_proc_msg *pm1 = _pm1;
376
377	/* check if gone */
378	if (up->up_gone)
379		return;
380
381	USB_MTX_ASSERT(up->up_mtx, MA_OWNED);
382
383	if (up->up_curtd == curthread) {
384		/* Just remove the messages from the queue. */
385		if (pm0->pm_qentry.tqe_prev) {
386			TAILQ_REMOVE(&up->up_qhead, pm0, pm_qentry);
387			pm0->pm_qentry.tqe_prev = NULL;
388		}
389		if (pm1->pm_qentry.tqe_prev) {
390			TAILQ_REMOVE(&up->up_qhead, pm1, pm_qentry);
391			pm1->pm_qentry.tqe_prev = NULL;
392		}
393	} else
394		while (pm0->pm_qentry.tqe_prev ||
395		    pm1->pm_qentry.tqe_prev) {
396			/* check if config thread is gone */
397			if (up->up_gone)
398				break;
399			up->up_dsleep = 1;
400			cv_wait(&up->up_drain, up->up_mtx);
401		}
402}
403
404/*------------------------------------------------------------------------*
405 *	usb_proc_drain
406 *
407 * This function will tear down an USB process, waiting for the
408 * currently executing command to return.
409 *
410 * NOTE: If the structure pointed to by "up" is all zero,
411 * this function does nothing.
412 *------------------------------------------------------------------------*/
413void
414usb_proc_drain(struct usb_process *up)
415{
416	/* check if not initialised */
417	if (up->up_mtx == NULL)
418		return;
419	/* handle special case with Giant */
420	if (up->up_mtx != &Giant)
421		USB_MTX_ASSERT(up->up_mtx, MA_NOTOWNED);
422
423	USB_MTX_LOCK(up->up_mtx);
424
425	/* Set the gone flag */
426
427	up->up_gone = 1;
428
429	while (up->up_ptr) {
430		/* Check if we need to wakeup the USB process */
431
432		if (up->up_msleep || up->up_csleep) {
433			up->up_msleep = 0;
434			up->up_csleep = 0;
435			cv_signal(&up->up_cv);
436		}
437#ifndef EARLY_AP_STARTUP
438		/* Check if we are still cold booted */
439		if (cold) {
440			USB_THREAD_SUSPEND(up->up_ptr);
441			printf("WARNING: A USB process has "
442			    "been left suspended\n");
443			break;
444		}
445#endif
446		cv_wait(&up->up_cv, up->up_mtx);
447	}
448	/* Check if someone is waiting - should not happen */
449
450	if (up->up_dsleep) {
451		up->up_dsleep = 0;
452		cv_broadcast(&up->up_drain);
453		DPRINTF("WARNING: Someone is waiting "
454		    "for USB process drain!\n");
455	}
456	USB_MTX_UNLOCK(up->up_mtx);
457}
458
459/*------------------------------------------------------------------------*
460 *	usb_proc_rewakeup
461 *
462 * This function is called to re-wakeup the given USB
463 * process. This usually happens after that the USB system has been in
464 * polling mode, like during a panic. This function must be called
465 * having "up->up_mtx" locked.
466 *------------------------------------------------------------------------*/
467void
468usb_proc_rewakeup(struct usb_process *up)
469{
470	/* check if not initialised */
471	if (up->up_mtx == NULL)
472		return;
473	/* check if gone */
474	if (up->up_gone)
475		return;
476
477	USB_MTX_ASSERT(up->up_mtx, MA_OWNED);
478
479	if (up->up_msleep == 0) {
480		/* re-wakeup */
481		cv_signal(&up->up_cv);
482	}
483}
484
485/*------------------------------------------------------------------------*
486 *	usb_proc_is_called_from
487 *
488 * This function will return non-zero if called from inside the USB
489 * process passed as first argument. Else this function returns zero.
490 *------------------------------------------------------------------------*/
491int
492usb_proc_is_called_from(struct usb_process *up)
493{
494	return (up->up_curtd == curthread);
495}
496