Expand Minimize

IoBuildPartialMdl routine

The IoBuildPartialMdl routine builds a new memory descriptor list (MDL) that represents part of a buffer that is described by an existing MDL.

Syntax


VOID IoBuildPartialMdl(
  _In_     PMDL SourceMdl,
  _Inout_  PMDL TargetMdl,
  _In_     PVOID VirtualAddress,
  _In_     ULONG Length
);

Parameters

SourceMdl [in]

A pointer to an MDL that describes the original buffer, of which a subrange is to be mapped.

TargetMdl [in, out]

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.

VirtualAddress [in]

A pointer to the base virtual address for the subrange to be described by the TargetMdl.

Length [in]

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.

Return value

None

Remarks

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.

Requirements

Version

Available starting with Windows 2000.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

Library

Ntoskrnl.lib

IRQL

<=DISPATCH_LEVEL

DDI compliance rules

MdlAfterReqCompletedIntIoctlA, MdlAfterReqCompletedIoctlA, MdlAfterReqCompletedReadA, MdlAfterReqCompletedWriteA

See also

IoFreeMdl
MmAllocatePagesForMdl
MmAllocatePagesForMdlEx
MmBuildMdlForNonPagedPool
MmGetSystemAddressForMdlSafe
MmPrepareMdlForReuse
MmProbeAndLockPages

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft