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