PGET_SCATTER_GATHER_LIST callback function (wdm.h)

The GetScatterGatherList routine prepares the system for a DMA scatter/gather operation on behalf of the target device object, through either the system DMA controller or a bus-master adapter.

Syntax

PGET_SCATTER_GATHER_LIST PgetScatterGatherList;

NTSTATUS PgetScatterGatherList(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PMDL Mdl,
  [in] PVOID CurrentVa,
  [in] ULONG Length,
  [in] PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in] PVOID Context,
  [in] BOOLEAN WriteToDevice
)
{...}

Parameters

[in] DmaAdapter

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

[in] DeviceObject

Pointer to the device object that represents the target device for the DMA operation.

[in] Mdl

Pointer to the MDL that describes the buffer at MdlAddress in the current IRP.

[in] CurrentVa

Pointer to the current virtual address in the MDL for the buffer to be mapped for a DMA transfer operation.

[in] Length

Specifies the length, in bytes, to be mapped.

[in] ExecutionRoutine

Pointer to a driver-supplied AdapterListControl routine, which is called at DISPATCH_LEVEL when the system DMA controller or bus-master adapter is available.

[in] Context

Pointer to the driver-determined context passed to the driver's AdapterListControl routine when it is called.

[in] WriteToDevice

Indicates the direction of the DMA transfer: TRUE for a transfer from the buffer to the device, and FALSE otherwise.

Return value

This routine can return one of the following NTSTATUS values.

Remarks

The GetScatterGatherList routine dynamically allocates a buffer to hold the scatter/gather list. For possible NTSTATUS values if the buffer allocation fails, see the return value.

GetScatterGatherList 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.

As soon as the appropriate DMA channel and any necessary map registers are available, GetScatterGatherList creates a scatter/gather list, initializes the map registers, and then calls the driver-supplied AdapterListControl routine to carry out the I/O operation.

GetScatterGatherList combines the actions of the AllocateAdapterChannel and MapTransfer routines for drivers that perform scatter/gather DMA. GetScatterGatherList determines how many map registers are required for the transfer, allocates the map registers, maps the buffers for DMA, and fills in the scatter/gather list. It then calls the supplied AdapterListControl routine, passing a pointer to the scatter/gather list in ScatterGather. The driver should retain this pointer for use when calling PutScatterGatherList. Note that GetScatterGatherList does not have the queuing restrictions that apply to AllocateAdapterChannel.

In its AdapterListControl routine, the driver should perform the I/O. On return from the driver-supplied routine, GetScatterGatherList keeps the map registers but frees the DMA adapter structure. The driver must call PutScatterGatherList (which flushes the buffers) before it can access the data in the buffer.

This routine can handle chained MDLs, provided that the total number of map registers required by all chained MDLs does not exceed the number of map registers that are available.

Requirements

See also

AllocateAdapterChannel

DEVICE_OBJECT

DMA_ADAPTER

DMA_OPERATIONS

IoGetDmaAdapter

PutScatterGatherList

SCATTER_GATHER_LIST