Edit

Using Work Items

  • Article

Warning

UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2.

The archived UMDF 1 samples can be found in the Windows 11, version 22H2 - May 2022 Driver Samples Update.

For more info, see Getting Started with UMDF.

A work item is a task that a driver performs in an OnWorkItem event callback function. These functions run asynchronously.

UMDF drivers commonly use work items if an OnInterruptIsr must perform additional processing without delaying the execution of the interrupt service request (ISR) because the interrupt line may be shared by multiple devices.

Typically, a driver's OnInterruptIsr callback function creates a work-item object and adds it to the system's work-item queue. Subsequently, a threadpool thread dequeues the object and calls the work item's OnWorkItem callback function.

Setting Up a Work Item

To set up a work item, your driver must:

  1. Create the work item.

    Your driver calls IWDFDevice3::CreateWorkItem to create a work-item object and to identify an OnWorkItem callback function that will process the work item.

  2. Store information about the work item.

    Typically, drivers use the context memory of the work-item object to store information about the task that the OnWorkItem callback function should perform. When the OnWorkItem callback function is called, it can retrieve the information by accessing this context memory. For information about how to allocate and access context memory, seeIWDFObject::AssignContext.

  3. Add the work item to the system's work-item queue.

    Your driver calls IWDFWorkItem::Enqueue, which adds the driver's work item to the work-item queue.

When your driver calls IWDFDevice3::CreateWorkItem, it may optionally supply a parent object (for example a device object or a queue object). When the system deletes that object, it also deletes any existing work items that are associated with the object.

Using the WorkItem Callback Function

After the work item has been added to the work-item queue, it remains in the queue until a system worker thread becomes available. The system worker thread removes the work item from the queue and then calls the driver's OnWorkItem callback function, passing the work-item object as input.

Typically, the OnWorkItem callback function performs the following steps:

  1. Obtains driver-supplied information about the work item by accessing the context memory of the work-item object.
  2. Performs the task that you specified. If necessary, the callback function can call IWDFWorkItem::GetParentObject to determine the work item's parent object.
  3. If the driver will requeue the work item, indicates that the handle to the work item is now available for reuse.

A few drivers might need to call IWDFWorkItem::Flush to flush their work items from the work-item queue. If a driver calls the Flush method, the method does not return until a worker thread has removed the specified work item from the work-item queue and called the driver's OnWorkItem callback function, and the OnWorkItem callback function has subsequently returned after processing the work item.