Edit

WDM Equivalents for WDF Buffer Pointers

  • Article

A Kernel-Mode Driver Framework (KMDF) or User-Mode Driver Framework (UMDF) driver uses the following methods for retrieving I/O buffers for buffered and direct I/O. Unless otherwise specified, the methods apply to both KMDF and UMDF.

The following tables describe what the retrieval methods return for IRP_MJ_READ, IRP_MJ_WRITE, and IRP_MJ_DEVICE_CONTROL requests for buffered and direct I/O. Requests for neither I/O require special handling because the driver must retrieve the buffers while running in the context of the requesting user-mode process.

Buffers for IRP_MJ_READ Requests

To retrieve a buffer for a read request, a KMDF driver calls one of the WdfRequestRetrieveOutputXxx methods. The buffer that each of these methods returns varies, depending on whether the driver performs buffered or direct I/O. The following table describes the pointer that is returned by each method in WDM terms.

Function Buffered I/O Direct I/O
WdfRequestRetrieveOutputBuffer Irp->AssociatedIrp.SystemBuffer MmGetSystemAddressForMdlSafe (Irp->MdlAddress)
WdfRequestRetrieveOutputWdmMdl (KMDF only) Builds a memory descriptor list (MDL) for Irp->AssociatedIrp.SystemBuffer and returns the MDL. Irp->MdlAddress
WdfRequestRetrieveOutputMemory Returns a WDFMEMORY object. Call WdfMemoryGetBuffer on this object to get Irp->AssociatedIrp.SystemBuffer. Returns a WDFMEMORY object. Call WdfMemoryGetBuffer on this object to get MmGetSystemAddressForMdlSafe (Irp->MdlAddress).

Buffers for IRP_MJ_WRITE Requests

To retrieve a buffer for a write request, a KMDF driver calls one of the WdfRequestRetrieveInputXxx methods. The buffer that each of these methods returns varies, depending on whether the driver performs buffered or direct I/O. The following table describes the pointer that is returned by each method in WDM terms.

Function Buffered I/O Direct I/O
WdfRequestRetrieveInputBuffer Irp->AssociatedIrp.SystemBuffer MmGetSystemAddressForMdlSafe (Irp->MdlAddress)
WdfRequestRetrieveInputWdmMdl (KMDF only) Builds an MDL for Irp->AssociatedIrp.SystemBuffer and returns the MDL. Irp->MdlAddress
WdfRequestRetrieveInputMemory Returns a WDFMEMORY object. Call WdfMemoryGetBuffer on this object to get Irp->AssociatedIrp.SystemBuffer. Returns a WDFMEMORY object. Call WdfMemoryGetBuffer on this object to get MmGetSystemAddressForMdlSafe (Irp->MdlAddress).

Buffers for IRP_MJ_DEVICE_CONTROL Requests

To retrieve a buffer for a device I/O control request, a KMDF driver calls either WdfRequestRetrieveInputXxx or WdfRequestRetrieveOutputXxx methods. The buffer that each of these methods returns varies, depending on whether the driver performs buffered or direct I/O, as shown in the following table:

Function Buffered I/O Direct I/O
WdfRequestRetrieveInputBuffer Irp->AssociatedIrp.SystemBuffer MmGetSystemAddressForMdlSafe (Irp->MdlAddress)
WdfRequestRetrieveInputWdmMdl (KMDF only) Builds an MDL for Irp->AssociatedIrp.SystemBuffer and returns the MDL. Builds an MDL for Irp->AssociatedIrp.SystemBuffer and returns the MDL.
WdfRequestRetrieveInputMemory Returns a WDFMEMORY object. Call WdfMemoryGetBuffer on this object to get Irp->AssociatedIrp.SystemBuffer. Returns a WDFMEMORY object. Call WdfMemoryGetBuffer on this object to get MmGetSystemAddressForMdlSafe (Irp->MdlAddress).
WdfRequestRetrieveOutputBuffer Irp->AssociatedIrp.SystemBuffer MmGetSystemAddressForMdlSafe (Irp->MdlAddress)
WdfRequestRetrieveOutputWdmMdl (KMDF only) Builds a memory descriptor list (MDL) for Irp->AssociatedIrp.SystemBuffer and returns the MDL. Irp->MdlAddress
WdfRequestRetrieveOutputMemory Returns a WDFMEMORY object. Call WdfMemoryGetBuffer on this object to get Irp->AssociatedIrp.SystemBuffer. Returns a WDFMEMORY object. Call WdfMemoryGetBuffer on this object to get MmGetSystemAddressForMdlSafe (Irp->MdlAddress).