IoMapTransfer

PHYSICAL_ADDRESS
    IoMapTransfer(
        IN PADAPTER_OBJECT  AdapterObject,
        IN PMDL  Mdl,
        IN PVOID  MapRegisterBase,
        IN PVOID  CurrentVa,
        IN OUT PULONG  Length,
        IN BOOLEAN  WriteToDevice
        );

IoMapTransfer sets up a number of map registers (up to the number returned by HalGetAdapter) for the given adapter object to map a transfer from a locked-down buffer specified by Mdl, the given CurrentVa into the MDL, Length in bytes to be transferred, and transfer direction.

Parameters

AdapterObject

Points to the adapter object pointer returned by HalGetAdapter and already passed in a call to IoAllocateAdapterChannel for the current IRP’s transfer request.

Mdl

Points to the MDL describing the buffer either in the current IRP at MdlAddress or the MDL that the driver of a slave device using auto-initialize mode set up to describe the driver’s common buffer.

MapRegisterBase

Points to the handle returned by IoAllocateAdapterChannel, which the driver already called for the current IRP.

CurrentVa

Points to the current virtual address in the buffer, described by the Mdl, to be mapped for a DMA transfer operation.

Length

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

WriteToDevice

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

Return Value

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

Comments

The AdapterObject must have already been allocated to the driver in a preceding call to IoAllocateAdapterChannel.

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

The initial CurrentVa for the start of a packet-based DMA transfer can be obtained 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, CurrentVa and Length must be updated for each DMA operation.

The driver of a busmaster device with scatter/gather support can use the returned logical address and updated Length value to build a scatter/gather list, calling IoMapTransfer repeatedly until it has used all available map registers for the transfer operation.

Callers of IoMapTransfer must be running at IRQL <= DISPATCH_LEVEL.

See Also

ADDRESS_AND_SIZE_TO_SPAN_PAGES, HalAllocateCommonBuffer, HalGetAdapter, IoAllocateAdapterChannel, IoFlushAdapterBuffers, IoFreeAdapterChannel, IoFreeMapRegisters, KeFlushIoBuffers, MmGetMdlVirtualAddress