USB_ADD_TASK(9) | Kernel Developer's Manual | USB_ADD_TASK(9)

# NAME

`usb_add_task`, `usb_rem_task`, `usb_wait_task`, `usb_rem_wait_task`, `usb_init_task` — USB task queues

# SYNOPSIS

`#include <dev/usb/usbdi.h>`

void
`usb_add_task`(struct usbd_device *dev, struct usb_task *task);

void
`usb_rem_task`(struct usbd_device *dev, struct usb_task *task);

void
`usb_wait_task`(struct usbd_device *dev, struct usb_task *task);

void
`usb_rem_wait_task`(struct usbd_device *dev, struct usb_task *task);

void
`usb_init_task`(struct usb_task *task, void (*fn)(void *), void *arg, char type);

# DESCRIPTION

The USB stack provides an API to manage task execution in a thread context at the soonest opportunity. There are three different task queues that are executed on two separate threads. All tasks executed via the USB task API are serialized with USB events such as device detachments.

The `usb_add_task`() function enqueues a task to be executed by the task thread. Subsequent calls to `usb_add_task`() will not result in multiple executions being scheduled. The task structure must already be initialised by `usb_init_task`().

The `usb_rem_task`() function removes a scheduled task from its queue. If the work was already executed or has not been added to the task queue, the call will have no effect. Calling `usb_rem_task`() while the task is executing will not abort it.

The `usb_wait_task`() function sleeps until the given task is neither queued for execution nor currently running.

The `usb_rem_wait_task`() function is the equivalent of calling `usb_rem_task`() followed by `usb_wait_task`().

The `usb_init_task`() macro prepares the task structure task to be used in future calls to `usb_add_task`(), `usb_rem_task`(), `usb_wait_task`(), and `usb_rem_wait_task`(). task will be prepared to call the function fn with the argument specified by arg. The type of the task determines the queue and thread that will be used for its execution:

`USB_TASK_TYPE_GENERIC`
  Tasks used for general work that need to happen in a process context.
`USB_TASK_TYPE_EXPLORE`
  Device discovery tasks exploring the tree from the root.
`USB_TASK_TYPE_ABORT`
  Tasks of this type execute on a dedicated thread not shared with other USB task types.

Most drivers will only define tasks of type `USB_TASK_TYPE_GENERIC`. Note that `USB_TASK_TYPE_ABORT` tasks are only used by host controller drivers and should never be used by drivers. Once initialised, the task can be used repeatedly in the API functions listed above and does not need to be reinitialised unless the function called and/or its argument must change.

# CONTEXT

`usb_task_add`() can be called from any context.

# SEE ALSO

usb(4), task_add(9)

January 19, 2021 | Debian