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.
| Return code | Description |
|---|---|
|
The operation succeeded. |
|
The routine could not allocate sufficient memory or the number of map registers required for the transfer is larger than the value returned by IoGetDmaAdapter. |
|
The buffer is too small for the requested transfer. |
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
| Requirement | Value |
|---|---|
| Minimum supported client | Available in Windows 2000 and later versions of Windows. Not supported in Windows 98 or Windows Me. |
| Target Platform | Desktop |
| Header | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | DISPATCH_LEVEL |
| DDI compliance rules | IrqlDispatch(storport), IrqlDispatch(storport), IrqlDispatch(wdm) |