Export (0) Print
Expand All

GetScatterGatherList routine

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


NTSTATUS GetScatterGatherList(
  _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

DmaAdapter [in]

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

DeviceObject [in]

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

Mdl [in]

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

CurrentVa [in]

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

Length [in]

Specifies the length, in bytes, to be mapped.

ExecutionRoutine [in]

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

Context [in]

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

WriteToDevice [in]

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 codeDescription
STATUS_SUCCESS

The operation succeeded.

STATUS_INSUFFICIENT_RESOURCES

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.

STATUS_BUFFER_TOO_SMALL

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

Version

Available in Windows 2000 and later versions of Windows. Not supported in Windows 98 or Windows Me.

Header

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

IRQL

DISPATCH_LEVEL

DDI compliance rules

IrqlDispatch, IrqlDispatch(storport)

See also

DEVICE_OBJECT
DMA_ADAPTER
IoGetDmaAdapter
PutScatterGatherList
AllocateAdapterChannel
DMA_OPERATIONS
SCATTER_GATHER_LIST

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft