BuildMdlFromScatterGatherList routine

The BuildMdlFromScatterGatherList routine builds an MDL from a scatter/gather list allocated by the system.

Note  This routine is reserved for system use.

Syntax


NTSTATUS BuildMdlFromScatterGatherList(
  _In_   PADAPTER_OBJECT DmaAdapter,
  _In_   PSCATTER_GATHER_LIST ScatterGather,
  _In_   PMDL OriginalMdl,
  _Out_  PMDL *TargetMdl
);

Parameters

DmaAdapter [in]

Pointer to the DMA_ADAPTER structure returned by IoGetDmaAdapter that represents the bus-master adapter or DMA controller.

ScatterGather [in]

Pointer to the SCATTER_GATHER_LIST structure passed to the driver's AdapterListControl routine.

OriginalMdl [in]

Pointer to the original MDL that the driver used to build the scatter/gather list.

TargetMdl [out]

Pointer to a variable the routine uses to return the MDL created to hold the buffer described by the scatter/gather list. The value returned can be the same as OriginalMdl.

Return value

BuildMdlFromScatterGatherList returns one of the following status codes:

Return codeDescription
STATUS_SUCCESS

The operation succeeded.

STATUS_INVALID_PARAMETER

The OriginalMdl parameter is NULL.

STATUS_INSUFFICIENT_RESOURCES

There is not enough memory available to allocate a new MDL.

STATUS_NONE_MAPPED

The system has already created a new MDL for the memory locations in the scatter/gather list. (This only happens if the routine is called twice on the same scatter/gather list.)

 

Remarks

BuildMdlFromScatterGatherList is not a system routine that can be called directly by name. This routine can be called only by pointer from the address returned in a DMA_OPERATIONS structure. Drivers obtain the address of this routine by calling IoGetDmaAdapter with the Version member of the DeviceDescription parameter set to DEVICE_DESCRIPTION_VERSION2. If IoGetDmaAdapter returns NULL, the routine is not available on your platform.

When a driver creates a scatter/gather list to write to a device, the system can make a copy of the data to be written, and use that copy to perform the DMA operation. Use this routine to access the memory locations in the scatter/gather list, regardless of whether those locations are a copy.

Requirements

Version

Available in Windows XP and later versions of Windows.

Header

Ntddk.h (include Ntddk.h)

IRQL

<= DISPATCH_LEVEL

DDI compliance rules

IrqlDispatch

See also

DEVICE_DESCRIPTION
DMA_ADAPTER
DMA_OPERATIONS
SCATTER_GATHER_LIST
BuildScatterGatherList
IoGetDmaAdapter

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft