WDF驱动开发-内存缓冲区

驱动程序通常使用内存缓冲区向/从框架和其他驱动程序传递数据，或在本地存储信息。 WDF常见的内存缓冲区包括框架内存对象(WDFMEMORY)、 lookaside、 MDL 和 本地缓冲区。

使用框架内存对象

框架使用 内存对象 来描述驱动程序从中接收并传递给框架的内存缓冲区。 每个框架内存对象表示一个缓冲区。

若要创建内存对象，驱动程序会调用以下对象方法之一：

• WdfMemoryCreate，用于创建内存对象并分配指定大小的内存缓冲区；
• WdfMemoryCreatePreallocated，它为预分配的缓冲区创建内存对象；
• WdfMemoryCreateFromLookaside，用于从 旁视列表创建内存缓冲区；

若要获取表示接收的 I/O 请求缓冲区的内存对象，驱动程序会调用 WdfRequestRetrieveInputMemory 和 WdfRequestRetrieveOutputMemory。 有关检索 I/O 请求缓冲区的详细信息，请参阅 在 Framework-Based 驱动程序中访问数据缓冲区。

若要获取内存对象缓冲区的地址和大小，驱动程序会调用 WdfMemoryGetBuffer。

若要将数据移入或移出内存对象的缓冲区，驱动程序会调用 WdfMemoryCopyFromBuffer 或 WdfMemoryCopyToBuffer。 这些对象方法检查源大小和目标大小，并防止缓冲区溢出错误。

如果驱动程序通过调用 WdfMemoryCreatePreallocated 创建内存对象，则它随后可以通过调用 WdfMemoryAssignBuffer 将不同的缓冲区分配给内存对象。

当驱动程序将 I/O 请求发送到 I/O 目标时，它通常会将输入或输出缓冲区传递给 框架 I/O 目标对象方法。 驱动程序通过传递描述缓冲区的 WDF_MEMORY_DESCRIPTOR 结构或通过传递内存对象句柄来指定缓冲区。 同步发送 I/O 请求的 I/O 目标对象方法需要 WDF_MEMORY_DESCRIPTOR 结构，异步发送 I/O 请求的方法需要内存对象句柄。

使用 Lookaside 列表

如果驱动程序需要许多大小大致相同的缓冲区，则应从 lookaside中分配它们。 驱动程序通过调用 WdfLookasideListCreate 创建lookaside。 随后，驱动程序可以通过调用 WdfMemoryCreateFromLookaside 从 lookaside 列表中获取缓冲区。

每次驱动程序调用 WdfMemoryCreateFromLookaside 时，框架都会创建一个内存对象，从 lookaside 列表中获取缓冲区，并将缓冲区分配给对象。 当驱动程序使用完这些内存对象之一后，它将调用 WdfObjectDelete，这将删除内存对象并将缓冲区空间返回到lookaside。

操作系统管理分配给lookaside的内存资源。 如果驱动程序在无可用（例如驱动程序第一次调用 WdfMemoryCreateFromLookaside）时从lookaside中请求缓冲区，系统会分配缓冲区并将其分配给列表。 当驱动程序 调用 WdfObjectDelete 并将缓冲区空间返回到lookaside时，系统会在列表中保留现在未分配的缓冲区，直到驱动程序再次需要它。 系统根据需要增加lookaside的大小;例如，更频繁地请求缓冲区的驱动程序会收到较大的lookaside。 另一方面，如果驱动程序未全部使用缓冲区，系统可能会减少lookaside中的缓冲区数。

使用 MDL

某些驱动程序使用内存描述符列表 (MDL) 来描述缓冲区。 例如， (DMA) 设备的直接内存访问驱动程序必须将 MDL 传递给 WdfDmaTransactionInitialize 方法（如果它调用该方法）。

使用 MDL 的驱动程序可以通过调用 WdfRequestRetrieveInputWdmMdl 和 WdfRequestRetrieveOutputWdmMdl 来获取表示已接收 I/O 请求缓冲区的 MDL。

大多数基于框架的驱动程序不使用 MDL。

分配本地缓冲区

需要不传递给框架的本地内部缓冲区空间的驱动程序不必创建内存对象来表示缓冲区。 驱动程序可以调用 ExAllocatePoolWithTag 来分配内部缓冲区。 驱动程序使用完缓冲区后，必须调用 ExFreePoolWithTag。

但是，驱动程序还可以将内存对象用于本地缓冲区。 使用内存缓冲区而不是调用 ExAllocatePoolWithTag的一个优点是，在删除每个对象的父对象时，框架会自动删除内存对象及其缓冲区。

注意：我们讨论的 ExAllocatePool DDI 已在 Windows 10 版本 2004 中弃用，并已替换为 ExAllocatePool2 和 ExAllocatePool3。 

对齐缓冲区

驱动程序可以使用 WDF_ALIGN_SIZE_UP 或 WDF_ALIGN_SIZE_DOWN 函数来计算与指定的对齐偏移量对齐的缓冲区大小。 如果驱动程序必须分配多个连续缓冲区，并且每个缓冲区必须从地址对齐边界开始，则此计算非常有用。

内存缓冲区生命周期

内存缓冲区的生命周期跨越从创建缓冲区到删除缓冲区的时间。 下面从缓冲区几种使用方案来看它们在删除缓冲区时的影响。

在 KMDF内核模式驱动程序框架中，请求对象表示 I/O 请求。 每个请求对象都与一个或多个内存对象相关联，每个内存对象表示用于请求中的输入或输出的缓冲区。

当框架创建表示传入 I/O 请求的请求和内存对象时，它会将请求对象设置为关联内存对象的父对象。 因此，内存对象的保留期不能超过请求对象的生存期。 当基于框架的驱动程序完成 I/O 请求时，框架将删除请求对象和内存对象，使这两个对象的句柄变得无效。

但是，基础缓冲区是不同的。 根据创建缓冲区的组件及其创建缓冲区的方式，缓冲区可能具有引用计数，并且可能由内存对象拥有，也可能不具有引用计数。 如果内存对象拥有缓冲区，则缓冲区具有引用计数，并且其生存期限制为内存对象的生存期。 如果其他组件创建了缓冲区，则缓冲区的生存期与内存对象无关。

基于框架的驱动程序还可以创建自己的请求对象以发送到 I/O 目标。 驱动程序创建的请求可以重复使用驱动程序在 I/O 请求中收到的现有内存对象。 经常向 I/O 目标发送请求的驱动程序可以重复使用它创建 的请求对象 。

了解请求对象、内存对象和基础缓冲区的生存期对于确保驱动程序不会尝试引用无效句柄或缓冲区指针非常重要。

请考虑以下使用场景：

方案 1：驱动程序从 KMDF 接收 I/O 请求，对其进行处理并完成

在最简单的方案中，KMDF 将请求调度到驱动程序，该驱动程序执行 I/O 并完成请求。 在这种情况下，基础缓冲区可能是由用户模式应用程序、其他驱动程序或操作系统本身创建的。

当驱动程序 完成请求时，框架将删除内存对象。 缓冲区指针随后无效。

方案 2：驱动程序从 KMDF 接收 I/O 请求并将其转发到 I/O 目标

在此方案中，驱动程序 将请求转发 到 I/O 目标。 以下示例代码演示驱动程序如何从传入请求对象检索内存对象的句柄、设置要发送到 I/O 目标的请求的格式，以及发送请求：

VOID
EvtIoRead(
    IN WDFQUEUE Queue,
    IN WDFREQUEST Request,
    IN size_t Length
    )
{
    NTSTATUS status;
    WDFMEMORY memory;
    WDFIOTARGET ioTarget;
    BOOLEAN ret;
    ioTarget = WdfDeviceGetIoTarget(WdfIoQueueGetDevice(Queue));

    status = WdfRequestRetrieveOutputMemory(Request, &memory);
    if (!NT_SUCCESS(status)) {
        goto End;
    }

    status = WdfIoTargetFormatRequestForRead(ioTarget,
                                    Request,
                                    memory,
                                    NULL,
                                    NULL);
    if (!NT_SUCCESS(status)) {
        goto End;
    }

    WdfRequestSetCompletionRoutine(Request,
                                    RequestCompletionRoutine,
                                    WDF_NO_CONTEXT);

    ret = WdfRequestSend (Request, ioTarget, WDF_NO_SEND_OPTIONS);
    if (!ret) {
        status = WdfRequestGetStatus (Request);
        goto End;
    }

    return;

End:
    WdfRequestComplete(Request, status);
    return;

}

当 I/O 目标完成请求时，框架将调用驱动程序为请求设置的完成回调。 以下代码显示了一个简单的完成回调：

VOID
RequestCompletionRoutine(
    IN WDFREQUEST                  Request,
    IN WDFIOTARGET                 Target,
    PWDF_REQUEST_COMPLETION_PARAMS CompletionParams,
    IN WDFCONTEXT                  Context
    )
{
    UNREFERENCED_PARAMETER(Target);
    UNREFERENCED_PARAMETER(Context);

    WdfRequestComplete(Request, CompletionParams->IoStatus.Status);

    return;

}

当驱动程序从其完成回调调用 WdfRequestComplete 时，框架将删除内存对象。 驱动程序检索的内存对象句柄现在无效。

方案 3：驱动程序发出使用现有内存对象的 I/O 请求。

某些驱动程序发出自己的 I/O 请求并将其发送到 I/O 目标，这些目标由 I/O 目标对象表示。 驱动程序可以创建自己的请求对象，也可以 重复使用框架创建的请求对象。 使用任一技术，驱动程序都可以重复使用来自上一个请求的内存对象。 驱动程序不得更改基础缓冲区，但在设置新 I/O 请求的格式时，它可以传递缓冲区偏移量。

当框架格式化要发送到 I/O 目标的请求时，它将代表 I/O 目标对象对回收的内存对象进行引用。 I/O 目标对象将保留此引用，直到执行以下操作之一：

• 请求已完成；
• 驱动程序通过调用 WdfIoTargetFormatRequestXxx 或 WdfIoTargetSendXxxSynchronously 方法之一再次重新设置请求对象的格式；
• 驱动程序调用 WdfRequestReuse；

新的 I/O 请求完成后，框架将调用驱动程序为此请求设置的 I/O 完成回调。 此时，I/O 目标对象仍保留对内存对象的引用。 因此，在 I/O 完成回调中，驱动程序必须先对驱动程序创建的请求对象调用 WdfRequestReuse ，然后才能完成从中检索内存对象的原始请求。 如果驱动程序不调用 WdfRequestReuse，则由于额外的引用，检查会出现 bug。

方案 4：驱动程序发出使用新内存对象的 I/O 请求

框架为驱动程序提供了三种方法来创建新的内存对象，具体取决于基础缓冲区的源。 有关详细信息，请参阅 使用内存缓冲区。

如果缓冲区由框架分配或从驱动程序创建的 lookaside 列表中分配，则内存对象拥有该缓冲区，因此只要内存对象存在，缓冲区指针就保持有效。 发出异步 I/O 请求的驱动程序应始终使用内存对象拥有的缓冲区，以便框架可以确保缓冲区一直存在，直到 I/O 请求完成发证驱动程序。

如果驱动程序通过调用 WdfMemoryCreatePreallocated 将以前分配的缓冲区分配给新的内存对象，则内存对象不拥有该缓冲区。 在这种情况下，内存对象的生存期与基础缓冲区的生存期无关。 驱动程序必须管理缓冲区的生存期，并且不得尝试使用无效的缓冲区指针。

方案 5：驱动程序重复使用它创建的请求对象

驱动程序可以重用其创建的请求对象，但在每次重用之前，它必须通过调用 WdfRequestReuse 来重新初始化每个此类对象。