GetDmaTransferInfo routine

The GetDmaTransferInfo routine calculates the allocation requirements for a scatter/gather DMA transfer.

Syntax


NTSTATUS GetDmaTransferInfo(
  _In_    PDMA_ADAPTER       DmaAdapter,
  _In_    PMDL               Mdl,
  _In_    ULONGLONG          Offset,
  _In_    ULONG              Length,
  _In_    BOOLEAN            WriteOnly,
  _Inout_ PDMA_TRANSFER_INFO TransferInfo
);

Parameters

DmaAdapter [in]

A pointer to a DMA_ADAPTER structure. This structure is the adapter object that represents the driver's bus-master DMA device or system DMA channel. The caller obtained this pointer from a previous call to the IoGetDmaAdapter routine.

Mdl [in]

A pointer to the MDL chain that describes the pages of memory that are to be transferred. For more information, see the Remarks section.

Offset [in]

The starting offset for the scatter/gather DMA transfer. This parameter is a byte offset from the start of the buffer in the first MDL in the MDL chain. If the MDLs in the MDL chain specify a total of N bytes of buffer space, valid values of Offset are in the range 0 to N–1.

Length [in]

The length, in bytes, of the DMA transfer. If the MDL chain specifies a total of N bytes of buffer space, valid values of Length are in the range 1 to N–Offset.

WriteOnly [in]

Indicates whether the transfer is a write-only operation (that is, a transfer to the device from memory). If WriteOnly is TRUE, information returned about the transfer might not be valid for a read transaction. This parameter might indicate that additional cache control operations are required at buffer boundaries to enforce cache coherency.

TransferInfo [in, out]

A pointer to a caller-allocated DMA_TRANSFER_INFO structure. The caller must set the Version member of the structure to DMA_TRANSFER_INFO_VERSION1 before calling GetDmaTransferInfo.

Return value

GetDmaTransferInfo returns STATUS_SUCCESS if the call is successful. Possible error return values include the following status codes.

Return codeDescription
STATUS_NOT_SUPPORTED

The routine does not support the specified version of the DMA_TRANSFER_INFO_XXX structure.

 

Remarks

GetDmaTransferInfo 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_VERSION3. If IoGetDmaAdapter returns NULL, the routine is not available on your platform.

Use GetDmaTransferInfo to calculate the size of the scatter/gather buffer to allocate for the BuildScatterGatherListEx and MapTransferEx routines.

GetDmaTransferInfo replaces the CalculateScatterGatherList routine and is more convenient to use with BuildScatterGatherListEx.

The Mdl, Offset, and Length parameters together specify a collection of physical memory regions to use as a buffer for a scatter/gather DMA transfer. Each physical memory region is typically a page or part of a page. GetDmaTransferInfo determines the allocation requirements for this transfer. These requirements include the following:

  • The number of elements in the scatter/gather list. Each element is a SCATTER_GATHER_ELEMENT structure that describes a physically contiguous block of memory.

  • The amount of memory to allocate to hold the specified scatter/gather list. (This memory allocation includes the space required for the scatter/gather list that describes the I/O buffer but not for the I/O buffer itself.)

  • The number of map registers required to translate the physical addresses in the scatter/gather list to logical addresses.

For information about the DMA transfer information that is provided by version 1 of the DMA_TRANSFER_INFO_XXX structure, see DMA_TRANSFER_INFO_V1.

An MDL describes the physical memory pages that underlie a locked-down, contiguous block of virtual memory. Typically, these physical memory pages are non-contiguous. An MDL chain is an ordered collection of MDLs that describes memory that can be used to buffer I/O data. Typically, the virtual memory regions described by the MDLs in the chain are non-contiguous. For more information about MDLs and MDL chains, see Using MDLs.

Requirements

Target platform

Desktop

Version

Available starting with Windows 8.

Header

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

IRQL

<= DISPATCH_LEVEL

See also

BuildScatterGatherListEx
CalculateScatterGatherList
DMA_OPERATIONS
DMA_TRANSFER_INFO
DMA_TRANSFER_INFO_V1
IoGetDmaAdapter
MapTransferEx

 

 

Send comments about this topic to Microsoft

Show: