PGET_SCATTER_GATHER_LIST回呼函式 (wdm.h)

發行項
02/29/2024

GetScatterGatherList 例程會透過系統 DMA 控制器或總線主機適配卡，代表目標裝置物件準備 DMA 散佈/收集作業。

語法

PGET_SCATTER_GATHER_LIST PgetScatterGatherList;

NTSTATUS PgetScatterGatherList(
  [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] DmaAdapter

IoGetDmaAdapter 所傳回之DMA_ADAPTER結構的指標，代表總線主機適配卡或 DMA 控制器。

[in] DeviceObject

代表 DMA 作業目標裝置之裝置物件的指標。

[in] Mdl

描述目前 IRP 中 MdlAddress 之緩衝區的 MDL 指標。

[in] CurrentVa

MDL 中目前虛擬位址的指標，用於對應 DMA 傳輸作業的緩衝區。

[in] Length

指定要對應的長度，以位元組為單位。

[in] ExecutionRoutine

驅動程式提供的 AdapterListControl 例程指標，當系統 DMA 控制器或總線主機配接器可用時，會在DISPATCH_LEVEL呼叫此例程。

[in] Context

呼叫驅動程式時傳遞至驅動程式 AdapterListControl 例程之驅動程式決定內容的指標。

[in] WriteToDevice

指出 DMA 傳輸的方向：如果是從緩衝區到裝置的傳輸，則為 TRUE ，否則 為 FALSE 。

傳回值

此例程可以傳回下列其中一個NTSTATUS值。

傳回碼	Description
STATUS_SUCCESS	作業成功。
STATUS_INSUFFICIENT_RESOURCES	例程無法配置足夠的記憶體，或傳輸所需的對應緩存器數目大於 IoGetDmaAdapter所傳回的值。
STATUS_BUFFER_TOO_SMALL	緩衝區太小，無法進行要求的傳輸。

備註

GetScatterGatherList 例程會動態配置緩衝區來保存散佈/收集清單。如需緩衝區配置失敗的可能NTSTATUS值，請參閱傳回值。

GetScatterGatherList 不是可直接依名稱呼叫的系統例程。這個例程只能由 DMA_OPERATIONS結構中傳回之位址的指標呼叫。驅動程式會呼叫 IoGetDmaAdapter來取得此例程的位址。

只要有適當的 DMA 信道和任何必要的地圖緩存器可用， GetScatterGatherList 就會建立散佈/收集清單、初始化對應緩存器，然後呼叫驅動程式提供的 AdapterListControl 例程來執行 I/O 作業。

GetScatterGatherList 會針對執行散佈/收集 DMA 的驅動程序，結合 AllocateAdapterChannel 和 MapTransfer 例程的動作。 GetScatterGatherList 會決定傳輸所需的地圖緩存器數目、配置地圖緩存器、對應 DMA 的緩衝區，以及填入散佈/收集清單。然後它會呼叫提供的 AdapterListControl 例程，並將指標傳遞至 ScatterGather 中的散佈/收集清單。驅動程式應該保留此指標以供呼叫 PutScatterGatherList 時使用。請注意， GetScatterGatherList 沒有套用至 AllocateAdapterChannel 的佇列限制。

在其 AdapterListControl 例程中，驅動程式應該執行 I/O。從驅動程式提供的例程傳回時， GetScatterGatherList 會保留地圖緩存器，但釋放 DMA 配接器結構。驅動程式必須呼叫 PutScatterGatherList (，以排清緩衝區) ，才能存取緩衝區中的數據。

此例程可以處理鏈結的 MDL，前提是所有鏈結的 MDL 所需的地圖緩存器總數不會超過可用的地圖緩存器數目。

規格需求

需求	值
最低支援的用戶端	可在 Windows 2000 和更新版本的 Windows 中使用。 Windows 98 或 Windows Me 不支援。
目標平台	桌面
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
IRQL	DISPATCH_LEVEL
DDI 合規性規則	IrqlDispatch (storport) 、IrqlDispatch (storport ) 、 IrqlDispatch (wdm)