PBUILD_SCATTER_GATHER_LIST callback function (wdm.h)
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) |