PMAP_TRANSFER callback function (wdm.h)

The MapTransfer routine sets up map registers for an adapter object to map a DMA transfer from a locked-down buffer.

Syntax

PMAP_TRANSFER PmapTransfer;

PHYSICAL_ADDRESS PmapTransfer(
  [in]      PDMA_ADAPTER DmaAdapter,
  [in]      PMDL Mdl,
  [in]      PVOID MapRegisterBase,
  [in]      PVOID CurrentVa,
  [in, out] PULONG Length,
  [in]      BOOLEAN WriteToDevice
)
{...}

Parameters

[in] DmaAdapter

Pointer to the DMA adapter object returned by IoGetDmaAdapter and previously passed to AllocateAdapterChannel for the current IRP's transfer request.

[in] Mdl

Pointer to one of the following: the MDL that describes the buffer at MdlAddress in the current IRP or the MDL that describes the common buffer set up by the driver of a subordinate device (auto-initialize mode).

[in] MapRegisterBase

Specifies the map registers allocated for the DMA operation. The system passes this value to the driver's AdapterControl routine.

[in] CurrentVa

Pointer to the current virtual address of the data to be transferred for a DMA transfer operation.

[in, out] Length

Specifies the length, in bytes, to be mapped. If the driver indicated that its device was a bus master with scatter/gather support when it called IoGetDmaAdapter, the value of Length on return from MapTransfer indicates how many bytes were mapped. Otherwise, the input and output values of Length are identical.

[in] WriteToDevice

Indicates the direction of the transfer operation: TRUE for a transfer from the locked-down buffer to the device.

Return value

MapTransfer returns the logical address of the region mapped, which the driver of a bus-master adapter can use. Drivers of devices that use a system DMA controller cannot use this value and should ignore it.

Remarks

MapTransfer is not a system routine that can be called directly by name. This routine is callable only by pointer from the address returned in a DMA_OPERATIONS structure. Drivers obtain the address of this routine by calling IoGetDmaAdapter.

The DmaAdapter must have already been allocated as a result of the driver's preceding call to AllocateAdapterChannel.

The number of map registers that can be set up cannot exceed the maximum returned when the driver called IoGetDmaAdapter.

A driver can get the initial CurrentVa for the start of a packet-based DMA transfer by calling MmGetMdlVirtualAddress. However, the value returned is an index into the Mdl, rather than a valid virtual address. If the driver must split a large transfer request into more than one DMA operation, it must update CurrentVa and Length for each DMA operation.

The driver of a bus-master device with scatter/gather support can use the returned logical address and updated Length value to build a scatter/gather list, calling MapTransfer repeatedly until it has used all available map registers for the transfer operation. However, such a driver could more simply use the GetScatterGatherList routine.

Requirements

Requirement Value
Minimum supported client Available starting with Windows 2000.
Target Platform Desktop
Header wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL <= DISPATCH_LEVEL
DDI compliance rules IrqlDispatch(wdm)

See also

ADDRESS_AND_SIZE_TO_SPAN_PAGES

AllocateAdapterChannel

AllocateCommonBuffer

DMA_ADAPTER

FlushAdapterBuffers

FreeAdapterChannel

FreeMapRegisters

IoGetDmaAdapter

KeFlushIoBuffers

MmGetMdlVirtualAddress