发布时间：2014-5-16 13:58
分类名称：Driver
下面是IoStartPacket，IoStartNextPacket, IoCancelIrp, 及用户实现的StartIo, CancelIo例程。
VOID
IoStartPacket(
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp,
IN PULONG Key OPTIONAL,
IN PDRIVER_CANCEL CancelFunction OPTIONAL
)
/*++
Routine Description:
This routine attempts to start the specified packet request (IRP) on the
specified device. If the device is already busy, then the packet is
simply queued to the device queue. If a non-NULL CancelFunction is
supplied, it will be put in the IRP. If the IRP has been canceled, the
CancelFunction will be called after the IRP has been inserted into the
queue or made the current packet.
Arguments:
DeviceObject - Pointer to device object itself.
Irp - I/O Request Packet which should be started on the device.
Key - Key to be used in inserting packet into device queue; optional
(if not specified, then packet is inserted at the tail).
CancelFunction - Pointer to an optional cancel routine.
Return Value:
None.
--*/
{
KIRQL oldIrql;
KIRQL cancelIrql = PASSIVE_LEVEL;
BOOLEAN i;
//
// Raise the IRQL of the processor to dispatch level for synchronization.
//
// 在DISPATCH_LEVEL下运行
KeRaiseIrql( DISPATCH_LEVEL, &oldIrql );
//
// If the driver has indicated that packets are cancelable, then acquire
// the cancel spinlock and set the address of the cancel function to
// indicate that the packet is not only cancelable, but indicates what
// routine to invoke should it be cancelled.
//
if (CancelFunction) {
IoAcquireCancelSpinLock( &cancelIrql );
Irp->CancelRoutine = CancelFunction;
}
//
// If a key parameter was specified, then insert the request into the
// work queue according to the key; otherwise, simply insert it at the
// tail.
//
if (Key) {
i = KeInsertByKeyDeviceQueue( &DeviceObject->DeviceQueue,
&Irp->Tail.Overlay.DeviceQueueEntry,
*Key );
} else {
i = KeInsertDeviceQueue( &DeviceObject->DeviceQueue,
&Irp->Tail.Overlay.DeviceQueueEntry );
}
//
// If the packet was not inserted into the queue, then this request is
// now the current packet for this device. Indicate so by storing its
// address in the current IRP field, and begin processing the request.
//
// 如果没有Insert，说明当前IRP链中是空的，可以执行。
// 如果Inserted，说明目前有正在处理的IRP，只是简单的将IRP进行排队。
if (!i) {
// 设置当前的IRP
DeviceObject->CurrentIrp = Irp;
if (CancelFunction) {
//
// If the driver does not want the IRP in the cancelable state
// then set the routine to NULL
//
if (DeviceObject->DeviceObjectExtension->StartIoFlags & DOE_STARTIO_NO_CANCEL) {
Irp->CancelRoutine = NULL;
}
IoReleaseCancelSpinLock( cancelIrql );
}
//
// Invoke the driver's start I/O routine to get the request going on the device.
// The StartIo routine should handle the cancellation.
//
DeviceObject->DriverObject->DriverStartIo( DeviceObject, Irp );
} else {
//
// The packet was successfully inserted into the device's work queue.
// Make one last check to determine whether or not the packet has
// already been marked cancelled. If it has, then invoke the
// driver's cancel routine now. Note that because the cancel
// spinlock is currently being held, an attempt to cancel the request
// from another processor at this point will simply wait until this
// routine is finished, and then get it cancelled.
//
if (CancelFunction) {
if (Irp->Cancel) {
Irp->CancelIrql = cancelIrql;
Irp->CancelRoutine = (PDRIVER_CANCEL) NULL;
CancelFunction( DeviceObject, Irp );
} else {
IoReleaseCancelSpinLock( cancelIrql );
}
}
}
//
// Restore the IRQL back to its value upon entry to this function before
// returning to the caller.
//
KeLowerIrql( oldIrql );
}
VOID
IopStartNextPacket(
IN PDEVICE_OBJECT DeviceObject,
IN LOGICAL Cancelable
)
/*++
Routine Description:
This routine is invoked to dequeue the next packet (IRP) from the
specified device work queue and invoke the device driver's start I/O
routine for it. If the Cancelable parameter is TRUE, then the update of
current IRP is synchronized using the cancel spinlock.
Arguments:
DeviceObject - Pointer to device object itself.
Cancelable - Indicates that IRPs in the device queue may be cancelable.
Return Value:
None.
--*/
{
KIRQL cancelIrql = PASSIVE_LEVEL;
PIRP irp;
PKDEVICE_QUEUE_ENTRY packet;
//
// Begin by checking to see whether or not this driver's requests are
// to be considered cancelable. If so, then acquire the cancel spinlock.
//
if (Cancelable) {
IoAcquireCancelSpinLock( &cancelIrql );
}
//
// Clear the current IRP field before starting another request.
//
DeviceObject->CurrentIrp = (PIRP) NULL;
//
// Remove the next packet from the head of the queue. If a packet was
// found, then process it.
//
packet = KeRemoveDeviceQueue( &DeviceObject->DeviceQueue );
if (packet) {
irp = CONTAINING_RECORD( packet, IRP, Tail.Overlay.DeviceQueueEntry );
//
// A packet was located so make it the current packet for this
// device.
//
DeviceObject->CurrentIrp = irp;
if (Cancelable) {
//
// If the driver does not want the IRP in the cancelable state
// then set the routine to NULL
//
if (DeviceObject->DeviceObjectExtension->StartIoFlags & DOE_STARTIO_NO_CANCEL) {
irp->CancelRoutine = NULL;
}
IoReleaseCancelSpinLock( cancelIrql );
}
//
// Invoke the driver's start I/O routine for this packet.
//
DeviceObject->DriverObject->DriverStartIo( DeviceObject, irp );
} else {
//
// No packet was found, so simply release the cancel spinlock if
// it was acquired.
//
if (Cancelable) {
IoReleaseCancelSpinLock( cancelIrql );
}
}
}
BOOLEAN
KeInsertDeviceQueue (
__inout PKDEVICE_QUEUE DeviceQueue,
__inout PKDEVICE_QUEUE_ENTRY DeviceQueueEntry
)
/*++
Routine Description:
This function inserts a device queue entry at the tail of the specified
device queue. If the device is not busy, then it is set busy and the entry
is not placed in the device queue. Otherwise the specified entry is placed
at the end of the device queue.
Arguments:
DeviceQueue - Supplies a pointer to a control object of type device queue.
DeviceQueueEntry - Supplies a pointer to a device queue entry.
Return Value:
If the device is not busy, then a value of FALSE is returned. Otherwise a
value of TRUE is returned.
--*/
{
BOOLEAN Busy;
BOOLEAN Inserted;
KLOCK_QUEUE_HANDLE LockHandle;
ASSERT_DEVICE_QUEUE(DeviceQueue);
//
// Set inserted to FALSE and lock specified device queue.
//
// DeviceQueue是在IoCreateDevice中调用KeInitializeDeviceQueue来初始化的
Inserted = FALSE;
KiAcquireInStackQueuedSpinLockForDpc(&DeviceQueue->Lock, &LockHandle);
//
// Insert the specified device queue entry at the end of the device queue
// if the device queue is busy. Otherwise set the device queue busy and
// don't insert the device queue entry.
//
Busy = DeviceQueue->Busy;
DeviceQueue->Busy = TRUE;
if (Busy == TRUE) {
InsertTailList(&DeviceQueue->DeviceListHead,
&DeviceQueueEntry->DeviceListEntry);
Inserted = TRUE;
}
DeviceQueueEntry->Inserted = Inserted;
//
// Unlock specified device queue.
//
KiReleaseInStackQueuedSpinLockForDpc(&LockHandle);
return Inserted;
}
BOOLEAN
IoCancelIrp(
IN PIRP Irp
)
/*++
Routine Description:
This routine is invoked to cancel an individual I/O Request Packet.
It acquires the cancel spin lock, sets the cancel flag in the IRP, and
then invokes the cancel routine specified by the appropriate field in
the IRP, if a routine was specified. It is expected that the cancel
routine will release the cancel spinlock. If there is no cancel routine,
then the cancel spin lock is released.
Arguments:
Irp - Supplies a pointer to the IRP to be cancelled.
Return Value:
The function value is TRUE if the IRP was in a cancelable state (it
had a cancel routine), else FALSE is returned.
Notes:
It is assumed that the caller has taken the necessary action to ensure
that the packet cannot be fully completed before invoking this routine.
--*/
{
PDRIVER_CANCEL cancelRoutine;
KIRQL irql;
BOOLEAN returnValue;
ASSERT( Irp->Type == IO_TYPE_IRP );
if (IopVerifierOn) {
if (IOV_CANCEL_IRP(Irp, &returnValue)) {
return returnValue;
}
}
//
// Acquire the cancel spin lock.
//
IoAcquireCancelSpinLock( &irql );
//
// Set the cancel flag in the IRP.
//
Irp->Cancel = TRUE;
//
// Obtain the address of the cancel routine, and if one was specified,
// invoke it.
//
cancelRoutine = (PDRIVER_CANCEL) (ULONG_PTR) InterlockedExchangePointer( (PVOID *) &Irp->CancelRoutine,
NULL );
if (cancelRoutine) {
if (Irp->CurrentLocation > (CCHAR) (Irp->StackCount + 1)) {
KeBugCheckEx( CANCEL_STATE_IN_COMPLETED_IRP, (ULONG_PTR) Irp, (ULONG_PTR) cancelRoutine, 0, 0 );
}
Irp->CancelIrql = irql;
cancelRoutine( Irp->Tail.Overlay.CurrentStackLocation->DeviceObject,
Irp );
//
// The cancel spinlock should have been released by the cancel routine.
//
return(TRUE);
} else {
//
// There was no cancel routine, so release the cancel spinlock and
// return indicating the Irp was not currently cancelable.
//
IoReleaseCancelSpinLock( irql );
return(FALSE);
}
}
// 用户提供的StartIo
VOID StartIo(PDEVICE_OBJECT fdo, PIRP Irp)
{
KIRQL oldirql;
// 处理Irp被Cancel的情况。在IoStartPacket或IoStartNextPacket调用此函数StartIo前，
// 会先解锁IoAcquireCancelSpinLock。（微软防止StartIo占用过多时间，导致系统响应缓慢）
// 这样调用到IoAcquireCancelSpinLock之前，IRP可能会被IoCancelIrp取消，取消会调用OnCancel函数，fdo->CurrentIrp == Irp，
// 会释放IoReleaseCancelSpinLock(DISPATCH_LEVEL)，释放后就有两种情况：
// 1. 线程切换回来，上锁IoAcquireCancelSpinLock，此时Irp == fdo->CurrentIrp 但Irp->Cancel已经被设置为TRUE。
// 2. 线程仍然未切换回来，在OnCancel中继续运行调用了IoStartNextPacket，使得Irp != fdo->CurrentIrp，Irp->Cancel为TRUE。
// 这两种情况都说明IRP已经被取消，不应该继续执行。
IoAcquireCancelSpinLock(&oldirql);
if (Irp != fdo->CurrentIrp || Irp->Cancel)
{
IoReleaseCancelSpinLock(oldirql);
return;
}
else
{
IoSetCancelRoutine(Irp, NULL);
IoReleaseCancelSpinLock(oldirql);
}
...
}
// 用户提供的Cancel函数
VOID OnCancel(PDEVICE_OBJECT fdo, PIRP Irp)
{
// 如果正好执行到StartIo，但还没有上锁前的情况
if (fdo->CurrentIrp == Irp)
{
KIRQL oldirql = Irp->CancelIrql;
IoReleaseCancelSpinLock(DISPATCH_LEVEL);
IoStartNextPacket(fdo, TRUE);
KeLowerIrql(oldirql);
}
else // 如果取消的是一个正在排队的IRP，直接从链中Remove。
{
KeRemoveEntryDeviceQueue(&fdo->DeviceQueue, &Irp->Tail.Overlay.DeviceQueueEntry);
IoReleaseCancelSpinLock(Irp->CancelIrql);
}
CompleteRequest(Irp, STATUS_CANCELLED, 0);
}