BuildScatterGatherList routine

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


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


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

The operation is completed successfully.


The system has insufficient map registers available for the transfer.


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



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.


Target platform


Available in Windows XP and later versions of Windows.


Ntddk.h (include Ntddk.h)



DDI compliance rules


See also




Send comments about this topic to Microsoft