366.7 KB - Evernote

Effect of User Mode APCs on Kernel Wait Functions
The previous section brings us to an interesting detail about the documented DDK wait functions.
Consider, for instance, the DDK help about KeWaitForSingleObject: among the possible return
values, STATUS_USER_APC is listed with the following description:
“The wait was interrupted to deliver a user asynchronous procedure call (APC) to the calling thread.”
The point is, the user APC has not yet been delivered: it will be, when the thread will re-enter user
mode.
Thus, when KeWaitForSingleObject returns, the APC has merely aborted the wait, but it is still to be
delivered. The wait has been aborted so that the thread can return to user mode and, thanks to
UserApcPending being set, deliver the APC.
If the thread were to stay in kernel mode, for instance by entering another wait, the APC would remain
pending.
User Mode APC Delivery Test in The Sample Driver
The sample driver accompanying this article shows this behaviour, by testing different wait cases. The
driver dispatch function for this test is called ApcUserModeTest.
This function creates a separate thread which will queue the APC to the one executing it, then enters
an alertable user-mode wait. The APC-requesting thread executes a function named ApcRequester.
When ApcRequester queue the APC to the original thread, the latter returns from
KeWaitForSingleObject with STATUS_USER_APC. However, the APC has not yet been delivered
and we can confirm this, because the APC kernel routine, when called, writes “Hello from the USER
APC kernel routine” on the debugger console. We will see that this happens only after
ApcUserModeTest has returned to user mode.
Before returning, ApcUserModeTest shows a few more interesting cases. First, it tries again to enter
an alertable user-mode wait with KeWaitForSingleObject. However, the function immediately returns
with STATUS_USER_APC. Thus, once a thread has user APCs pending, it simply can’t enter such a
wait.
It then tries a non-alertable user mode wait and, interestingly, the result is the same. This means
alertability matters only when APCs are requested for a thread which is already waiting: the thread is
only awakened if the wait is alertable. On the other hand, alertable or not, a thread can’t enter a user
mode wait if it already has pending user APCs.
Finally, ApcUserModeTest tries a non-alertable kernel mode wait and this time the thread is put to
sleep, regardless of the pending APCs.
After all these tests, ApcUserModeTest terminates, the thread returns to user mode and only then the
APC is dispatched and we see the debug message from its KernelMode routine.
Earlier, when examining nt!KiInsertQueueApc for user APCs, we reasoned that the wait functions
would have had to account for the fact that a thread could call them after APCs have been queued for
it. This follows from the fact that, for not-waiting threads, nt!KiInsertQueueApc does nothing more than
chaining the APCs to its list; the target thread is thus free to attempt to enter an alertable user mode
wait after this.
26