Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
The BuildMdlFromScatterGatherList routine builds an MDL from a scatter/gather list allocated by the system.
This routine is reserved for system use.
Syntax
PBUILD_MDL_FROM_SCATTER_GATHER_LIST PbuildMdlFromScatterGatherList;
NTSTATUS PbuildMdlFromScatterGatherList(
[in] PDMA_ADAPTER DmaAdapter,
[in] PSCATTER_GATHER_LIST ScatterGather,
[in] PMDL OriginalMdl,
[out] PMDL *TargetMdl
)
{...}
Parameters
[in] DmaAdapter
Pointer to the DMA_ADAPTER structure returned by IoGetDmaAdapter that represents the bus-master adapter or DMA controller.
[in] ScatterGather
Pointer to the SCATTER_GATHER_LIST structure passed to the driver's AdapterListControl routine.
[in] OriginalMdl
Pointer to the original MDL that the driver used to build the scatter/gather list.
[out] TargetMdl
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 code | Description |
|---|---|
| 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
| Requirement | Value |
|---|---|
| Minimum supported client | Available in Windows XP and later versions of Windows. |
| Target Platform | Desktop |
| Header | wdm.h (include Wdm.h) |
| IRQL | <= DISPATCH_LEVEL |
| DDI compliance rules | IrqlDispatch(wdm) |