PGET_SCATTER_GATHER_LIST_EX callback function (wdm.h)

Article
01/13/2023

The GetScatterGatherListEx routine allocates the resources that are required for a DMA transfer, builds a scatter/gather list, and calls the driver-supplied AdapterListControl routine to initiate the DMA transfer.

Caution

Do not call this routine for a system DMA device.

Syntax

PGET_SCATTER_GATHER_LIST_EX PgetScatterGatherListEx;

NTSTATUS PgetScatterGatherListEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            PMDL Mdl,
  [in]            ULONGLONG Offset,
  [in]            ULONG Length,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in, optional]  PVOID Context,
  [in]            BOOLEAN WriteToDevice,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext,
  [out, optional] PSCATTER_GATHER_LIST *ScatterGatherList
)
{...}

Parameters

[in] DmaAdapter

A pointer to a DMA_ADAPTER structure. This structure is the adapter object that represents the driver's bus-master DMA device. The caller obtained this pointer from a previous call to the IoGetDmaAdapter routine.

[in] DeviceObject

A pointer to a DEVICE_OBJECT structure. This structure is the physical device object (PDO) that represents the target device for the requested DMA operation.

[in] DmaTransferContext

A pointer to an initialized DMA transfer context. This context was initialized by a previous call to the InitializeDmaTransferContext routine. This context must be unique across all adapter allocation requests. To cancel a pending allocation request, the caller must supply the DMA transfer context for the request to the CancelAdapterChannel routine.

[in] Mdl

A pointer to an MDL chain that describes the physical page layout for a collection of locked-down buffers in virtual memory. The scatter/gather list for the DMA transfer will use the region of this memory that is specified by the Offset and Length parameters. For more information about MDL chains, see Using MDLs.

[in] Offset

The starting offset for the scatter/gather DMA transfer. This parameter is a byte offset from the start of the buffer in the first MDL in the MDL chain. If the MDLs in the MDL chain specify a total of N bytes of buffer space, valid values of Offset are in the range 0 to N–1.

[in] Length

The length, in bytes, of the DMA transfer. If the MDL chain specifies a total of N bytes of buffer space, valid values of Length are in the range 1 to N–Offset.

[in] Flags

The adapter channel allocation flags. The following flag is supported:

Flag	Meaning
DMA_SYNCHRONOUS_CALLBACK	The GetScatterGatherListEx routine is called synchronously. If this flag is set, and the required DMA resources are not immediately available, the call fails and returns STATUS_INSUFFICIENT_RESOURCES.

If the DMA_SYNCHRONOUS_CALLBACK flag is set, the ExecutionRoutine parameter is optional and can be NULL. If this flag is not set, ExecutionRoutine must be a valid, non-NULL pointer. For more information about this flag, see the Remarks section.

[in, optional] ExecutionRoutine

A pointer to the driver-supplied AdapterListControl routine that initiates the DMA transfer for the driver. The I/O manager calls the AdapterListControl routine after the required resources are allocated for the adapter object. After the AdapterListControl routine returns, the I/O manager automatically frees the adapter object and the resources that were allocated for this object.

If the DMA_SYNCHRONOUS_CALLBACK flag is set, the ExecutionRoutine parameter is optional and can be NULL. If this parameter is NULL, the caller can use the resources allocated by GetScatterGatherListEx to perform the DMA transfer after GetScatterGatherListEx returns. For more information, see the Remarks section.

[in, optional] Context

The driver-determined, adapter-control context. This context is passed to the AdapterListControl routine as the Context parameter.

[in] WriteToDevice

The direction of the DMA transfer. Set this parameter to TRUE for a write operation, which transfers data from memory to the device. Set this parameter to FALSE for a read operation, which transfers data from the device to memory.

[in, optional] DmaCompletionRoutine

Not used. Set to NULL.

[in, optional] CompletionContext

Not used. Set to NULL.

[out, optional] ScatterGatherList

A pointer to a variable into which the routine writes a pointer to the allocated scatter/gather list. This parameter points to a SCATTER_GATHER_LIST structure. The routine allocates this structure and the SCATTER_GATHER_ELEMENT array that it points to.

The ScatterGatherList parameter is optional and can be NULL if the ExecutionRoutine parameter is non-NULL.

If the DMA_SYNCHRONOUS_CALLBACK flag is set and the ExecutionRoutine parameter is NULL, ScatterGatherList must be a valid, non-NULL pointer. If ExecutionRoutine is non-NULL, ScatterGatherList is optional and can be NULL if the calling driver does not require the scatter/gather list. The GetScatterGatherListEx call fails if the DMA_SYNCHRONOUS_CALLBACK flag is set and ScatterGatherList and ExecutionRoutine are both NULL, or if the DMA_SYNCHRONOUS_CALLBACK flag is not set and ExecutionRoutine is NULL.

Return value

GetScatterGatherListEx returns STATUS_SUCCESS if the call is successful. Possible error return values include the following status codes:

Return code	Description
STATUS_INVALID_PARAMETERS	The routine failed due to invalid parameter values passed by the caller.
STATUS_INSUFFICIENT_RESOURCES	The routine failed to allocate resources required for the DMA transfer.

Remarks

GetScatterGatherListEx 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_VERSION3. If IoGetDmaAdapter returns NULL, the routine is not available on your platform.

Use GetScatterGatherListEx only for bus-master adapters. Do not use this routine for a system DMA adapter.

The driver of a bus-master device can use GetScatterGatherListEx to combine the operations performed by the AllocateAdapterChannelEx and MapTransferEx routines into a one call. GetScatterGatherListEx performs the following operations:

Allocates the resources that are required for the DMA transfer.
Builds a scatter/gather list based on the values of the Mdl, Offset, and Length parameters.
Calls the driver-supplied AdapterListControl routine and supplies the scatter/gather list to this routine as a parameter.

The allocated resources are automatically released after the AdapterListControl routine returns. If GetScatterGatherListEx is called synchronously (that is, if the DMA_SYNCHRONOUS_CALLBACK flag is set), the AdapterListControl routine can be omitted. In this case, the caller uses the allocated resources to initiate the DMA transfer after GetScatterGatherListEx returns. The caller must explicitly release these resources.

By default, GetScatterGatherListEx returns asynchronously, without waiting for the requested resource allocation to complete. After this return, the caller can, if necessary, cancel the pending allocation request by calling the CancelAdapterChannel routine.

If the calling driver sets the DMA_SYNCHRONOUS_CALLBACK flag, the GetScatterGatherListEx routine behaves as follows:

If the requested resources are not immediately available, GetScatterGatherListEx does not wait for resources, does not build a scatter/gather list, and does not call the AdapterListControl routine. Instead, GetScatterGatherListEx fails and returns STATUS_INSUFFICIENT_RESOURCES.
The driver is not required to supply an AdapterListControl routine if the DMA_SYNCHRONOUS_CALLBACK flag is set.
If the driver supplies an AdapterListControl routine, the DMA_SYNCHRONOUS_CALLBACK flag indicates that this routine is to be called in the context of the calling thread, before GetScatterGatherListEx returns.
If the driver does not supply an AdapterListControl routine, the driver can use the allocated resources and scatter/gather list after GetScatterGatherListEx returns. In this case, the driver must supply a valid, non-NULL ScatterGatherList pointer. In addition, after the driver initiates the DMA transfer, the driver must call the FreeAdapterObject routine to free the resources that GetScatterGatherListEx allocated for the adapter object.

GetScatterGatherListEx is an extended version of the GetScatterGatherList routine. The following features are available only in the extended version:

GetScatterGatherListEx is similar to the BuildScatterGatherListEx routine, except that GetScatterGatherListEx automatically allocates the buffer for the scatter/gather list.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 8.
Target Platform	Desktop
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL