The docs on “Using Automatic Synchronization” seem a little unclear to me.
It states the default synchronization value for device and queue objects is WdfSynchronizationScopeNone. I assume (though it’s not stated) that the default synchronization value for all other objects is WdfSynchronizationScopeInheritFromParent except for the driver object which would be WdfSynchronizationScopeNone.
I’m also assuming that the “default” value is only applied if WDF_NO_OBJECT_ATTRIBUTES is passed during creation, since all the attribute init macros set it to WdfSynchronizationScopeInheritFromParent. Again, the documentation does not make it clear when the “default” value is applied.
If I’m right, then the docs must be wrong in one aspect: they state that to get device-level synchronization, just set it to ScopeDevice in the driver object and have the device objects inherit it. However, that leaves the queue objects still with a default of ScopeNone. (The alternate approach recommended by the docs has the same problem).
The official documentation contradicts the defaults specified in “Developing Drivers with the WDF”, pg 392-393. Though I must say that the defaults in the book seem more intuitive to me.
So, I’m either misunderstanding something or the documentation topic “Using Automatic Synchronization” is incorrect.
Simple question, simple answer: The default synchronization scope for both device and queue objects is WdfSynchronizationScopeInheritFromParent.
In terms of how you specify sync scope the docs are correct, but unnecessarily prescriptive (that is, they only indicate ONE of several possible ways to do it correctly).
You can always set the sync scope (device or queue) on the driver object, and let all the children (devices and queues) inherit this by using the defaults. This can be an attractive option, assuming you want the same sync scope on all your child objects.
Alternatively, you can set the sync scope in the WDF_OBJECT_ATTRIBUTES structure that’s used for creating the desired Framework Object. The advantage to this approach, in my opinion, is that it makes the synch scope associated with the object explicitly clear – it’s specified at object creation. This would allow you to have one WDF Device that’s synchScopeDevice and another that’s synchScopeQueue – I’m not sure how much sense this would make in a real driver, but it’s possible.
If you are correct, then the WDK documentation is wrong:
Topic “Using Automatic Synchronization”, section “Choosing a Synchronization Scope”, it states:
“The default synchronization scope for device and queue objects is WdfSynchronizationScopeNone.”
However, it certainly makes more sense to me if the default would be to inherit.
Dude… Spend a few minutes and try it out yourself. Then you won’t have to stay up nights worrying about whether the docs are giving you the definitive answer.
Docs… good for finding out how things probably work. Code… good for finding out how things definitely work.
Docs… good for finding out how things probably work. Code… good for finding out how things definitely work.
With due respect, I must completely disagree. When writing against an API/library, the documentation represents a contract between the library writer and the end programmer. The behavior may change.
I have in the past written software that depended on well-tested, repeatable, yet undocumented behavior… only to have it change in a later version. I just don’t do that anymore; the only time I use undocumented functions/structures are for implementing newer APIs on older, stable platforms. If Russinovich and Cogswell want to do it on modern platforms, fine.
But I choose to view the documentation as a contract, a written agreement. This view does make documentation bugs very serious.
Nobody’s suggesting that you use undocumented structures or interfaces.
A contract? So, do you get the (no) money you paid for the WDK back if the docs are wrong?
Seriously, though, for architectural issues, you are correct (if a bit narrow). You can’t rely on a DDI to do something that it just “happens” to do, if that’s not a documented effect. But that’s NOT what we’re talking about here, dynamic behaviors. We’re talking about what the default value of something is. You can determine this empirically and beyond any doubt just by TRYING it.
If your empirical results do not match what’s in the documentation… report it as a bug. Duh! The docs HAVE to be wrong.
You might want to lighten-up a little if you’re going to be writing Windows drivers for any amount of time. The docs just aren’t always definitive. Would that it were so…
Looks like I need to update the WDK docs. Currently the docs say that you can set synch scope on device, queue, and file objects. But actually, you can set scope only on driver and device objects.
