WDF IO execution level question

NTDEV
1

Hi,

I have noticed something weird in the WDF osrusbfx2 sample that is supplied
with the DDK. The IO functions in the example (read, write, control) are
placed in pageable code sections.

The documentation states that these functions are called at <= DISPATCH
level unless the parent has been created with the execution level attribute
set to WdfExecutionLevelPassive.

Looking in the code, the device is created with the default attributes,
which specify WdfExecutionLevelInheritFromParent, according to the
documentation.

The driver object is also created with the default object attributes, but
the KMDF documentation states that The default execution level for driver
objects is WdfExecutionLevelDispatch.

The documentation also states that DriverObjects do not have a parent.

This means there are 4 options (I think):

  • the example is wrong, because the IO functions can be called at
    DISPATCH level.

  • The documentation is wrong, and driver objects are created with
    execution level passive, or somehow they inherit from the parent they are
    not supposed to have (a framework default or something else).

  • The documentation is incomplete, and should mention that
    WdfExecutionLevelInheritFromParent for driver objects means the same as
    WdfExecutionLevelPassive.

  • I don’t get it, in which case I would appreciate it if someone can
    point me to the flaw in my logic.

Any ideas?

Kind regards,

Bruno.

2

While the DDK says it is possible for read/write/IOCTL to be called at
dispatch level, this is really dependent on the device stack itself.
Certain stacks dictate that i/o must arrive at passive level (like TDI)
while others must handle incoming i/o at dispatch level (like storage).

This is a one off device in its own class, so it can dictate the rules.
It expects all i/o to come in at passive level b/c there is an
expectation that there are no filter drivers above it (and if there are,
that they comply with the assumption) and that the i/o manager is the
one sending i/o.

D

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Bruno van Dooren
Sent: Tuesday, January 17, 2006 9:54 AM
To: Windows System Software Devs Interest List
Subject: [ntdev] WDF IO execution level question

Hi,

I have noticed something weird in the WDF osrusbfx2 sample that is
supplied
with the DDK. The IO functions in the example (read, write, control) are

placed in pageable code sections.

The documentation states that these functions are called at <= DISPATCH
level unless the parent has been created with the execution level
attribute
set to WdfExecutionLevelPassive.

Looking in the code, the device is created with the default attributes,
which specify WdfExecutionLevelInheritFromParent, according to the
documentation.

The driver object is also created with the default object attributes,
but
the KMDF documentation states that The default execution level for
driver
objects is WdfExecutionLevelDispatch.

The documentation also states that DriverObjects do not have a parent.

This means there are 4 options (I think):

  • the example is wrong, because the IO functions can be called
    at
    DISPATCH level.

  • The documentation is wrong, and driver objects are created
    with
    execution level passive, or somehow they inherit from the parent they
    are
    not supposed to have (a framework default or something else).

  • The documentation is incomplete, and should mention that
    WdfExecutionLevelInheritFromParent for driver objects means the same as
    WdfExecutionLevelPassive.

  • I don’t get it, in which case I would appreciate it if someone
    can
    point me to the flaw in my logic.

Any ideas?

Kind regards,

Bruno.

Questions? First check the Kernel Driver FAQ at
http://www.osronline.com/article.cfm?id=256

You are currently subscribed to ntdev as: xxxxx@microsoft.com
To unsubscribe send a blank email to xxxxx@lists.osr.com

3

Bruno van Dooren wrote:

I have noticed something weird in the WDF osrusbfx2 sample that is supplied
with the DDK. The IO functions in the example (read, write, control) are
placed in pageable code sections.

The documentation states that these functions are called at <= DISPATCH
level unless the parent has been created with the execution level attribute
set to WdfExecutionLevelPassive.

That is a top-most driver. Read, write, and control will be invoked
directly from user-mode applications, and will thus be called at a
passive IRQL.

–
Tim Roberts, xxxxx@probo.com
Providenza & Boekelheide, Inc.

4

is this documented somewhere? because it is not obvious from the
documentation that i could find.

kind regards,
Bruno.

“Tim Roberts” wrote in message news:xxxxx@ntdev…
> Bruno van Dooren wrote:
>
>>
>>I have noticed something weird in the WDF osrusbfx2 sample that is
>>supplied
>>with the DDK. The IO functions in the example (read, write, control) are
>>placed in pageable code sections.
>>
>>The documentation states that these functions are called at <= DISPATCH
>>level unless the parent has been created with the execution level
>>attribute
>>set to WdfExecutionLevelPassive.
>>
>>
>
> That is a top-most driver. Read, write, and control will be invoked
> directly from user-mode applications, and will thus be called at a
> passive IRQL.
>
> –
> Tim Roberts, xxxxx@probo.com
> Providenza & Boekelheide, Inc.
>
>
>

5


Dispatch Routines and IRQLs

Most drivers’ dispatch routines are called in an arbitrary thread
context at IRQL = PASSIVE_LEVEL, with the following exceptions:

Any highest-level driver’s dispatch routines are called in the context
of the thread that originated the I/O request, which is commonly a
user-mode application thread.
In other words, the dispatch routines of file system drivers and other
highest-level drivers are called in a nonarbitrary thread context at
IRQL = PASSIVE_LEVEL.

The DispatchRead, DispatchWrite, and DispatchDeviceControl routines of
lowest-level device drivers, and of intermediate drivers layered above
them in the system paging path, can be called at IRQL = APC_LEVEL and in
an arbitrary thread context.
The DispatchRead and/or DispatchWrite routines, and any other routine
that also processes read and/or write requests in such a lowest-level
device or intermediate driver, must be resident at all times. These
driver routines can neither be pageable nor be part of a driver’s
pageable-image section; they must not access any pageable memory.
Furthermore, they should not be dependent on any blocking calls (such as
KeWaitForSingleObject with a nonzero time-out).

The DispatchPower routine of drivers in the hibernation and/or paging
paths can be called at IRQL DISPATCH_LEVEL. The DispatchPnP routines of
such drivers must be prepared to handle PnP
IRP_MN_DEVICE_USAGE_NOTIFICATION requests.
The DispatchPower routine of drivers that require inrush power at
start-up
can be called at IRQL DISPATCH_LEVEL

d

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Bruno van Dooren
Sent: Tuesday, January 17, 2006 1:22 PM
To: Windows System Software Devs Interest List
Subject: Re:[ntdev] WDF IO execution level question

is this documented somewhere? because it is not obvious from the
documentation that i could find.

kind regards,
Bruno.

“Tim Roberts” wrote in message news:xxxxx@ntdev…
> Bruno van Dooren wrote:
>
>>
>>I have noticed something weird in the WDF osrusbfx2 sample that is
>>supplied
>>with the DDK. The IO functions in the example (read, write, control)
are
>>placed in pageable code sections.
>>
>>The documentation states that these functions are called at <=
DISPATCH
>>level unless the parent has been created with the execution level
>>attribute
>>set to WdfExecutionLevelPassive.
>>
>>
>
> That is a top-most driver. Read, write, and control will be invoked
> directly from user-mode applications, and will thus be called at a
> passive IRQL.
>
> –
> Tim Roberts, xxxxx@probo.com
> Providenza & Boekelheide, Inc.
>
>
>

—
Questions? First check the Kernel Driver FAQ at
http://www.osronline.com/article.cfm?id=256

You are currently subscribed to ntdev as: xxxxx@microsoft.com
To unsubscribe send a blank email to xxxxx@lists.osr.com

6

>Certain stacks dictate that i/o must arrive at passive level (like TDI)

while others must handle incoming i/o at dispatch level (like storage).

TDI handles sends on DISPATCH fine, but not connects.

Maxim Shatskih, Windows DDK MVP
StorageCraft Corporation
xxxxx@storagecraft.com
http://www.storagecraft.com

7

my statement might have been too broad, but the point was that TDI has
an IRQL restriction for some IRPs.

d

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Maxim S.
Shatskih
Sent: Tuesday, January 17, 2006 11:13 PM
To: Windows System Software Devs Interest List
Subject: Re: [ntdev] WDF IO execution level question

Certain stacks dictate that i/o must arrive at passive level (like TDI)
while others must handle incoming i/o at dispatch level (like storage).

TDI handles sends on DISPATCH fine, but not connects.

Maxim Shatskih, Windows DDK MVP
StorageCraft Corporation
xxxxx@storagecraft.com
http://www.storagecraft.com

Questions? First check the Kernel Driver FAQ at
http://www.osronline.com/article.cfm?id=256

You are currently subscribed to ntdev as: xxxxx@microsoft.com
To unsubscribe send a blank email to xxxxx@lists.osr.com

8

Thanks.

The KMDF documentation is still incomplete (lots of broken links, and
structures and enums that are not in the index.

i still think that this tidbit should be explained, or at least linked to in
the KMDF docs, so that it becomes more obvious. but at least now i know the
answer.

thanks for your time.

kind regards,
Bruno.

“Doron Holan” wrote in message
news:xxxxx@ntdev…

Dispatch Routines and IRQLs

Most drivers’ dispatch routines are called in an arbitrary thread
context at IRQL = PASSIVE_LEVEL, with the following exceptions:

Any highest-level driver’s dispatch routines are called in the context
of the thread that originated the I/O request, which is commonly a
user-mode application thread.
In other words, the dispatch routines of file system drivers and other
highest-level drivers are called in a nonarbitrary thread context at
IRQL = PASSIVE_LEVEL.

The DispatchRead, DispatchWrite, and DispatchDeviceControl routines of
lowest-level device drivers, and of intermediate drivers layered above
them in the system paging path, can be called at IRQL = APC_LEVEL and in
an arbitrary thread context.
The DispatchRead and/or DispatchWrite routines, and any other routine
that also processes read and/or write requests in such a lowest-level
device or intermediate driver, must be resident at all times. These
driver routines can neither be pageable nor be part of a driver’s
pageable-image section; they must not access any pageable memory.
Furthermore, they should not be dependent on any blocking calls (such as
KeWaitForSingleObject with a nonzero time-out).

The DispatchPower routine of drivers in the hibernation and/or paging
paths can be called at IRQL DISPATCH_LEVEL. The DispatchPnP routines of
such drivers must be prepared to handle PnP
IRP_MN_DEVICE_USAGE_NOTIFICATION requests.
The DispatchPower routine of drivers that require inrush power at
start-up
can be called at IRQL DISPATCH_LEVEL


d

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Bruno van Dooren
Sent: Tuesday, January 17, 2006 1:22 PM
To: Windows System Software Devs Interest List
Subject: Re:[ntdev] WDF IO execution level question

is this documented somewhere? because it is not obvious from the
documentation that i could find.

kind regards,
Bruno.

“Tim Roberts” wrote in message news:xxxxx@ntdev…
> Bruno van Dooren wrote:
>
>>
>>I have noticed something weird in the WDF osrusbfx2 sample that is
>>supplied
>>with the DDK. The IO functions in the example (read, write, control)
are
>>placed in pageable code sections.
>>
>>The documentation states that these functions are called at <=
DISPATCH
>>level unless the parent has been created with the execution level
>>attribute
>>set to WdfExecutionLevelPassive.
>>
>>
>
> That is a top-most driver. Read, write, and control will be invoked
> directly from user-mode applications, and will thus be called at a
> passive IRQL.
>
> –
> Tim Roberts, xxxxx@probo.com
> Providenza & Boekelheide, Inc.
>
>
>

—
Questions? First check the Kernel Driver FAQ at
http://www.osronline.com/article.cfm?id=256

You are currently subscribed to ntdev as: xxxxx@microsoft.com
To unsubscribe send a blank email to xxxxx@lists.osr.com

9

Are you using the WDK docset or the docset released on the web?

d

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Bruno van Dooren
Sent: Wednesday, January 18, 2006 12:10 PM
To: Windows System Software Devs Interest List
Subject: Re:[ntdev] WDF IO execution level question

Thanks.

The KMDF documentation is still incomplete (lots of broken links, and
structures and enums that are not in the index.

i still think that this tidbit should be explained, or at least linked
to in
the KMDF docs, so that it becomes more obvious. but at least now i know
the
answer.

thanks for your time.

kind regards,
Bruno.

“Doron Holan” wrote in message
news:xxxxx@ntdev…

Dispatch Routines and IRQLs

Most drivers’ dispatch routines are called in an arbitrary thread
context at IRQL = PASSIVE_LEVEL, with the following exceptions:

Any highest-level driver’s dispatch routines are called in the context
of the thread that originated the I/O request, which is commonly a
user-mode application thread.
In other words, the dispatch routines of file system drivers and other
highest-level drivers are called in a nonarbitrary thread context at
IRQL = PASSIVE_LEVEL.

The DispatchRead, DispatchWrite, and DispatchDeviceControl routines of
lowest-level device drivers, and of intermediate drivers layered above
them in the system paging path, can be called at IRQL = APC_LEVEL and in
an arbitrary thread context.
The DispatchRead and/or DispatchWrite routines, and any other routine
that also processes read and/or write requests in such a lowest-level
device or intermediate driver, must be resident at all times. These
driver routines can neither be pageable nor be part of a driver’s
pageable-image section; they must not access any pageable memory.
Furthermore, they should not be dependent on any blocking calls (such as
KeWaitForSingleObject with a nonzero time-out).

The DispatchPower routine of drivers in the hibernation and/or paging
paths can be called at IRQL DISPATCH_LEVEL. The DispatchPnP routines of
such drivers must be prepared to handle PnP
IRP_MN_DEVICE_USAGE_NOTIFICATION requests.
The DispatchPower routine of drivers that require inrush power at
start-up
can be called at IRQL DISPATCH_LEVEL


d

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Bruno van Dooren
Sent: Tuesday, January 17, 2006 1:22 PM
To: Windows System Software Devs Interest List
Subject: Re:[ntdev] WDF IO execution level question

is this documented somewhere? because it is not obvious from the
documentation that i could find.

kind regards,
Bruno.

“Tim Roberts” wrote in message news:xxxxx@ntdev…
> Bruno van Dooren wrote:
>
>>
>>I have noticed something weird in the WDF osrusbfx2 sample that is
>>supplied
>>with the DDK. The IO functions in the example (read, write, control)
are
>>placed in pageable code sections.
>>
>>The documentation states that these functions are called at <=
DISPATCH
>>level unless the parent has been created with the execution level
>>attribute
>>set to WdfExecutionLevelPassive.
>>
>>
>
> That is a top-most driver. Read, write, and control will be invoked
> directly from user-mode applications, and will thus be called at a
> passive IRQL.
>
> –
> Tim Roberts, xxxxx@probo.com
> Providenza & Boekelheide, Inc.
>
>
>

—
Questions? First check the Kernel Driver FAQ at
http://www.osronline.com/article.cfm?id=256

You are currently subscribed to ntdev as: xxxxx@microsoft.com
To unsubscribe send a blank email to xxxxx@lists.osr.com

—
Questions? First check the Kernel Driver FAQ at
http://www.osronline.com/article.cfm?id=256

You are currently subscribed to ntdev as: xxxxx@microsoft.com
To unsubscribe send a blank email to xxxxx@lists.osr.com

10

The WDF documents that were released on the web. the links came from the
same page as the KMDF DDK, if i recall correctly.
Are there different versions?

kind regards,
Bruno.

“Doron Holan” wrote in message
news:xxxxx@ntdev…
Are you using the WDK docset or the docset released on the web?

d

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Bruno van Dooren
Sent: Wednesday, January 18, 2006 12:10 PM
To: Windows System Software Devs Interest List
Subject: Re:[ntdev] WDF IO execution level question

Thanks.

The KMDF documentation is still incomplete (lots of broken links, and
structures and enums that are not in the index.

i still think that this tidbit should be explained, or at least linked
to in
the KMDF docs, so that it becomes more obvious. but at least now i know
the
answer.

thanks for your time.

kind regards,
Bruno.

“Doron Holan” wrote in message
news:xxxxx@ntdev…

Dispatch Routines and IRQLs

Most drivers’ dispatch routines are called in an arbitrary thread
context at IRQL = PASSIVE_LEVEL, with the following exceptions:

Any highest-level driver’s dispatch routines are called in the context
of the thread that originated the I/O request, which is commonly a
user-mode application thread.
In other words, the dispatch routines of file system drivers and other
highest-level drivers are called in a nonarbitrary thread context at
IRQL = PASSIVE_LEVEL.

The DispatchRead, DispatchWrite, and DispatchDeviceControl routines of
lowest-level device drivers, and of intermediate drivers layered above
them in the system paging path, can be called at IRQL = APC_LEVEL and in
an arbitrary thread context.
The DispatchRead and/or DispatchWrite routines, and any other routine
that also processes read and/or write requests in such a lowest-level
device or intermediate driver, must be resident at all times. These
driver routines can neither be pageable nor be part of a driver’s
pageable-image section; they must not access any pageable memory.
Furthermore, they should not be dependent on any blocking calls (such as
KeWaitForSingleObject with a nonzero time-out).

The DispatchPower routine of drivers in the hibernation and/or paging
paths can be called at IRQL DISPATCH_LEVEL. The DispatchPnP routines of
such drivers must be prepared to handle PnP
IRP_MN_DEVICE_USAGE_NOTIFICATION requests.
The DispatchPower routine of drivers that require inrush power at
start-up
can be called at IRQL DISPATCH_LEVEL


d

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Bruno van Dooren
Sent: Tuesday, January 17, 2006 1:22 PM
To: Windows System Software Devs Interest List
Subject: Re:[ntdev] WDF IO execution level question

is this documented somewhere? because it is not obvious from the
documentation that i could find.

kind regards,
Bruno.

“Tim Roberts” wrote in message news:xxxxx@ntdev…
> Bruno van Dooren wrote:
>
>>
>>I have noticed something weird in the WDF osrusbfx2 sample that is
>>supplied
>>with the DDK. The IO functions in the example (read, write, control)
are
>>placed in pageable code sections.
>>
>>The documentation states that these functions are called at <=
DISPATCH
>>level unless the parent has been created with the execution level
>>attribute
>>set to WdfExecutionLevelPassive.
>>
>>
>
> That is a top-most driver. Read, write, and control will be invoked
> directly from user-mode applications, and will thus be called at a
> passive IRQL.
>
> –
> Tim Roberts, xxxxx@probo.com
> Providenza & Boekelheide, Inc.
>
>
>

—
Questions? First check the Kernel Driver FAQ at
http://www.osronline.com/article.cfm?id=256

You are currently subscribed to ntdev as: xxxxx@microsoft.com
To unsubscribe send a blank email to xxxxx@lists.osr.com

—
Questions? First check the Kernel Driver FAQ at
http://www.osronline.com/article.cfm?id=256

You are currently subscribed to ntdev as: xxxxx@microsoft.com
To unsubscribe send a blank email to xxxxx@lists.osr.com

11

The WDK has older docs b/c it is not in sync with the web release, so I
wanted to make sure you were looking at the right doc set. Whenever you
have feedback on the help, you should use the “Send feedback on this
topic” at the bottom of the page. It will go to the right doc writer
and the feedback is taken into consideration when the documentation is
revised for the next release.

I will fwd this feedback to the doc writer.

d

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Bruno van Dooren
Sent: Wednesday, January 18, 2006 1:52 PM
To: Windows System Software Devs Interest List
Subject: Re:[ntdev] WDF IO execution level question

The WDF documents that were released on the web. the links came from the

same page as the KMDF DDK, if i recall correctly.
Are there different versions?

kind regards,
Bruno.

“Doron Holan” wrote in message
news:xxxxx@ntdev…
Are you using the WDK docset or the docset released on the web?

d

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Bruno van Dooren
Sent: Wednesday, January 18, 2006 12:10 PM
To: Windows System Software Devs Interest List
Subject: Re:[ntdev] WDF IO execution level question

Thanks.

The KMDF documentation is still incomplete (lots of broken links, and
structures and enums that are not in the index.

i still think that this tidbit should be explained, or at least linked
to in
the KMDF docs, so that it becomes more obvious. but at least now i know
the
answer.

thanks for your time.

kind regards,
Bruno.

“Doron Holan” wrote in message
news:xxxxx@ntdev…

Dispatch Routines and IRQLs

Most drivers’ dispatch routines are called in an arbitrary thread
context at IRQL = PASSIVE_LEVEL, with the following exceptions:

Any highest-level driver’s dispatch routines are called in the context
of the thread that originated the I/O request, which is commonly a
user-mode application thread.
In other words, the dispatch routines of file system drivers and other
highest-level drivers are called in a nonarbitrary thread context at
IRQL = PASSIVE_LEVEL.

The DispatchRead, DispatchWrite, and DispatchDeviceControl routines of
lowest-level device drivers, and of intermediate drivers layered above
them in the system paging path, can be called at IRQL = APC_LEVEL and in
an arbitrary thread context.
The DispatchRead and/or DispatchWrite routines, and any other routine
that also processes read and/or write requests in such a lowest-level
device or intermediate driver, must be resident at all times. These
driver routines can neither be pageable nor be part of a driver’s
pageable-image section; they must not access any pageable memory.
Furthermore, they should not be dependent on any blocking calls (such as
KeWaitForSingleObject with a nonzero time-out).

The DispatchPower routine of drivers in the hibernation and/or paging
paths can be called at IRQL DISPATCH_LEVEL. The DispatchPnP routines of
such drivers must be prepared to handle PnP
IRP_MN_DEVICE_USAGE_NOTIFICATION requests.
The DispatchPower routine of drivers that require inrush power at
start-up
can be called at IRQL DISPATCH_LEVEL


d

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Bruno van Dooren
Sent: Tuesday, January 17, 2006 1:22 PM
To: Windows System Software Devs Interest List
Subject: Re:[ntdev] WDF IO execution level question

is this documented somewhere? because it is not obvious from the
documentation that i could find.

kind regards,
Bruno.

“Tim Roberts” wrote in message news:xxxxx@ntdev…
> Bruno van Dooren wrote:
>
>>
>>I have noticed something weird in the WDF osrusbfx2 sample that is
>>supplied
>>with the DDK. The IO functions in the example (read, write, control)
are
>>placed in pageable code sections.
>>
>>The documentation states that these functions are called at <=
DISPATCH
>>level unless the parent has been created with the execution level
>>attribute
>>set to WdfExecutionLevelPassive.
>>
>>
>
> That is a top-most driver. Read, write, and control will be invoked
> directly from user-mode applications, and will thus be called at a
> passive IRQL.
>
> –
> Tim Roberts, xxxxx@probo.com
> Providenza & Boekelheide, Inc.
>
>
>

—
Questions? First check the Kernel Driver FAQ at
http://www.osronline.com/article.cfm?id=256

You are currently subscribed to ntdev as: xxxxx@microsoft.com
To unsubscribe send a blank email to xxxxx@lists.osr.com

—
Questions? First check the Kernel Driver FAQ at
http://www.osronline.com/article.cfm?id=256

You are currently subscribed to ntdev as: xxxxx@microsoft.com
To unsubscribe send a blank email to xxxxx@lists.osr.com

—
Questions? First check the Kernel Driver FAQ at
http://www.osronline.com/article.cfm?id=256

You are currently subscribed to ntdev as: xxxxx@microsoft.com
To unsubscribe send a blank email to xxxxx@lists.osr.com