1.\" $OpenBSD: usb_add_task.9,v 1.3 2021/01/19 16:05:59 anton Exp $ 2.\" 3.\" Copyright (c) 2016 Adam Wolk <awolk@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: January 19 2021 $ 18.Dt USB_ADD_TASK 9 19.Os 20.Sh NAME 21.Nm usb_add_task , 22.Nm usb_rem_task , 23.Nm usb_wait_task , 24.Nm usb_rem_wait_task , 25.Nm usb_init_task 26.Nd USB task queues 27.Sh SYNOPSIS 28.In dev/usb/usbdi.h 29.Ft void 30.Fn usb_add_task "struct usbd_device *dev" "struct usb_task *task" 31.Ft void 32.Fn usb_rem_task "struct usbd_device *dev" "struct usb_task *task" 33.Ft void 34.Fn usb_wait_task "struct usbd_device *dev" "struct usb_task *task" 35.Ft void 36.Fn usb_rem_wait_task "struct usbd_device *dev" "struct usb_task *task" 37.Ft void 38.Fn usb_init_task "struct usb_task *task" "void (*fn)(void *)" "void *arg" "char type" 39.Sh DESCRIPTION 40The USB stack provides an API to manage task execution in a thread context at 41the soonest opportunity. 42There are three different task queues 43that are executed on two separate threads. 44All tasks executed via the USB task API are 45serialized with USB events such as device detachments. 46.Pp 47The 48.Fn usb_add_task 49function enqueues a task to be executed by the task thread. 50Subsequent calls to 51.Fn usb_add_task 52will not result in multiple executions being scheduled. 53The task structure must already be initialised by 54.Fn usb_init_task . 55.Pp 56The 57.Fn usb_rem_task 58function removes a scheduled task from its queue. 59If the work was already executed or has not been added to the task queue, 60the call will have no effect. 61Calling 62.Fn usb_rem_task 63while the task is executing will not abort it. 64.Pp 65The 66.Fn usb_wait_task 67function sleeps until the given task is neither queued for execution 68nor currently running. 69.Pp 70The 71.Fn usb_rem_wait_task 72function is the equivalent of calling 73.Fn usb_rem_task 74followed by 75.Fn usb_wait_task . 76.Pp 77The 78.Fn usb_init_task 79macro prepares the task structure 80.Fa task 81to be used in future calls to 82.Fn usb_add_task , 83.Fn usb_rem_task , 84.Fn usb_wait_task , 85and 86.Fn usb_rem_wait_task . 87.Fa task 88will be prepared to call the function 89.Fa fn 90with the argument specified by 91.Fa arg . 92The 93.Fa type 94of the task determines the queue 95and thread that will be used for its execution: 96.Bl -tag -width "USB_TASK_TYPE_EXPLORE" -offset indent 97.It Dv USB_TASK_TYPE_GENERIC 98Tasks used for general work that need to happen in a process context. 99.It Dv USB_TASK_TYPE_EXPLORE 100Device discovery tasks exploring the tree from the root. 101.It Dv USB_TASK_TYPE_ABORT 102Tasks of this type execute on a dedicated thread 103not shared with other USB task types. 104.El 105.Pp 106Most drivers will only define tasks of type 107.Dv USB_TASK_TYPE_GENERIC . 108Note that 109.Dv USB_TASK_TYPE_ABORT 110tasks are only used by host controller drivers 111and should never be used by drivers. 112Once initialised, the 113.Fa task 114can be used repeatedly in the API functions listed above 115and does not need to be reinitialised 116unless the function called and/or its argument must change. 117.Sh CONTEXT 118.Fn usb_task_add 119can be called from any context. 120.Sh SEE ALSO 121.Xr usb 4 , 122.Xr task_add 9 123