WorkItem SynchronizationScope / AutomaticSerialization

NTDEV
1

Hi

I have below inherited code that creates syncScope/AutoSerialization (w.r.t workItem).

  • It creates a Queue object to limit SyncScope of the WorkItem.
  • During Queue creation it chooses WdfExecutionLevelPassive/WdfSynchronizationScopeQueue. ,
    (parent of queue is WDFDEVICE and WDFDEVICE doesn’t change any of its defaults i…e WdfSynchronizationScopeInheritFromParent(= none), WdfExecutionLevelInheritFromParent (=dispatch))

I have below questions as to what Fx does with below settings

  1. Is the WorkItem serialized against anything in driver (those callbacks which have AutomaticSerialization = TRUE (and ExecutionLevelPassive)); ? Not sure
  2. Is the workItem serialized against itself ? YES?

Thanks

    //queue
    WDF_IO_QUEUE_CONFIG_INIT(&queueConfig, WdfIoQueueDispatchManual);
    queueConfig.PowerManaged = WdfFalse;

   WDF_OBJECT_ATTRIBUTES attributes;
    attributes.ParentObject = Device;
    attributes.ExecutionLevel = WdfExecutionLevelPassive;
    attributes.SynchronizationScope = WdfSynchronizationScopeQueue;

    WDFQUEUE ParentObjectWdfQueue = NULL;
    NTSTATUS status = WdfIoQueueCreate(Device, &queueConfig, &attributes, &ParentObjectWdfQueue);

--Workitem
    WDF_WORKITEM_CONFIG_INIT(&workitemConfig, func);
    NT_ASSERT(workitemConfig.AutomaticSerialization == TRUE);

    // Set the parent object to be device
    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes, WORKITEM_CONTEXT);
    attributes.ParentObject = ParentObjectWdfQueue; //parent is queue, parent of queue is device
 
    NTSTATUS status = WdfWorkItemCreate(&workitemConfig, &attributes, t);
2

In your code, the work item is serialized against all other things protected by Sync Scope Queue (so, for example, the EvtIoXxx Event Processing Callbacks at the Queue level).

In general, specifying Sync Scope is not a best practice.

Peter

3

Thanks Peter.

In above, a specific Queue is created for specific purpose to parent each WORKITEM.
(Also these queues have no EvtIoXXX() calls associated with them (at least explicitly within the driver))

i.e. WDFWORKITEM-1 parented by WDFQUEUE-1 and WDFWORKITEM-2 parented by WDFQUEUE-2.
(Each WDFWORKITEM has default AutomaticSerialization=TRUE)

So can I assume below

  • Even though each WORKITEM has syncScope Queue, since the parent of each WDFWORKITEM is a distinct queue, WORKITEM-1 isn’t synched with WORKITEM-2 even though they have AutomaticSerialization set to true?

Thanks

4

If you use AutomaticSerialization, then ISRs, DPCs, work items, and timers are all serialized.

I want to emphasize what Peter said. As a general rule, AutomaticSerialization and Sync Scope are bad ideas. They are a bandaid to cover up lazy coding, and they can very easily lead to deadlocks.

Do your job as an engineer. Figure out what parts of your state need protecting, and add locks where those items are updated. Turn off the automatic locking. Your system will run better because of it.

5

If you use AutomaticSerialization, then ISRs, DPCs, work items, and timers are all serialized.

Actually, not quite correct. Your ISR is never serialized by this, and your timers, DPCs, and work items are only serialized if you set the AutomaticSerialization field for those structures to TRUE.

Sync Scope was not a good idea when it was created, and it’s use is rarely a good idea now. The idea was to further simplify driver writing… the result was to create more locking that people who don’t understand locking still don’t understand.

Peter

6

Read this beautiful article by none other than OSR only.
https://www.osr.com/nt-insider/2014-issue3/understanding-sync-scope-wdf-drivers/