BuildScatterGatherList routine

The BuildScatterGatherList routine prepares the system for a DMA operation, using a driver-supplied buffer to build the scatter/gather list.

Syntax


NTSTATUS BuildScatterGatherList(
  _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,
  _In_  PVOID ScatterGatherBuffer,
  _In_  ULONG ScatterGatherBufferLength
);

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 specified by the MdlAddress member of 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, of the buffer to be mapped.

ExecutionRoutine [in]

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

Context [in]

Pointer to the driver-determined context passed to ExecutionRoutine 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.

ScatterGatherBuffer [in]

Pointer to the caller-supplied buffer that the routine fills with a SCATTER_GATHER_LIST structure.

ScatterGatherBufferLength [in]

Specifies the size, in bytes, of the buffer passed in the ScatterGatherBuffer parameter.

Return value

BuildScatterGatherList returns one of the following values:

Return codeDescription
STATUS_SUCCESS

The operation is completed successfully.

STATUS_INSUFFICIENT_RESOURCES

The system has insufficient map registers available for the transfer.

STATUS_BUFFER_TOO_SMALL

The specified Length is too big to fit within the buffer.

 

Remarks

BuildScatterGatherList is not a system routine that can be called directly by name. This routine can be called only by pointer from the address returned in a DMA_OPERATIONS structure. Drivers obtain the address of this routine by calling IoGetDmaAdapter with the Version member of the DeviceDescription parameter set to DEVICE_DESCRIPTION_VERSION2. If IoGetDmaAdapter returns NULL, the routine is not available on your platform.

BuildScatterGatherList performs the same operation as GetScatterGatherList, except that it uses the buffer supplied in the ScatterGatherBuffer parameter to hold the scatter/gather list that it creates. In contrast, GetScatterGatherList dynamically allocates a buffer to hold the scatter/gather list. If insufficient memory is available to allocate the buffer, GetScatterGatherList can fail with a STATUS_INSUFFICIENT_RESOURCES error. Drivers that must avoid this scenario can preallocate a buffer to hold the scatter/gather list, and use BuildScatterGatherList instead.

A driver can use the CalculateScatterGatherList routine to determine the size of buffer to allocate to hold the scatter/gather list.

The driver should retain the pointer to the scatter/gather list in ScatterGatherBuffer for use when the driver calls PutScatterGatherList. The driver must call PutScatterGatherList (which flushes the list) before it can access the data in the list.

Requirements

Version

Available in Windows XP and later versions of Windows.

Header

Ntddk.h (include Ntddk.h)

IRQL

DISPATCH_LEVEL

DDI compliance rules

IrqlDispatch

See also

BuildMdlFromScatterGatherList
CalculateScatterGatherList
DEVICE_DESCRIPTION
DEVICE_OBJECT
DMA_ADAPTER
DMA_OPERATIONS
GetScatterGatherList
IoGetDmaAdapter
PutScatterGatherList
SCATTER_GATHER_LIST

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft