The IoBuildPartialMdl routine builds a new memory descriptor list (MDL) that represents part of a buffer that is described by an existing MDL.
NTKERNELAPI VOID IoBuildPartialMdl( PMDL SourceMdl, PMDL TargetMdl, PVOID VirtualAddress, ULONG Length );
A pointer to an MDL that describes the original buffer, of which a subrange is to be mapped.
A pointer to a caller-allocated MDL. This MDL must be large enough to describe the pages in the subrange that are specified by VirtualAddress and Length.
A pointer to the base virtual address for the subrange to be described by the TargetMdl.
Specifies the length, in bytes, to be mapped by the TargetMdl. This value, in combination with VirtualAddress, must specify a buffer that is a proper subrange of the buffer that is described by SourceMdl. If Length is zero, the subrange to be mapped starts at VirtualAddress and includes the remaining range described by the SourceMdl.
This routine builds a target MDL that describes a subrange of the buffer that is described by the source MDL. This subrange is specified by the VirtualAddress and Length parameters. The SourceMdl and TargetMdl parameters point to the source MDL and target MDL.
A driver can use IoBuildPartialMdl to split a large transfer request into smaller transfer requests. The physical pages that the source MDL describes must be locked before the driver calls IoBuildPartialMdl. Typically, the source MDL describes a buffer in user address space, and the driver calls the MmProbeAndLockPages routine to lock the pages in this buffer. However, the driver can build the source MDL from nonpaged memory by calling the MmBuildMdlForNonPagedPool, MmAllocatePagesForMdlEx, or MmAllocatePagesForMdl routine.
A driver can map a partial MDL into the system address space by using the MmGetSystemAddressForMdlSafe macro. If a partial MDL is built from a source MDL that is already mapped into the system address space, MmGetSystemAddressForMdlSafe uses the existing source mapping. Otherwise, MmGetSystemAddressForMdlSafe creates a new mapping. To prevent this new mapping from being leaked, drivers must call MmPrepareMdlForReuse before reusing a partial MDL. In addition, the IoFreeMdl routine releases the system-address-space mapping for a partial MDL, if such a mapping exists.
For more information about MDLs, see Using MDLs.
|Windows version||Available starting with Windows 2000.|
|Header||wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)|
|DDI compliance rules||MdlAfterReqCompletedIntIoctlA, MdlAfterReqCompletedIoctlA, MdlAfterReqCompletedReadA, MdlAfterReqCompletedWriteA|