Clarification about KeWaitForSingleObject return values

I’ve looked in the DDK and searched the forum. I’ve noticed that a lot of
code I’ve seen that calls KeWaitForSingleObject with Alertable set to FALSE
and processor mode set to KernelMode and doesn’t check the return value of
KeWaitForSingleObject. It makes sense to me that KeWaitForSingleObject
would never fail when called with these parameters. Is this a valid
assumption? If not, where can I find information on why it would fail so
that I can know how to handle it properly.

In my scenario, I’m doing the wait in a system thread I created or in a
dispatch for an IOCTL. If KeWaitForSingleObject can fail in the scenario
described above, can it fail in my system thread or dispatch. From the
documentation, I assume that I should never see this fail in my system
thread (unless may be kill it), but if the thread that sent the IOCTL
terminates during the wait?

Thanks,

Jonathan Ludwig

If you are waiting in a non system thread context, ie the context of the
app which is sending the IOCTL, you must call wrap the wait call with
KeEnterCriticalRegion/KeLeaveCriticalRegion. By wrapping it, you will
prevent normal APCs from being processed on that thread. Thread
suspension is achieved by a normal APC. The thread cannot terminate if
it is stuck in a kernel/non altertable wait.

The NTSTATUS value is there for you to determine the result of wait (ie
if you were alerted, the wait timed out, the wait succeeded). There is
no validation of the object you are waiting on nor is there an NTSTATUS
value returned for an invalid parameter.

d

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Jonathan Ludwig
Sent: Wednesday, May 25, 2005 12:56 PM
To: Windows System Software Devs Interest List
Subject: [ntdev] Clarification about KeWaitForSingleObject return values

I’ve looked in the DDK and searched the forum. I’ve noticed that a lot
of
code I’ve seen that calls KeWaitForSingleObject with Alertable set to
FALSE
and processor mode set to KernelMode and doesn’t check the return value
of
KeWaitForSingleObject. It makes sense to me that KeWaitForSingleObject
would never fail when called with these parameters. Is this a valid
assumption? If not, where can I find information on why it would fail
so
that I can know how to handle it properly.

In my scenario, I’m doing the wait in a system thread I created or in a
dispatch for an IOCTL. If KeWaitForSingleObject can fail in the
scenario
described above, can it fail in my system thread or dispatch. From the
documentation, I assume that I should never see this fail in my system
thread (unless may be kill it), but if the thread that sent the IOCTL
terminates during the wait?

Thanks,

Jonathan Ludwig


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

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

> I’ve looked in the DDK and searched the forum. I’ve noticed that a lot of

code I’ve seen that calls KeWaitForSingleObject with Alertable set to FALSE
and processor mode set to KernelMode and doesn’t check the return value of
KeWaitForSingleObject. It makes sense to me that KeWaitForSingleObject
would never fail when called with these parameters. Is this a valid
assumption? If not, where can I find information on why it would fail so

Valid return values of KeWaitForSingleObject:

  • STATUS_ALERTED - wait DID occured and was interrupted by KeAlertThread. Can
    occur only if the wait parameters are Alertable=TRUE and, if wait parameter
    ProcessorMode is KernelMode, then KeAlertThread ProcessorMode is not user mode
    (alert for a mode higher-privileged then the wait mode is a no-op).
  • STATUS_USER_APC - can only occur if ProcessorMode is UserMode, wait was
    interrupted by the user APC.
  • STATUS_ABANDONED_WAIT_0 - you’re waiting on a busy mutant which is destroyed
    while busy.
  • STATUS_TIMEOUT - as documented
  • STATUS_SUCCESS in all other cases

So, you’re correct :slight_smile:


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

>app which is sending the IOCTL, you must call wrap the wait call with

KeEnterCriticalRegion/KeLeaveCriticalRegion.

Am I wrong that, with non-alertable KernelMode wait, it cannot be interrupted
by any APCs even in the critical region and on PASSIVE_LEVEL? I remember that
special kernel APCs (IopCompleteRequest) can interrupt it for a while and
restart it without the wait routine returning.

Using events or ERESOURCEs for mutual exclusiveness will surely require these
wrappers, since otherwise the thread can be suspended or terminated while
holding a lock. Not so with usual waits. Also not so with FAST_MUTEX, who
raises to APC_LEVEL internally (which includes all KeEnterCriticalRegion
semantics and even adds some more IopCompleteRequest is also blocked).

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

No, I am 99% sure it can still be interrupted. The folks who know this
for sure have been advertising at winhec/DDC for a few years that you
need to do this even for a KernelMode/FALSE wait, so I am basing my
statement on that repeated message. I know tt can still be interrupted
by a special kernel mode APC if you don’t enter the CR.

d

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Maxim S. Shatskih
Sent: Wednesday, May 25, 2005 1:25 PM
To: Windows System Software Devs Interest List
Subject: Re: [ntdev] Clarification about KeWaitForSingleObject return
values

app which is sending the IOCTL, you must call wrap the wait call with
KeEnterCriticalRegion/KeLeaveCriticalRegion.

Am I wrong that, with non-alertable KernelMode wait, it cannot be
interrupted
by any APCs even in the critical region and on PASSIVE_LEVEL? I remember
that
special kernel APCs (IopCompleteRequest) can interrupt it for a while
and
restart it without the wait routine returning.

Using events or ERESOURCEs for mutual exclusiveness will surely
require these
wrappers, since otherwise the thread can be suspended or terminated
while
holding a lock. Not so with usual waits. Also not so with FAST_MUTEX,
who
raises to APC_LEVEL internally (which includes all KeEnterCriticalRegion
semantics and even adds some more IopCompleteRequest is also blocked).

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@windows.microsoft.com
To unsubscribe send a blank email to xxxxx@lists.osr.com

Wait, the DDK documentation for KeEnterCriticalRegion says it disables,
normal kernel APC’s, but not special kernel APC’s. I would like to
understand this better, but I can work around it.

Right now my dispatch receives a custom device control IRP. The processing
for this IRP must happen in a system thread at passive level, so I signal an
event (A) to my system thread to do the processing and wait on a second
event (B). My system thread wakes up on the first event (A), does the
processing and then signals the other event (B) which the dispatch thread is
waiting on. If the wait in my dispatch thread for event B fails, I would
like to understand what made it fail so I can know if I need to wait on
event (B) again. If this is problematic, I can just pend the IRP, and pass
it on to the system thread to complete. I’d rather do this because I’ll
have to add cancelation support for this IRP. It’s a custom IOCTL that’s
only called just a few times so I don’t care about holding the thread making
the IOCTL; it sends the IOCTL synchronously and can do nothing further until
the IOCTL completes.

This seems like a really basic question, I’ve looked in all my driver books
and the DDK and cannot find an explanation of this. But, I have seen a lot
of code that does this and assumes that KeWaitForSingleObject() is going to
succeed.

Thanks,

Jonathan Ludwig

“Doron Holan” wrote in message
news:xxxxx@ntdev…
No, I am 99% sure it can still be interrupted. The folks who know this
for sure have been advertising at winhec/DDC for a few years that you
need to do this even for a KernelMode/FALSE wait, so I am basing my
statement on that repeated message. I know tt can still be interrupted
by a special kernel mode APC if you don’t enter the CR.

d

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Maxim S. Shatskih
Sent: Wednesday, May 25, 2005 1:25 PM
To: Windows System Software Devs Interest List
Subject: Re: [ntdev] Clarification about KeWaitForSingleObject return
values

>app which is sending the IOCTL, you must call wrap the wait call with
>KeEnterCriticalRegion/KeLeaveCriticalRegion.

Am I wrong that, with non-alertable KernelMode wait, it cannot be
interrupted
by any APCs even in the critical region and on PASSIVE_LEVEL? I remember
that
special kernel APCs (IopCompleteRequest) can interrupt it for a while
and
restart it without the wait routine returning.

Using events or ERESOURCEs for mutual exclusiveness will surely
require these
wrappers, since otherwise the thread can be suspended or terminated
while
holding a lock. Not so with usual waits. Also not so with FAST_MUTEX,
who
raises to APC_LEVEL internally (which includes all KeEnterCriticalRegion
semantics and even adds some more IopCompleteRequest is also blocked).

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@windows.microsoft.com
To unsubscribe send a blank email to xxxxx@lists.osr.com

The return values you get from KeWaitForSingleObject are not errors. Note
that NT_SUCCESS will return true, or SUCCESS, an all of them. What you get
back is more or less an informational status that you may or may not need to
use in your logic.


The personal opinion of
Gary G. Little

“Jonathan Ludwig” wrote in message
news:xxxxx@ntdev…
> I’ve looked in the DDK and searched the forum. I’ve noticed that a lot of
> code I’ve seen that calls KeWaitForSingleObject with Alertable set to
> FALSE and processor mode set to KernelMode and doesn’t check the return
> value of KeWaitForSingleObject. It makes sense to me that
> KeWaitForSingleObject would never fail when called with these parameters.
> Is this a valid assumption? If not, where can I find information on why
> it would fail so that I can know how to handle it properly.
>
> In my scenario, I’m doing the wait in a system thread I created or in a
> dispatch for an IOCTL. If KeWaitForSingleObject can fail in the scenario
> described above, can it fail in my system thread or dispatch. From the
> documentation, I assume that I should never see this fail in my system
> thread (unless may be kill it), but if the thread that sent the IOCTL
> terminates during the wait?
>
> Thanks,
>
> Jonathan Ludwig
>
>

This cough medicine crossed my wires.

The KeWaitForSingleObject with KernelMode/FALSE will not be suspendable
while you are in the guts of the function call, but you will be
suspendable as soon as it satisfies the wait. That means that you are
now holding the KEVENT and there is a window of time where you can be
infinitely suspended holding this resource, causing lots of problems.
This is why you enter the CR before the wait, it is not that you need to
protect yourself during the wait, you need to protect yourself from
suspend after the wait has been satisfied and you own the resource.

Like I said before, the wait will only fail if you specify a timeout in
this case. The KEVENT you are waiting on is probably in your device
extension or on the stack, so there will be no reason for the wait to
fail.

I would implement a cancel routine and stop mucking about with this. In
the end, your life will be easier. Use the IO CSQ library and do not
reinvent the wheel.

d

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Jonathan Ludwig
Sent: Wednesday, May 25, 2005 2:33 PM
To: Windows System Software Devs Interest List
Subject: Re:[ntdev] Clarification about KeWaitForSingleObject return
values

Wait, the DDK documentation for KeEnterCriticalRegion says it disables,
normal kernel APC’s, but not special kernel APC’s. I would like to
understand this better, but I can work around it.

Right now my dispatch receives a custom device control IRP. The
processing
for this IRP must happen in a system thread at passive level, so I
signal an
event (A) to my system thread to do the processing and wait on a second
event (B). My system thread wakes up on the first event (A), does the
processing and then signals the other event (B) which the dispatch
thread is
waiting on. If the wait in my dispatch thread for event B fails, I
would
like to understand what made it fail so I can know if I need to wait on
event (B) again. If this is problematic, I can just pend the IRP, and
pass
it on to the system thread to complete. I’d rather do this because I’ll

have to add cancelation support for this IRP. It’s a custom IOCTL
that’s
only called just a few times so I don’t care about holding the thread
making
the IOCTL; it sends the IOCTL synchronously and can do nothing further
until
the IOCTL completes.

This seems like a really basic question, I’ve looked in all my driver
books
and the DDK and cannot find an explanation of this. But, I have seen a
lot
of code that does this and assumes that KeWaitForSingleObject() is going
to
succeed.

Thanks,

Jonathan Ludwig

“Doron Holan” wrote in message
news:xxxxx@ntdev…
No, I am 99% sure it can still be interrupted. The folks who know this
for sure have been advertising at winhec/DDC for a few years that you
need to do this even for a KernelMode/FALSE wait, so I am basing my
statement on that repeated message. I know tt can still be interrupted
by a special kernel mode APC if you don’t enter the CR.

d

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Maxim S. Shatskih
Sent: Wednesday, May 25, 2005 1:25 PM
To: Windows System Software Devs Interest List
Subject: Re: [ntdev] Clarification about KeWaitForSingleObject return
values

>app which is sending the IOCTL, you must call wrap the wait call with
>KeEnterCriticalRegion/KeLeaveCriticalRegion.

Am I wrong that, with non-alertable KernelMode wait, it cannot be
interrupted
by any APCs even in the critical region and on PASSIVE_LEVEL? I remember
that
special kernel APCs (IopCompleteRequest) can interrupt it for a while
and
restart it without the wait routine returning.

Using events or ERESOURCEs for mutual exclusiveness will surely
require these
wrappers, since otherwise the thread can be suspended or terminated
while
holding a lock. Not so with usual waits. Also not so with FAST_MUTEX,
who
raises to APC_LEVEL internally (which includes all KeEnterCriticalRegion
semantics and even adds some more IopCompleteRequest is also blocked).

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@windows.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@windows.microsoft.com
To unsubscribe send a blank email to xxxxx@lists.osr.com

CR has not effect on special kernel APCs.

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

----- Original Message -----
From: “Doron Holan”
To: “Windows System Software Devs Interest List”
Sent: Thursday, May 26, 2005 12:53 AM
Subject: RE: [ntdev] Clarification about KeWaitForSingleObject return values

No, I am 99% sure it can still be interrupted. The folks who know this
for sure have been advertising at winhec/DDC for a few years that you
need to do this even for a KernelMode/FALSE wait, so I am basing my
statement on that repeated message. I know tt can still be interrupted
by a special kernel mode APC if you don’t enter the CR.

d

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Maxim S. Shatskih
Sent: Wednesday, May 25, 2005 1:25 PM
To: Windows System Software Devs Interest List
Subject: Re: [ntdev] Clarification about KeWaitForSingleObject return
values

>app which is sending the IOCTL, you must call wrap the wait call with
>KeEnterCriticalRegion/KeLeaveCriticalRegion.

Am I wrong that, with non-alertable KernelMode wait, it cannot be
interrupted
by any APCs even in the critical region and on PASSIVE_LEVEL? I remember
that
special kernel APCs (IopCompleteRequest) can interrupt it for a while
and
restart it without the wait routine returning.

Using events or ERESOURCEs for mutual exclusiveness will surely
require these
wrappers, since otherwise the thread can be suspended or terminated
while
holding a lock. Not so with usual waits. Also not so with FAST_MUTEX,
who
raises to APC_LEVEL internally (which includes all KeEnterCriticalRegion
semantics and even adds some more IopCompleteRequest is also blocked).

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@windows.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: unknown lmsubst tag argument: ‘’
To unsubscribe send a blank email to xxxxx@lists.osr.com