31、分层驱动程序

把功能复杂的驱动分解成多个简单的驱动。多个分层驱动程序形成一个设备堆栈，IRP请求首先发送到设备堆栈的顶层，然后以次穿越每层的设备堆栈，最终完成IRP的请求。

1、相关概念

分层驱动是指两个或两个以上的驱动程序，他们分别创建设备对象，并且形成一个由高到低的设备对象栈。IRP请求一般送到设备栈最顶层的设备对象。顶层设备对象可以处理该IRP请求，也可以向下转发。IRP请求结束时，按原路返回。

1）_DEVICE_OBJECT结构体，需要注意3个参数：

DriverObject 设备对象对应的驱动对象

NextDevice 记录下一个设备对象的指针

AttachedDevice 记录当前设备对象挂载的设备对象。

WDM驱动程序就属于分层驱动程序。最简单的WDM驱动程序分为两层：一层是PDO（物理设备对象），一层是FDO（功能设备对象），FDO挂载在PDO之上。PDO实现即插即用的功能，FDO完成逻辑功能，而将一些硬件相关请求发往PDL。

挂载指的是将高一层的设备对象挂载在低一层的设备对象上，从而形成一个设备栈。

IoAttachDeviceToDeviceStack 挂载

IoDetachDevice 卸载

2）I/O 堆栈

用一个叫做IO_STACK_LOCATION的数据结构来保存；它和设备堆栈紧密结合。在IRP中，有一个指向IO_STACK_LOCATION数组的指针。调用IoAllocateIrp创建Irp时，有一个StackSize,就是IO_STACK_LOCATION数组的大小。

图示 P322

3）向下转发IRP

3种方法处理IRP：直接处理；调用StartIo，向下转发。

一个设备堆栈对应一个IO_STACK_LOCATION堆栈元素。IRP内部有一个指针指向当前正使用的IO_STACK_LOCATION。IoGetCurrentIrpStackLocation 获得。

每次调用IoCallDriver时，内核函数会将IRP的当前指针向下移一个单位。而IoSkipCurrentIrpStackLocation 用来将当前I/O堆栈往回（上）移一个单位。

When sending an IRP to the next-lower driver, your driver can call IoSkipCurrentIrpStackLocation if you do not intend to provide an IoCompletion routine (the address of which is stored in the driver's IO_STACK_LOCATION structure). If you call IoSkipCurrentIrpStackLocation before calling IoCallDriver, the next-lower driver receives the same IO_STACK_LOCATION that your driver received.

If you intend to provide an IoCompletion routine for the IRP, your driver should call IoCopyCurrentIrpStackLocationToNext instead of IoSkipCurrentIrpStackLocation.

/************************************************************************
* 函数名称:DriverEntry
* 功能描述:初始化驱动程序，定位和申请硬件资源，创建内核对象
* 参数列表:
      pDriverObject:从I/O管理器中传进来的驱动对象
      pRegistryPath:驱动程序在注册表的中的路径
* 返回 值:返回初始化驱动状态
*************************************************************************/
 #pragma INITCODE
 extern "C" NTSTATUS DriverEntry (
            IN PDRIVER_OBJECT pDriverObject,
            IN PUNICODE_STRING pRegistryPath    ) 
{
    NTSTATUS ntStatus;
    KdPrint(("DriverB:Enter B DriverEntry\n"));

    //注册其他驱动调用函数入口
     pDriverObject->DriverUnload = HelloDDKUnload;
    pDriverObject->MajorFunction[IRP_MJ_CREATE] = HelloDDKCreate;
    pDriverObject->MajorFunction[IRP_MJ_CLOSE] = HelloDDKClose;
    pDriverObject->MajorFunction[IRP_MJ_WRITE] = HelloDDKDispatchRoutine;
    pDriverObject->MajorFunction[IRP_MJ_READ] = HelloDDKRead;
    
    UNICODE_STRING DeviceName;
    RtlInitUnicodeString( &DeviceName, L"\\Device\\MyDDKDeviceA" );

    PDEVICE_OBJECT DeviceObject = NULL;
    PFILE_OBJECT FileObject = NULL;
    //寻找DriverA创建的设备对象
     ntStatus = IoGetDeviceObjectPointer(&DeviceName,FILE_ALL_ACCESS,&FileObject,&DeviceObject);

    if (!NT_SUCCESS(ntStatus))
    {
        KdPrint(("DriverB:IoGetDeviceObjectPointer() 0x%x\n", ntStatus ));
        return ntStatus;
    }

    //创建自己的驱动设备对象
     ntStatus = CreateDevice(pDriverObject);

    if ( !NT_SUCCESS( ntStatus ) )
    {
        ObDereferenceObject( FileObject );
        DbgPrint( "IoCreateDevice() 0x%x!\n", ntStatus );
        return ntStatus;
    }

    PDEVICE_EXTENSION pdx = (PDEVICE_EXTENSION) pDriverObject->DeviceObject->DeviceExtension;

    PDEVICE_OBJECT FilterDeviceObject = pdx->pDevice;

    //将自己的设备对象挂载在DriverA的设备对象上
    PDEVICE_OBJECT TargetDevice = IoAttachDeviceToDeviceStack( FilterDeviceObject,
                                          DeviceObject );
    //将底层设备对象记录下来
    pdx->TargetDevice = TargetDevice;
    
    if ( !TargetDevice )
    {
        ObDereferenceObject( FileObject );
        IoDeleteDevice( FilterDeviceObject );
        DbgPrint( "IoAttachDeviceToDeviceStack() 0x%x!\n", ntStatus );
        return STATUS_INSUFFICIENT_RESOURCES;
    }

    FilterDeviceObject->DeviceType = TargetDevice->DeviceType;
    FilterDeviceObject->Characteristics = TargetDevice->Characteristics;
    FilterDeviceObject->Flags &= ~DO_DEVICE_INITIALIZING;
    FilterDeviceObject->Flags |= ( TargetDevice->Flags & ( DO_DIRECT_IO |
                                                         DO_BUFFERED_IO ) );
    ObDereferenceObject( FileObject );

    KdPrint(("DriverB:B attached A successfully!\n"));
    
    KdPrint(("DriverB:Leave B DriverEntry\n"));
    return ntStatus;
}
/************************************************************************
* 函数名称:HelloDDKUnload
* 功能描述:负责驱动程序的卸载操作
* 参数列表:
      pDriverObject:驱动对象
* 返回 值:返回状态
*************************************************************************/
#pragma PAGEDCODE
VOID HelloDDKUnload (IN PDRIVER_OBJECT pDriverObject) 
{
    PDEVICE_OBJECT    pNextObj;
    KdPrint(("DriverB:Enter B DriverUnload\n"));
    pNextObj = pDriverObject->DeviceObject;

    while (pNextObj != NULL) 
    {
        PDEVICE_EXTENSION pDevExt = (PDEVICE_EXTENSION)
            pNextObj->DeviceExtension;
        pNextObj = pNextObj->NextDevice;
        //从设备栈中弹出
        IoDetachDevice( pDevExt->TargetDevice);
        //删除该设备对象
        IoDeleteDevice( pDevExt->pDevice );
    }
    KdPrint(("DriverB:Enter B DriverUnload\n"));
}

/************************************************************************
* 函数名称:HelloDDKDispatchRoutine
* 功能描述:对读IRP进行处理
* 参数列表:
      pDevObj:功能设备对象
      pIrp:从IO请求包
* 返回 值:返回状态
*************************************************************************/
#pragma PAGEDCODE
NTSTATUS HelloDDKDispatchRoutine(IN PDEVICE_OBJECT pDevObj,
                                 IN PIRP pIrp) 
{
    KdPrint(("DriverB:Enter B HelloDDKDispatchRoutine\n"));
    NTSTATUS ntStatus = STATUS_SUCCESS;
    // 完成IRP
    pIrp->IoStatus.Status = ntStatus;
    pIrp->IoStatus.Information = 0;    // bytes xfered
    IoCompleteRequest( pIrp, IO_NO_INCREMENT );
    KdPrint(("DriverB:Leave B HelloDDKDispatchRoutine\n"));
    return ntStatus;
}

#pragma PAGEDCODE
NTSTATUS HelloDDKCreate(IN PDEVICE_OBJECT pDevObj,
                                 IN PIRP pIrp) 
{
    KdPrint(("DriverB:Enter B HelloDDKCreate\n"));
    NTSTATUS ntStatus = STATUS_SUCCESS;
    //
//     // 完成IRP
//     pIrp->IoStatus.Status = ntStatus;
//     pIrp->IoStatus.Information = 0;    // bytes xfered
//     IoCompleteRequest( pIrp, IO_NO_INCREMENT );

    PDEVICE_EXTENSION pdx = (PDEVICE_EXTENSION)pDevObj->DeviceExtension;

    IoSkipCurrentIrpStackLocation (pIrp);

    ntStatus = IoCallDriver(pdx->TargetDevice, pIrp);

    KdPrint(("DriverB:Leave B HelloDDKCreate\n"));

    return ntStatus;
}

#pragma PAGEDCODE
NTSTATUS HelloDDKRead(IN PDEVICE_OBJECT pDevObj,
                                 IN PIRP pIrp) 
{
    KdPrint(("DriverB:Enter B HelloDDKCreate\n"));
    NTSTATUS ntStatus = STATUS_SUCCESS;
    //将自己完成IRP，改成由底层驱动负责

    PDEVICE_EXTENSION pdx = (PDEVICE_EXTENSION)pDevObj->DeviceExtension;

    //调用底层驱动
    IoSkipCurrentIrpStackLocation (pIrp);

    ntStatus = IoCallDriver(pdx->TargetDevice, pIrp);

    KdPrint(("DriverB:Leave B HelloDDKCreate\n"));

    return ntStatus;
}

#pragma PAGEDCODE
NTSTATUS HelloDDKClose(IN PDEVICE_OBJECT pDevObj,
                                 IN PIRP pIrp) 
{
    KdPrint(("DriverB:Enter B HelloDDKClose\n"));
    NTSTATUS ntStatus = STATUS_SUCCESS;

    PDEVICE_EXTENSION pdx = (PDEVICE_EXTENSION)pDevObj->DeviceExtension;

    IoSkipCurrentIrpStackLocation (pIrp);

    ntStatus = IoCallDriver(pdx->TargetDevice, pIrp);    
    
    KdPrint(("DriverB:Leave B HelloDDKClose\n"));

    return ntStatus;
}

挂载设备对象代码示例 P324

转发IRP代码示例 P326 如上代码示例Read

2、完成例程

在将IRP发送给低层驱动或者其他驱动之前，可以对IRP设置一个完成例程。一旦底层驱动将IRP完成后，IRP完成例程将被触发，可以通过这个原理来获得通知。

IoSetCompletionRoutine ，如果参数CompletionRoutine 为NULL，则意味着完成例程取消。IRP被IoCompleteRequest 完成时，会一层层出栈，如果遇到完成例程，则调用完成例程。

当调用IoCallDriver后，当前驱动就失去了对IRP的控制；如果此时设置IRP的属性，会引起系统崩溃。完成例程返回两种状态，STATUS_SUCCESS，STATUS_MORE_PROCESSING_REQUIRED。如果返回是 STATUS_MORE_PROCESSING_REQUIRED，则本层设备堆栈重新获得IRP的控制权，并且设备栈不会向上弹出，也就是向上“回卷” 设备栈停止，此时可以再次向底层发送IRP。

1）传播Pending位

IRP的堆栈向上回卷时，底层I/O堆栈的Control域的SL_PENDING_RETURNED位必须传播到上一层。如果本层没有设备完成例程，传播是自动的；如果设备了完成例程，则需要程序员自己实现。

注意：只能在完成例程中设置。

2）返回STATUS_SUCCESS

如果是STATUS_SUCCESS，则继续回卷。

NTSTATUS
  MyIoCompletion(
    IN PDEVICE_OBJECT  DeviceObject,
    IN PIRP  Irp,
    IN PVOID  Context
    )
{
    //进入此函数标志底层驱动设备将IRP完成
    KdPrint(("Enter MyIoCompletion\n"));
    if (Irp->PendingReturned) 
    {
        //传播pending位
        IoMarkIrpPending( Irp );
    }
    return STATUS_SUCCESS;//同STATUS_CONTINUE_COMPLETION
}

#pragma PAGEDCODE
NTSTATUS HelloDDKRead(IN PDEVICE_OBJECT pDevObj,
                                 IN PIRP pIrp) 
{
    KdPrint(("DriverB:Enter B HelloDDKRead\n"));
    NTSTATUS ntStatus = STATUS_SUCCESS;
    //将自己完成IRP，改成由底层驱动负责

    PDEVICE_EXTENSION pdx = (PDEVICE_EXTENSION)pDevObj->DeviceExtension;

    //将当前IRP堆栈拷贝底层堆栈
    IoCopyCurrentIrpStackLocationToNext(pIrp);

    //设置完成例程
    IoSetCompletionRoutine(pIrp,MyIoCompletion,NULL,TRUE,TRUE,TRUE);

    //调用底层驱动
    ntStatus = IoCallDriver(pdx->TargetDevice, pIrp);

    //当IoCallDriver后，并且完成例程返回的是STATUS_SUCCESS
    //IRP就不在属于派遣函数了，就不能对IRP进行操作了
    if (ntStatus == STATUS_PENDING)
    {
        KdPrint(("STATUS_PENDING\n"));
    }
    ntStatus = STATUS_PENDING; 

    KdPrint(("DriverB:Leave B HelloDDKRead\n"));

    return ntStatus;
}

示例代码 P333

3）STATUS_MORE_PROCESSING_REQUIRED

如果是STATUS_MORE_PROCESSING_REQUIRED，则本层堆栈重新获得控制，并且该IRP从完成状态变成了未完成状态，需要再次完成，即执行IoCompleteRequest 。

重新获得的IRP可以再次传下底层，也可以标志完成。

NTSTATUS
  MyIoCompletion(
    IN PDEVICE_OBJECT  DeviceObject,
    IN PIRP  Irp,
    IN PVOID  Context
    )
{

    if (Irp->PendingReturned == TRUE) 
    {
        //设置事件
        KeSetEvent((PKEVENT)Context,IO_NO_INCREMENT,FALSE);
    }

    return STATUS_MORE_PROCESSING_REQUIRED;
}

#pragma PAGEDCODE
NTSTATUS HelloDDKRead(IN PDEVICE_OBJECT pDevObj,
                                 IN PIRP pIrp) 
{
    KdPrint(("DriverB:Enter B HelloDDKRead\n"));
    NTSTATUS ntStatus = STATUS_SUCCESS;
    //将自己完成IRP，改成由底层驱动负责

    PDEVICE_EXTENSION pdx = (PDEVICE_EXTENSION)pDevObj->DeviceExtension;

    //将本层的IRP堆栈拷贝到底层堆栈
    IoCopyCurrentIrpStackLocationToNext(pIrp);

    KEVENT event;
    //初始化事件
    KeInitializeEvent(&event, NotificationEvent, FALSE);

    //设置完成例程
    IoSetCompletionRoutine(pIrp,MyIoCompletion,&event,TRUE,TRUE,TRUE);

    //调用底层驱动
    ntStatus = IoCallDriver(pdx->TargetDevice, pIrp);

    if (ntStatus == STATUS_PENDING)
    {
        KdPrint(("IoCallDriver return STATUS_PENDING,Waiting ...\n"));
        KeWaitForSingleObject(&event,Executive,KernelMode ,FALSE,NULL);
        ntStatus = pIrp->IoStatus.Status;
    }

    //虽然在底层驱动已经将IRP完成了，但是由于完成例程返回的是
    //STATUS_MORE_PROCESSING_REQUIRED,因此需要再次调用IoCompleteRequest!
    IoCompleteRequest (pIrp, IO_NO_INCREMENT);

    KdPrint(("DriverB:Leave B HelloDDKRead\n"));

    return ntStatus;
}

示例代码 P335

3）将IRP分成多个IRP

通过一个例子来说明。

图示分层驱动模型 P336

#pragma PAGEDCODE
NTSTATUS
HelloDDKReadCompletion(
    IN PDEVICE_OBJECT DeviceObject,
    IN PIRP           Irp,
    IN PVOID          Context
    )
{
    KdPrint(("DriverB:Enter B HelloDDKReadCompletion\n"));

    PMYDRIVER_RW_CONTEXT rwContext = (PMYDRIVER_RW_CONTEXT) Context;
    NTSTATUS ntStatus = Irp->IoStatus.Status;

    ULONG stageLength;

    if(rwContext && NT_SUCCESS(ntStatus)) 
    {
        //已经传送了多少字节
        rwContext->Numxfer += Irp->IoStatus.Information;

       if(rwContext->Length) 
       {
           //设定下一阶段读取字节数
            if(rwContext->Length > MAX_PACKAGE_SIZE) 
            {
                stageLength = MAX_PACKAGE_SIZE;
            }
            else 
            {
                stageLength = rwContext->Length;
            }
            //重新利用MDL
            MmPrepareMdlForReuse(rwContext->NewMdl);

            IoBuildPartialMdl(Irp->MdlAddress,
                              rwContext->NewMdl,
                              (PVOID) rwContext->VirtualAddress,
                              stageLength);
        
            rwContext->VirtualAddress += stageLength;
            rwContext->Length -= stageLength;

            IoCopyCurrentIrpStackLocationToNext(Irp);
            PIO_STACK_LOCATION nextStack = IoGetNextIrpStackLocation(Irp);

            nextStack->Parameters.Read.Length = stageLength;

            IoSetCompletionRoutine(Irp,
                                   HelloDDKReadCompletion,
                                   rwContext,
                                   TRUE,
                                   TRUE,
                                   TRUE);

            IoCallDriver(rwContext->DeviceExtension->TargetDevice, 
                         Irp);

            return STATUS_MORE_PROCESSING_REQUIRED;
        }
        else 
        {
            //最后一次传输
            Irp->IoStatus.Information = rwContext->Numxfer;
        }
    }

    KdPrint(("DriverB:Leave B HelloDDKReadCompletion\n"));
    return STATUS_MORE_PROCESSING_REQUIRED;  
}

底层驱动示例代码 P337 见DriverA示例部分

#pragma PAGEDCODE
NTSTATUS HelloDDKRead(IN PDEVICE_OBJECT pDevObj,
                                 IN PIRP pIrp) 
{
    KdPrint(("DriverB:Enter B HelloDDKRead\n"));
    NTSTATUS status = STATUS_SUCCESS;

    PDEVICE_EXTENSION pDevExt = (PDEVICE_EXTENSION)
        pDevObj->DeviceExtension;

    PIO_STACK_LOCATION stack = IoGetCurrentIrpStackLocation(pIrp);
    
    ULONG totalLength;
    ULONG stageLength;
    PMDL mdl;
    PVOID virtualAddress;
    PMYDRIVER_RW_CONTEXT rwContext = NULL;
    PIO_STACK_LOCATION nextStack;

    if (!pIrp->MdlAddress)
    {
        status = STATUS_UNSUCCESSFUL;
        totalLength = 0;
        goto HelloDDKRead_EXIT;
    }

    //获取MDL的虚拟地址
    virtualAddress = MmGetMdlVirtualAddress(pIrp->MdlAddress);
    //获取MDL的长度
    totalLength = MmGetMdlByteCount(pIrp->MdlAddress);

    KdPrint(("DriverB:(pIrp->MdlAddress)MmGetMdlVirtualAddress:%08X\n",MmGetMdlVirtualAddress(pIrp->MdlAddress)));
    KdPrint(("DriverB:(pIrp->MdlAddress)MmGetMdlByteCount:%d\n",MmGetMdlByteCount(pIrp->MdlAddress)));

    //将总的传输，分成几个阶段，这里设定每次阶段的长度
    if(totalLength > MAX_PACKAGE_SIZE) 
    {
        stageLength = MAX_PACKAGE_SIZE;
    }else 
    {
        stageLength = totalLength;
    }

    //创建新的MDL
    mdl = IoAllocateMdl((PVOID) virtualAddress,
                        totalLength,
                        FALSE,
                        FALSE,
                        NULL);

    KdPrint(("DriverB:(new mdl)MmGetMdlVirtualAddress:%08X\n",MmGetMdlVirtualAddress(mdl)));
    KdPrint(("DriverB:(new mdl)MmGetMdlByteCount:%d\n",MmGetMdlByteCount(mdl)));

    if(mdl == NULL) 
    {
        KdPrint(("DriverB:Failed to alloc mem for mdl\n"));
        status = STATUS_INSUFFICIENT_RESOURCES;
        goto HelloDDKRead_EXIT;
    }

    //将IRP的MDL做重新映射
    IoBuildPartialMdl(pIrp->MdlAddress,
                      mdl,
                      (PVOID) virtualAddress,
                      stageLength);
    KdPrint(("DriverB:(new mdl)MmGetMdlVirtualAddress:%08X\n",MmGetMdlVirtualAddress(mdl)));
    KdPrint(("DriverB:(new mdl)MmGetMdlByteCount:%d\n",MmGetMdlByteCount(mdl)));

    rwContext = (PMYDRIVER_RW_CONTEXT)
                ExAllocatePool(NonPagedPool,sizeof(MYDRIVER_RW_CONTEXT));

    rwContext->NewMdl            = mdl;
    rwContext->PreviousMdl        = pIrp->MdlAddress;
    rwContext->Length            = totalLength - stageLength;//还剩下多少没读取
    rwContext->Numxfer            = 0;                        //读了多少字节
    rwContext->VirtualAddress    = ((ULONG_PTR)virtualAddress + stageLength);//下一阶段开始读取的地址
    rwContext->DeviceExtension    = pDevExt;

    //拷贝到底层堆栈
    IoCopyCurrentIrpStackLocationToNext(pIrp);

    nextStack = IoGetNextIrpStackLocation(pIrp);
    //根据底层驱动的实现，底层驱动有可能读取这个数值，也有可能读取mdl的length。
    nextStack->Parameters.Read.Length = stageLength;

    pIrp->MdlAddress = mdl;
    
    //设定完成例程
    IoSetCompletionRoutine(pIrp, 
                           (PIO_COMPLETION_ROUTINE)HelloDDKReadCompletion,
                           rwContext,
                           TRUE,
                           TRUE,
                           TRUE);

    IoCallDriver(pDevExt->TargetDevice,pIrp);
    
    pIrp->MdlAddress = rwContext->PreviousMdl;
    IoFreeMdl(rwContext->NewMdl);

HelloDDKRead_EXIT:
    // 完成IRP
    pIrp->IoStatus.Status = status;
    pIrp->IoStatus.Information = totalLength;    // bytes xfered
    IoCompleteRequest( pIrp, IO_NO_INCREMENT );
    KdPrint(("DriverB:Leave B HelloDDKRead\n"));
    return status;
}

中间层驱动，读派遣函数示例代码 P339

图示完成例程与派遣例程 P338

完全例程 示例代码 P342  如上代码示例中