WDK DOC: NDIS DDI IRQL specifications changed in WDK docs

David_R_Cattley · January 21, 2010, 9:11am

[Since Mr. Tippet has been seen in these parts …]

While code-reviewing a project for a customer this week I came across what I
believe to be a wholesale set of DOC errors in the WDK docs for NDIS.
Either that, or the NDIS rules have changed and a whole lot of code is now
illegal.

The execution IRQL specification for ProtocolReceive(),
ProtocolReceiveComplete(), ProtocolReceivePacket(),
ProtocolRequestComplete() and surely others have all had the IRQL execution
specification changed from

“Xxxx runs at IRQL == DISPATCH_LEVEL”

To

“Xxx runs at IRQL <= DISPATCH_LEVEL”

Now I did not go find the complete list of these. But it surely freaked me
out when I was referring back to WDK specifications to validate IRQL
assumptions and explaining that process to a developer I was coaching and
then wondering why this example code (that I wrote) suddenly seemed to be
violating the IRQL constraints. Now sure, I make those mistakes but I
generally don’t like to parade them around

So the coaching lesson turned into [with some colorful language] an
explanation why one should never throw away old DDK docs. Also a valuable
lesson but not the one intended.

I would most appreciate a clarification from the WDK DOC team regarding
these changes - were they driven by actual changes in the rules? Did
somebody rewrite NDIS between NT5 and NT6 such that the rules changed or was
this a DOC error?

Thanks,
Dave Cattley

OSR_Community_User · January 21, 2010, 4:46pm

Dave, you are correct that the docs here have changed. The old 5.1 docs used to say " IRQL: DISPATCH_LEVEL" or in some cases, " ProtocolReceive runs at IRQL = DISPATCH_LEVEL." That notation was a relic from a less standardized era of documentation: the author of that text meant to communicate something like “Yes, it *can* run up to DISPATCH_LEVEL”. Obviously, that interpretation requires a rather twisted use of the English language, and is completely misleading to just about everybody, since it runs counter to the contemporary MSDN standard.

To fix the confusion, in September 2008, all the old 5.1 docs were changed en masse to the more conventional and less ambiguous “<= DISPATCH_LEVEL” notation. If you took the obvious interpretation of the old text, this is a change of the NDIS contract, so for that I apologize. Our actual implementation of that contract (NDIS.sys) permits the datapath to run at <=DISPATCH, although it’s much more common to see dispatch than passive.

There are other cases like this where we need to fix the IRQLs for consistency or just plain sanity. Fortunately, most are usually quite minor; the aforementioned revision was an exception. Below I have printed all the recent ones that I am aware of. These are mostly still “in the works” so the production MSDN website hasn’t been updated yet.

But I would like to pose this question for the community: how can we best communicate documentation updates like these? Bear in mind that some are quite trifling (e.g., probably nobody cares that you can now call NdisFreeSpinLock at DISPATCH_LEVEL); and any big ones are usually only immediately after we release a new OS with its new interfaces (e.g. the new VMQ DDIs).

FilterSetModuleOptions handler will be changed to “==PASSIVE_LEVEL” from “<=DISPATCH_LEVEL” (required for sanity, since NdisSetOptionalHandlers is PASSIVE only)

NdisBuildScatterGatherList, NdisFreeScatterGatherList, and NetProcessSGList will be changed to “==DISPATCH_LEVEL” from “PASSIVE_LEVEL” (SG DMA is always DISPATCH_LEVEL in Windows)

NdisFreeSharedMemory will be changed to “PASSIVE_LEVEL” from “<=DISPATCH_LEVEL” (sorry, this is just an unfortunate bug in the docs)

MiniportSharedMemoryAllocateComplete was changed to “PASSIVE_LEVEL” from “DISPATCH_LEVEL” (Another unfortunate doc bug)

NetTimerCallback will be changed to “DISPATCH_LEVEL” from “<=DISPATCH_LEVEL” (NDIS timers run at DPC; no need to be vague about what IRQL you’ll be called at)

MiniportCheckForHangEx will be changed to “PASSIVE_LEVEL” from “<=DISPATCH_LEVEL” (CFH runs at PASSIVE; no need to be vague about what IRQL you’ll be called at)

NdisFreeSpinLock was changed to “any” from “PASSIVE_LEVEL” (not realistically useful, but since NdisAllocateSpinLock was already “any”, hypothetical DISPATCH callers were in the odd position of being able to allocate something they couldn’t free)

-----Original Message-----
From: xxxxx@lists.osr.com [mailto:xxxxx@lists.osr.com] On Behalf Of David R. Cattley
Sent: Thursday, January 21, 2010 6:11 AM
To: Windows System Software Devs Interest List
Subject: [ntdev] WDK DOC: NDIS DDI IRQL specifications changed in WDK docs

[Since Mr. Tippet has been seen in these parts …]

While code-reviewing a project for a customer this week I came across what I believe to be a wholesale set of DOC errors in the WDK docs for NDIS.
Either that, or the NDIS rules have changed and a whole lot of code is now illegal.

The execution IRQL specification for ProtocolReceive(), ProtocolReceiveComplete(), ProtocolReceivePacket(),
ProtocolRequestComplete() and surely others have all had the IRQL execution specification changed from

“Xxxx runs at IRQL == DISPATCH_LEVEL”

To

“Xxx runs at IRQL <= DISPATCH_LEVEL”

Now I did not go find the complete list of these. But it surely freaked me out when I was referring back to WDK specifications to validate IRQL assumptions and explaining that process to a developer I was coaching and then wondering why this example code (that I wrote) suddenly seemed to be violating the IRQL constraints. Now sure, I make those mistakes but I generally don’t like to parade them around

So the coaching lesson turned into [with some colorful language] an explanation why one should never throw away old DDK docs. Also a valuable lesson but not the one intended.

I would most appreciate a clarification from the WDK DOC team regarding these changes - were they driven by actual changes in the rules? Did somebody rewrite NDIS between NT5 and NT6 such that the rules changed or was this a DOC error?

Thanks,
Dave Cattley

NTDEV is sponsored by OSR

For our schedule of WDF, WDM, debugging and other seminars visit:
http://www.osr.com/seminars

To unsubscribe, visit the List Server section of OSR Online at http://www.osronline.com/page.cfm?name=ListServer

David_R_Cattley · January 21, 2010, 5:06pm

Jeffrey,

Thanks for the reply. Now I really am freaked out. What you are saying
here is that a documented contract for an NDIS callback routine, that
previously (since NDIS 3.0) has been documented as *guaranteed to be called
at DISPATCH_LEVEL* is actually incorrectly documented? Meaning that NDIS
does not guarantee that (for example) ProtocolReceive() is called at
DISPATCH_LEVEL?

Wow.

So, how about the samples in the WDK that all show implementation techniques
for said callback to use NdisDprXxxx() routines because, well, the contract
was that the callback was called at DISPATCH_LEVEL and so the NdisDprXxx()
routines were legal. Now they are illegal because they *require*
DISPATCH_LEVEL and the callback no longer has that guarantee.

Wow.

Respectfully, I remain to be convinced that NDIS has changed the rules or
that for 15 years we have been told the wrong rules. Maybe that is true.
But I would like to hear it again and then be given time to go outside and
scream.

Wow.

Cheers,
Dave Cattley

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Jeffrey Tippet
Sent: Thursday, January 21, 2010 4:46 PM
To: Windows System Software Devs Interest List
Subject: RE: [ntdev] WDK DOC: NDIS DDI IRQL specifications changed in WDK
docs

Dave, you are correct that the docs here have changed. The old 5.1 docs
used to say " IRQL: DISPATCH_LEVEL" or in some cases, " ProtocolReceive runs
at IRQL = DISPATCH_LEVEL." That notation was a relic from a less
standardized era of documentation: the author of that text meant to
communicate something like “Yes, it *can* run up to DISPATCH_LEVEL”.
Obviously, that interpretation requires a rather twisted use of the English
language, and is completely misleading to just about everybody, since it
runs counter to the contemporary MSDN standard.

To fix the confusion, in September 2008, all the old 5.1 docs were changed
en masse to the more conventional and less ambiguous “<= DISPATCH_LEVEL”
notation. If you took the obvious interpretation of the old text, this is a
change of the NDIS contract, so for that I apologize. Our actual
implementation of that contract (NDIS.sys) permits the datapath to run at
<=DISPATCH, although it’s much more common to see dispatch than passive.

There are other cases like this where we need to fix the IRQLs for
consistency or just plain sanity. Fortunately, most are usually quite
minor; the aforementioned revision was an exception. Below I have printed
all the recent ones that I am aware of. These are mostly still “in the
works” so the production MSDN website hasn’t been updated yet.

But I would like to pose this question for the community: how can we best
communicate documentation updates like these? Bear in mind that some are
quite trifling (e.g., probably nobody cares that you can now call
NdisFreeSpinLock at DISPATCH_LEVEL); and any big ones are usually only
immediately after we release a new OS with its new interfaces (e.g. the new
VMQ DDIs).

FilterSetModuleOptions handler will be changed to “==PASSIVE_LEVEL” from
“<=DISPATCH_LEVEL” (required for sanity, since NdisSetOptionalHandlers is
PASSIVE only)

NdisBuildScatterGatherList, NdisFreeScatterGatherList, and NetProcessSGList
will be changed to “==DISPATCH_LEVEL” from “PASSIVE_LEVEL” (SG DMA is always
DISPATCH_LEVEL in Windows)

NdisFreeSharedMemory will be changed to “PASSIVE_LEVEL” from
“<=DISPATCH_LEVEL” (sorry, this is just an unfortunate bug in the docs)

MiniportSharedMemoryAllocateComplete was changed to “PASSIVE_LEVEL” from
“DISPATCH_LEVEL” (Another unfortunate doc bug)

NetTimerCallback will be changed to “DISPATCH_LEVEL” from “<=DISPATCH_LEVEL”
(NDIS timers run at DPC; no need to be vague about what IRQL you’ll be
called at)

MiniportCheckForHangEx will be changed to “PASSIVE_LEVEL” from
“<=DISPATCH_LEVEL” (CFH runs at PASSIVE; no need to be vague about what IRQL
you’ll be called at)

NdisFreeSpinLock was changed to “any” from “PASSIVE_LEVEL” (not
realistically useful, but since NdisAllocateSpinLock was already “any”,
hypothetical DISPATCH callers were in the odd position of being able to
allocate something they couldn’t free)

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of David R. Cattley
Sent: Thursday, January 21, 2010 6:11 AM
To: Windows System Software Devs Interest List
Subject: [ntdev] WDK DOC: NDIS DDI IRQL specifications changed in WDK docs

[Since Mr. Tippet has been seen in these parts …]

While code-reviewing a project for a customer this week I came across what I
believe to be a wholesale set of DOC errors in the WDK docs for NDIS.
Either that, or the NDIS rules have changed and a whole lot of code is now
illegal.

The execution IRQL specification for ProtocolReceive(),
ProtocolReceiveComplete(), ProtocolReceivePacket(),
ProtocolRequestComplete() and surely others have all had the IRQL execution
specification changed from

“Xxxx runs at IRQL == DISPATCH_LEVEL”

To

“Xxx runs at IRQL <= DISPATCH_LEVEL”

Now I did not go find the complete list of these. But it surely freaked me
out when I was referring back to WDK specifications to validate IRQL
assumptions and explaining that process to a developer I was coaching and
then wondering why this example code (that I wrote) suddenly seemed to be
violating the IRQL constraints. Now sure, I make those mistakes but I
generally don’t like to parade them around

So the coaching lesson turned into [with some colorful language] an
explanation why one should never throw away old DDK docs. Also a valuable
lesson but not the one intended.

I would most appreciate a clarification from the WDK DOC team regarding
these changes - were they driven by actual changes in the rules? Did
somebody rewrite NDIS between NT5 and NT6 such that the rules changed or was
this a DOC error?

Thanks,
Dave Cattley

NTDEV is sponsored by OSR

For our schedule of WDF, WDM, debugging and other seminars visit:
http://www.osr.com/seminars

To unsubscribe, visit the List Server section of OSR Online at
http://www.osronline.com/page.cfm?name=ListServer

NTDEV is sponsored by OSR

For our schedule of WDF, WDM, debugging and other seminars visit:
http://www.osr.com/seminars

To unsubscribe, visit the List Server section of OSR Online at
http://www.osronline.com/page.cfm?name=ListServer

David_R_Cattley · January 21, 2010, 5:43pm

Ok, so I can’t substantiate 15 years but I did just look at the NT4 DDK docs
and so I can reasonably substantiate 13.5 years. If I didn’t lose my NT 3.1
DDK and MSDN 1.0 discs I might be able to make good on the 15 year claim.

I guess I am most concerned about misunderstanding what you are saying. It
sounds like what you are saying is that the rules all along have been the
same, just incorrectly stated. But in particular, I am truly concerned
that there is a large body of code out there written to the rules as *were*
stated and now potentially (and inadvertently) incorrect.

Regards,
Dave Cattley

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of David R. Cattley
Sent: Thursday, January 21, 2010 5:05 PM
To: Windows System Software Devs Interest List
Subject: RE: [ntdev] WDK DOC: NDIS DDI IRQL specifications changed in WDK
docs