IRP processing to avoid forgetting

Introduction

One of the most frequently done tasks in Windows Driver Model (WDM) drivers is sending input/output request packets (IRPs) from one driver to another driver. A driver either creates its own IRP and sends it to a lower driver, or the driver forwards the IRPs
That it has es from another driver that is attached abve.

This article discusses all the possible ways that a driver can send IRPs to a lower driver with annotated sample code. depending on the need, driver writers can follow one of the templates given in this article and not be affected by old IRP handling rules.
Before you examine the varous scenarios, note the following about the status that is returned by completion routines:

An IRP completion routine can return either status_more_processing_required or STATUS_SUCCESS.

The I/O manager uses the following rules when it examines the status:

• If the status is status_more_processing_required, stop completing the IRP, leave the stack location unchanged and return.
• If the status is anything other than status_more_processing_required, continue completing the IRP upward.

Because the I/O manager does not have to know which non-STATUS_MORE_PROCESSING_REQUIRED value is used, use STATUS_SUCCESS (because the value 0 is efficiently loadable on most processor ubuntures ).

To improve the readability of the Code, Windows XP SP1 and Windows XP. net driver development kit ntddk. H and WDM. h header files will have a new # define that is named status_continue_completion, Which is aliased
To STATUS_SUCCESS as shown in the following code:

// // This value should be returned from completion routines to continue// completing the IRP upwards. Otherwise, STATUS_MORE_PROCESSING_REQUIRED// should be returned.// #define STATUS_CONTINUE_COMPLETION      STATUS_SUCCESS// // Completion routines can also use this enumeration instead of status codes.// typedef enum _IO_COMPLETION_ROUTINE_RESULT {        ContinueCompletion = STATUS_CONTINUE_COMPLETION,    StopCompletion = STATUS_MORE_PROCESSING_REQUIRED} IO_COMPLETION_ROUTINE_RESULT, *PIO_COMPLETION_ROUTINE_RESULT;Scenario 1: Forward and forget Use the following code if a driver just wants to forward the IRP down and take no additional action. The driver does not have to set a completion routine in this case. If the driver is a top level driver, the IRP can be completed synchronously or asynchronously, depending on the status that is returned by the lower driver. 
NTSTATUSDispatchRoutine_1(    IN PDEVICE_OBJECT DeviceObject,    IN PIRP Irp    ){    //     // You are not setting a completion routine, so just skip the stack    // location because it provides better performance.    //     IoSkipCurrentIrpStackLocation (Irp);    return IoCallDriver(TopOfDeviceStack, Irp);} 
Scenario 2: Forward and waitUse the following code if a driver wants to forward the IRP to a lower driver and wait for it to return so that it can process the IRP. This is frequently done when handling PNP IRPs. For example, when you receive a IRP_MN_START_DEVICE IRP, you must forward the IRP down to the bus driver and wait for it to complete before you can start your device. The Windows XP system has a new function named IoForwardIrpSynchronously that you can use to do this operation easily. 
NTSTATUSDispatchRoutine_2(    IN PDEVICE_OBJECT DeviceObject,    IN PIRP Irp    ){    KEVENT   event;    NTSTATUS status;    KeInitializeEvent(&event, NotificationEvent, FALSE);    //     // You are setting completion routine, so you must copy    // current stack location to the next. You cannot skip a location    // here.    //     IoCopyCurrentIrpStackLocationToNext(Irp);    IoSetCompletionRoutine(Irp,                           CompletionRoutine_2,                           &event,                           TRUE,                           TRUE,                           TRUE                           );    status = IoCallDriver(TopOfDeviceStack, Irp);    if (status == STATUS_PENDING) {               KeWaitForSingleObject(&event,                             Executive, // WaitReason                             KernelMode, // must be Kernelmode to prevent the stack getting paged out                             FALSE,                             NULL // indefinite wait                             );       status = Irp->IoStatus.Status;    }        // <---- Do your own work here.    //     // Because you stopped the completion of the IRP in the CompletionRoutine    // by returning STATUS_MORE_PROCESSING_REQUIRED, you must call    // IoCompleteRequest here.    //     IoCompleteRequest (Irp, IO_NO_INCREMENT);    return status;}NTSTATUSCompletionRoutine_2(    IN PDEVICE_OBJECT   DeviceObject,    IN PIRP             Irp,    IN PVOID            Context    ){   if (Irp->PendingReturned == TRUE) {    //     // You will set the event only if the lower driver has returned    // STATUS_PENDING earlier. This optimization removes the need to    // call KeSetEvent unnecessarily and improves performance because the    // system does not have to acquire an internal lock.      //     KeSetEvent ((PKEVENT) Context, IO_NO_INCREMENT, FALSE);  }  // This is the only status you can return.   return STATUS_MORE_PROCESSING_REQUIRED;  } Scenario 3: Forward with a completion routineIn this case, the driver sets a completion routine, forwards the IRP down, and then returns the status of lower driver as is. The purpose of setting the completion routine is to modify the content of the IRP on its way back. 
NTSTATUSDispathRoutine_3(    IN PDEVICE_OBJECT DeviceObject,    IN PIRP Irp    ){    NTSTATUS status;    //     // Because you are setting completion routine, you must copy the    // current stack location to the next. You cannot skip a location    // here.    //     IoCopyCurrentIrpStackLocationToNext(Irp);     IoSetCompletionRoutine(Irp,                           CompletionRoutine_31,// or CompletionRoutine_32                           NULL,                           TRUE,                           TRUE,                           TRUE                           );        return IoCallDriver(TopOfDeviceStack, Irp);} 
If you return the status of the lower driver from your dispatch routine:
   
   

    
    
You must not change the status of the IRP in the completion routine. This is to make sure that the status values set in the IRP's IoStatus block (Irp->IoStatus.Status) are the same as the return status of the lower drivers. 
    
    
You must propagate the pending status of the IRP as indicated by Irp->PendingReturned. 
    
    
You must not change the synchronicity of the IRP.
   
   
As a result, there are only 2 valid versions of the completion routine in this scenario (31 and 32):
 NTSTATUSCompletionRoutine_31 (    IN PDEVICE_OBJECT   DeviceObject,    IN PIRP             Irp,    IN PVOID            Context    ){       //     // Because the dispatch routine is returning the status of lower driver    // as is, you must do the following:    //     if (Irp->PendingReturned) {                IoMarkIrpPending( Irp );    }        return STATUS_CONTINUE_COMPLETION ; // Make sure of same synchronicity }NTSTATUSCompletionRoutine_32 (    IN PDEVICE_OBJECT   DeviceObject,    IN PIRP             Irp,    IN PVOID            Context    ){       //     // Because the dispatch routine is returning the status of lower driver    // as is, you must do the following:    //     if (Irp->PendingReturned) {                IoMarkIrpPending( Irp );    }        //        // To make sure of the same synchronicity, complete the IRP here.    // You cannot complete the IRP later in another thread because the     // the dispatch routine is returning the status returned by the lower    // driver as is.    //     IoCompleteRequest( Irp,  IO_NO_INCREMENT);      //     // Although this is an unusual completion routine that you rarely see,    // it is discussed here to address all possible ways to handle IRPs.      //     return STATUS_MORE_PROCESSING_REQUIRED; } Scenario 4: Queue for later, or forward and reuseUse the following code snippet in a situation where the driver wants to either queue an IRP and process it later or forward the IRP to the lower driver and reuse it for a specific number of times before completing the IRP. The dispatch routine marks the IRP pending and returns STATUS_PENDING because the IRP is going to be completed later in a different thread. Here, the completion routine can change the status of the IRP if necessary (in contrast to the previous scenario). 
NTSTATUSDispathRoutine_4(    IN PDEVICE_OBJECT DeviceObject,    IN PIRP Irp    ){    NTSTATUS status;    //     // You mark the IRP pending if you are intending to queue the IRP    // and process it later. If you are intending to forward the IRP     // directly, use one of the methods discussed earlier in this article.    //     IoMarkIrpPending( Irp );        //     // For demonstration purposes: this IRP is forwarded to the lower driver.    //     IoCopyCurrentIrpStackLocationToNext(Irp);     IoSetCompletionRoutine(Irp,                           CompletionRoutine_41, // or CompletionRoutine_42                           NULL,                           TRUE,                           TRUE,                           TRUE                           );     IoCallDriver(TopOfDeviceStack, Irp);    //     // Because you marked the IRP pending, you must return pending,    // regardless of the status of returned by IoCallDriver.    //     return STATUS_PENDING ;}
The completion routine can either return STATUS_CONTINUE_COMPLETION or STATUS_MORE_PROCESSING_REQUIRED. You return STATUS_MORE_PROCESSING_REQUIRED only if you intend to reuse the IRP from another thread and complete it later.
NTSTATUSCompletionRoutine_41(    IN PDEVICE_OBJECT   DeviceObject,    IN PIRP             Irp,    IN PVOID            Context    ){     //     // By returning STATUS_CONTINUE_COMPLETION , you are relinquishing the     // ownership of the IRP. You cannot touch the IRP after this.    //     return STATUS_CONTINUE_COMPLETION ; } NTSTATUSCompletionRoutine_42 (    IN PDEVICE_OBJECT   DeviceObject,    IN PIRP             Irp,    IN PVOID            Context    ){      //     // Because you are stopping the completion of the IRP by returning the    // following status, you must complete the IRP later.    //     return STATUS_MORE_PROCESSING_REQUIRED ; } Scenario 5: Complete the IRP in the dispatch routineThis scenario shows how to complete an IRP in the dispatch routine. Important When you complete an IRP in the dispatch routine, the return status of the dispatch routine should match the status of the value that is set in the IoStatus block of the IRP (Irp->IoStatus.Status). 
NTSTATUSDispatchRoutine_5(    IN PDEVICE_OBJECT DeviceObject,    IN PIRP Irp    ){    //     // <-- Process the IRP here.    //     Irp->IoStatus.Status = STATUS_XXX;    Irp->IoStatus.Information = YYY;    IoCompletRequest(Irp, IO_NO_INCREMENT);    return STATUS_XXX;}