发布时间：2014-5-15 20:35
分类名称：Driver
VOID IoSetCompletionRoutine(
_In_ PIRP Irp,
_In_opt_ PIO_COMPLETION_ROUTINE CompletionRoutine,
_In_opt_ PVOID Context,
_In_ BOOLEAN InvokeOnSuccess,
_In_ BOOLEAN InvokeOnError,
_In_ BOOLEAN InvokeOnCancel
);
#define IoSetCompletionRoutine( Irp, Routine, CompletionContext, Success, Error, Cancel ) { \
PIO_STACK_LOCATION __irpSp; \
ASSERT( ((Success) | (Error) | (Cancel)) ? (Routine) != NULL : TRUE ); \
__irpSp = IoGetNextIrpStackLocation( (Irp) ); \
__irpSp->CompletionRoutine = (Routine); \
__irpSp->Context = (CompletionContext); \
__irpSp->Control = 0; \
if ((Success)) { __irpSp->Control = SL_INVOKE_ON_SUCCESS; } \
if ((Error)) { __irpSp->Control |= SL_INVOKE_ON_ERROR; } \
if ((Cancel)) { __irpSp->Control |= SL_INVOKE_ON_CANCEL; } }
NTSTATUS CompletionRoutine(PDEVICE_OBJECT fdo, PIRP Irp, PVOID context)
{
return <some status code>;
}
IoSetCompletionRoutine installs the completion routine address and context argument in the next IO_STACK_LOCATION — that is, in the stack location in which the next lower driver will find its parameters. Consequently, the lowest-level driver in a particular stack of drivers doesn't dare attempt to install a completion routine. Doing so would be pretty futile, of course, because—by definition of lowest-level driver—there's no driver left to pass the request on to.
CompletionRoutine receives pointers to the device object and the IRP, and it also receives whichever context value you specified in the call to IoSetCompletionRoutine. Completion routines can be called at DISPATCH_LEVEL in an arbitrary thread context but can also be called at PASSIVE_LEVEL or APC_LEVEL. To accommodate the worst case (DISPATCH_LEVEL), completion routines therefore need to be in nonpaged memory and must call only service functions that are callable at or below DISPATCH_LEVEL. To accommodate the possibility of being called at a lower IRQL, however, a completion routine shouldn't call functions such as KeAcquireSpinLockAtDpcLevel that assume they're at DISPATCH_LEVEL to start with.
There are really just two possible return values from a completion routine:
IoCompleteRequest is responsible for calling all of the completion routines that drivers installed in their respective stack locations. The way the process works, as shown in the flowchart in the following figure.
注释：此流程可以参考IoCompleteRequest的代码实现，在我的其它文章中有。
Within a completion routine, a call to IoGetCurrentIrpStackLocation will retrieve the same stack pointer that was current when somebody called IoSetCompletionRoutine.（IoCompleteRequest在调用完成函数时，已经将IRP的CurrentStackLocation等成员加了一） You shouldn't rely in a completion routine on the contents of any lower stack location. To reinforce this rule, IoCompleteRequest zeroes most of the next location just before calling a completion routine.
IoMarkIrpPending
为何调用此函数（宏）？
为何又要在完成函数中加入如下代码？
if (Irp->PendingReturned) IoMarkIrpPending(Irp);
如果你能看懂IoCompleteRequest实现代码，这些问题都能找到答案。
以下从示例中说明：
KEVENT event;
IO_STATUS_BLOCK iosb;
KeInitializeEvent(&event, ...);
PIRP Irp = IoBuildDeviceIoControlRequest(..., &event, &iosb); // 构造一个同步IRP，IoBuildSynchronousFsdRequest也适用。
NTSTATUS status = IoCallDriver(SomeDeviceObject, Irp);
if (status == STATUS_PENDING) // 如果调用完，返回的是STATUS_PENDING，说明处理还未完成，需要继续等待。
{
KeWaitForSingleObject(&event, ...); // 等待异步完成，完成后，event会被激活，继续往下执行。
status = iosb.Status;
}
else
<cleanup IRP>
Call的这个Device的最上层派遣函数如果是：
NTSTATUS TopDriverDispatchSomething(PDEVICE_OBJECT fdo, PIRP Irp)
{
IoMarkIrpPending(Irp);
// do something, deliver IRP somewhere, and complete it later.
return STATUS_PENDING;
}
这种情况将正常工作，示例中，调用IoCallDriver后，直接进入TopDriverDispatchSomething，它将IRP加入处理队列后，返回STATUS_PENDING，表示IRP还未完成。IoCallDriver的返回值将是派遣函数的返回值，发现是STATUS_PENDING，调用KeWaitForSingleObject等待完成。
事件何时被激活？
IoCompleteRequest does this signaling indirectly by scheduling an APC to the same routine that performs the <cleanup IRP> step in the preceding pseudocode. That cleanup code will do many tasks, including calling IoFreeIrp to release the IRP and KeSetEvent to set the event on which the creator might be waiting. For some types of IRP, IoCompleteRequest will always schedule the APC. For other types of IRP, though, IoCompleteRequest will schedule the APC only if the SL_PENDING_RETURNED flag is set in the topmost stack location.
IoCompleteRequest发现IRP对应的最高层IO堆栈的flag中有SL_PENDING_RETURNED,将会schedule APC，APC中，将会激活Evnet。
IoMarkIrpPending is a macro whose only purpose is to set SL_PENDING_RETURNED in the current stack location.
#define IoMarkIrpPending( Irp ) ( \
IoGetCurrentIrpStackLocation( (Irp) )->Control |= SL_PENDING_RETURNED )
此示例中，设置的SL_PENDING_RETURNED只是本层，而且本层是最高层，所以没有问题。
Call的这个Device的不止一层，如果是：
NTSTATUS TopDriverDispatchSomething(PDEVICE_OBJECT fido,PIRP Irp)
{
PDEVICE_EXTENSION pdx =
(PDEVICE_EXTENSION) fido->DeviceExtension;
IoCopyCurrentIrpStackLocationToNext(Irp);
return IoCallDriver(pdx->LowerDeviceObject, Irp);
}
NTSTATUS SecondDriverDispatchSomething(PDEVICE_OBJECT fdo,PIRP Irp)
{
IoMarkIrpPending(Irp);
… …
return STATUS_PENDING;
}
设置的SL_PENDING_RETURNED只是本层（SecondDriverDispatchSomething），上层（TopDriverDispatchSomething）并没有此标志，需要不停传递到最上层。如果没有安装完成函数，这种传递在IoCompleteRequest中自动进行。如果安装了完成函数，则需要在完成函数中调用if (Irp->PendingReturned) IoMarkIrpPending(Irp); 来辅助向上传递（不知道微软为何要这么搞，估计是增加灵活性吧）。为何判断的是Irp->PendingReturned？因为IoCompleteRequest，每次完成函数前会先设置此标识：Irp->PendingReturned = stackPointer->Control & SL_PENDING_RETURNED; 来保存堆栈内到底有无SL_PENDING_RETURNED标志。
现在，如果将IoCopyCurrentIrpStackLocationToNext替换为IoSkipCurrentIrpStackLocation，仍然能够正常工作，因为IoMarkIrpPending设置的是TopDriverDispatchSomething这层的堆栈，如果下面还有跟多层呢？也一样。只要有一层被设置为，则会从此层开始，层层传递。
Call的这个Device安装了完成函数，如果是：
NTSTATUS TopDriverDispatchSomething(PDEVICE_OBJECT fido,PIRP Irp)
{
PDEVICE_EXTENSION pdx =
(PDEVICE_EXTENSION) fido->DeviceExtension;
IoCopyCurrentIrpStackLocationToNext(Irp);
IoSetCompletionRoutine(Irp, TopDriverCompletionRoutine, ...);
return IoCallDriver(pdx->LowerDeviceObject, Irp);
}
NTSTATUS SecondDriverDispatchSomething(PDEVICE_OBJECT fdo,PIRP Irp)
{
IoMarkIrpPending(Irp);
… …
return STATUS_PENDING;
}
NTSTATUS TopDriverCompletionRoutine(PDEVICE_OBJECT fido,PIRP Irp, ...)
{
if (Irp->PendingReturned) // 向上传递
IoMarkIrpPending(Irp);
return STATUS_SUCCESS;
}
如果完成函数不调用IoMarkIrpPending，标识将不会传递到最上层。IoCompleteRequest最终不会schedule APC，event无法触发。
调用IoMarkIrpPending错误的情况：
Bad Idea # 1—Conditionally Call IoMarkIrpPending in the Dispatch Routine
NTSTATUS TopDriverDispatchSomething(PDEVICE_OBJECT fido,PIRP Irp)
{
PDEVICE_EXTENSION pdx =
(PDEVICE_EXTENSION) fido->DeviceExtension;
IoCopyCurrentIrpStackLocationToNext(Irp);
IoSetCompletionRoutine(Irp, TopDriverCompletionRoutine, ...);
NTSTATUS status = IoCallDriver(pdx->LowerDeviceObject, Irp);
if (status == STATUS_PENDING)
IoMarkIrpPending(Irp); // <== Argh! Don't do this!
return status;
}
The reason this is a bad idea is that the IRP might already be complete, and someone might already have called IoFreeIrp, by the time IoCallDriver returns. You must treat the pointer as poison as soon as you give it away to a function that might complete the IRP.
Bad idea # 2—Always Call IoMarkIrpPending in the Dispatch Routine
Here the dispatch routine unconditionally calls IoMarkIrpPending and then returns whichever value IoCallDriver returns:
NTSTATUS TopDriverDispatchSomething(PDEVICE_OBJECT fido,PIRP Irp)
{
PDEVICE_EXTENSION pdx =
(PDEVICE_EXTENSION) fido->DeviceExtension;
IoMarkIrpPending(Irp); // <== Don't do this either!
IoCopyCurrentIrpStackLocationToNext(Irp);
IoSetCompletionRoutine(Irp, TopDriverCompletionRoutine, ...);
return IoCallDriver(pdx->LowerDeviceObject, Irp);
}
This is a bad idea if the next driver happens to complete the IRP in its dispatch routine and returns a nonpending status. In this situation, IoCompleteRequest will cause all the completion cleanup to happen. When you return a nonpending status, the I/O Manager routine that originated the IRP might call the same completion cleanup routine a second time. This leads to a double-completion bug check.
Remember always to pair the call to IoMarkIrpPending with returning STATUS_PENDING. That is, do both or neither, but never one without the other.
Bad Idea # 3—Call IoMarkPending Regardless of the Return Code from the Completion Routine
NTSTATUS TopDriverDispatchSomething(PDEVICE_OBJECT fido,PIRP Irp)
{
PDEVICE_EXTENSION pdx =
(PDEVICE_EXTENSION) fido->DeviceExtension;
KEVENT event;
KeInitializeEvent(&event, NotificationEvent, FALSE);
IoCopyCurrentIrpStackLocationToNext(Irp);
IoSetCompletionRoutine(Irp, TopDriverCompletionRoutine, &event,
TRUE, TRUE, TRUE);
IoCallDriver(pdx->LowerDeviceObject, Irp);
KeWaitForSingleObject(&event, ...);
Irp->IoStatus.Status = status;
IoCompleteRequest(Irp, IO_NO_INCREMENT);
return status;
}
NTSTATUS TopDriverCompletionRoutine(PDEVICE_OBJECT fido,PIRP Irp, PVOID pev)
{
if (Irp->PendingReturned)
IoMarkIrpPending(Irp); // <== oops
KeSetEvent((PKEVENT) pev, IO_NO_INCREMENT, FALSE);
return STATUS_MORE_PROCESSING_REQUIRED;
}
What's probably going on here is that the programmer wants to forward the IRP synchronously and then resume processing the IRP after the lower driver finishes with it. (See IRP-handling scenario 7 at the end of this chapter.) That's how you're supposed to handle certain PnP IRPs, in fact. This example can cause a double-completion bug check, though, if the lower driver happens to return STATUS_PENDING. This is actually the same scenario as in the previous bad idea: your dispatch routine is returning a nonpending status, but your stack frame has the pending flag set. People often get away with this bad idea, which existed in the IRP_MJ_PNP handlers of many early Windows 2000 DDK samples, because no one ever posts a Plug and Play IRP. (Therefore, PendingReturned is never set, and the incorrect call to IoMarkIrpPending never happens.)
Avoid these problems by remembering not to call IoMarkIrpPending from a completion routine that returns STATUS_MORE_PRO?CESSING_REQUIRED.