PBUILD_SCATTER_GATHER_LIST callback function (wdm.h)

Article
11/24/2022

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

Syntax

PBUILD_SCATTER_GATHER_LIST PbuildScatterGatherList;

NTSTATUS PbuildScatterGatherList(
  [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 ScatterGatherLength
)
{...}

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

[in] ExecutionRoutine

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.

[in] Context

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

[in] ScatterGatherBuffer

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

[in] ScatterGatherLength

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

Return value

BuildScatterGatherList returns one of the following values:

Return code	Description
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

Requirement	Value
Minimum supported client	Available in Windows XP and later versions of Windows.
Target Platform	Desktop
Header	wdm.h (include Wdm.h)
IRQL	DISPATCH_LEVEL
DDI compliance rules	IrqlDispatch(wdm)