USB_ADD_TASK(9)

💖 USB_ADD_TASK(9) 💖

okay so bestie, this is the USB_ADD_TASK(9) page from the Kernel Developer's Manual. It's all about USB task queues, and honestly? kind of iconic. Let's get into it. ✨

🎀 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 gives you an API to manage task execution in a thread context at the soonest opportunity. There are three different task queues, and they run on two separate threads. Every task executed through the USB task API is serialized with USB events such as device detachments. No cap.

• usb_add_task() — enqueues a task to be executed by the task thread. If you call usb_add_task() again, it will not schedule multiple executions. The task structure must already be initialised by usb_init_task().
• usb_rem_task() — removes a scheduled task from its queue. If the work was already executed, or it 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.
• usb_wait_task() — sleeps until the given task is neither queued for execution nor currently running. It's giving "wait for it" energy, but literally.
• usb_rem_wait_task() — the equivalent of calling usb_rem_task() followed by usb_wait_task().
• usb_init_task() — this 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(). The task will be prepared to call the function fn with the argument specified by arg. The type of the task decides which queue and thread will be used for its execution:

🦋 task types 🦋

• 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. Like, never ever. This is not a drill, bestie.

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)

---

mwah 💋 that's the whole page. Source/version: Debian. Date: January 19, 2021. go off, kernel dev bestie 🫶