PGET_SCATTER_GATHER_LIST_EX回呼函式 (wdm.h)

發行項
03/05/2024

GetScatterGatherListEx 例程會配置 DMA 傳輸所需的資源、建置散佈/收集清單，並呼叫驅動程式提供的 AdapterListControl 例程來起始 DMA 傳輸。

警告

請勿針對系統 DMA 裝置呼叫此例程。

語法

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
)
{...}

參數

[in] DmaAdapter

DMA_ADAPTER 結構的指標。這個結構是代表驅動程式總線主要 DMA 裝置的配接器物件。呼叫端從先前呼叫IoGetDmaAdapter 例程取得此指標。

[in] DeviceObject

DEVICE_OBJECT 結構的指標。此結構是 PDO (實體裝置物件，) ，代表所要求 DMA 作業的目標裝置。

[in] DmaTransferContext

已初始化 DMA 傳輸內容的指標。此內容是由先前呼叫 InitializeDmaTransferContext 例程所初始化。此內容在所有適配卡配置要求中都必須是唯一的。若要取消擱置的配置要求，呼叫端必須將 DMA 傳輸內容提供給 CancelAdapterChannel 例程。

[in] Mdl

MDL 鏈結的指標，描述虛擬記憶體中鎖定緩衝區集合的實體頁面配置。 DMA 傳輸的散佈/收集清單會使用 Offset 和 Length 參數所指定的此記憶體區域。如需 MDL 鏈結的詳細資訊，請參閱使用 MDLs。

[in] Offset

散佈圖/收集 DMA 傳輸的起始位移。此參數是從 MDL 鏈結中第一個 MDL 緩衝區開頭的位元組位移。如果 MDL 鏈結中的 MDL 指定緩衝區空間的 N 個字節總數， 則 Offset 的有效值會介於 0 到 N–1 的範圍內。

[in] Length

DMA 傳輸的長度，以位元組為單位。如果 MDL 鏈結指定緩衝區空間的 N 個字節總數， 則 Length 的有效值會介於 1 到 N–Offset 的範圍內。

[in] Flags

配接器通道配置旗標。支援下列旗標：

旗標	意義
DMA_SYNCHRONOUS_CALLBACK	GetScatterGatherListEx 例程會以同步方式呼叫。如果已設定此旗標，而且必要的 DMA 資源無法立即使用，則呼叫會失敗並傳回STATUS_INSUFFICIENT_RESOURCES。

如果已設定 DMA_SYNCHRONOUS_CALLBACK 旗標， ExecutionRoutine 參數是選擇性的，而且可以是 NULL。如果未設定此旗標， ExecutionRoutine 必須是有效的非 NULL 指標。如需此旗標的詳細資訊，請參閱一節。

[in, optional] ExecutionRoutine

驅動程式提供的 AdapterListControl 例程指標，起始驅動程式的 DMA 傳輸。 I/O 管理員會在為配接器物件配置必要的資源之後呼叫 AdapterListControl 例程。 在 AdapterListControl 例程傳回之後，I/O 管理員會自動釋放配接器對象和為此物件配置的資源。

如果已設定 DMA_SYNCHRONOUS_CALLBACK 旗標， ExecutionRoutine 參數是選擇性的，而且可以是 NULL。如果此參數為 NULL，呼叫端可以使用 GetScatterGatherListEx 所配置的資源，在 GetScatterGatherListEx 傳回之後執行 DMA 傳輸。如需詳細資訊，請參閱＜備註＞一節。

[in, optional] Context

驅動程式決定的配接器控件內容。此內容會以 Context 參數的形式傳遞至 AdapterListControl 例程。

[in] WriteToDevice

DMA 傳輸的方向。針對寫入作業將此參數設定為 TRUE，以將數據從記憶體傳輸到裝置。針對讀取作業將此參數設定為 FALSE，以將資料從裝置傳輸到記憶體。

[in, optional] DmaCompletionRoutine

未使用。設定為 NULL。

[in, optional] CompletionContext

未使用。設定為 NULL。

[out, optional] ScatterGatherList

變數的指標，例程會將指標寫入已配置的散佈/收集清單。此參數指向 SCATTER_GATHER_LIST 結構。例程會配置這個結構及其所指向 的SCATTER_GATHER_ELEMENT 陣列。

ScatterGatherList 參數是選擇性的，如果 ExecutionRoutine 參數為非 NULL，則可以是 NULL。

如果已設定 DMA_SYNCHRONOUS_CALLBACK 旗標， 且 ExecutionRoutine 參數為 NULL， 則 ScatterGatherList 必須是有效的非 NULL 指標。如果 ExecutionRoutine 不是 NULL， 則 ScatterGatherList 是選擇性的，如果呼叫驅動程式不需要散佈/收集清單，則可以是 NULL 。如果設定DMA_SYNCHRONOUS_CALLBACK旗標且 ScatterGatherList 和 ExecutionRoutine 都是 NULL，或未設定DMA_SYNCHRONOUS_CALLBACK旗標且 ExecutionRoutine 為 NULL，GetScatterGatherListEx 呼叫就會失敗。

傳回值

如果呼叫成功，GetScatterGatherListEx 會傳回STATUS_SUCCESS。可能的錯誤傳回值包括下列狀態代碼：

傳回碼	Description
STATUS_INVALID_PARAMETERS	例程失敗，因為呼叫端傳遞的參數值無效。
STATUS_INSUFFICIENT_RESOURCES	例程無法配置 DMA 傳輸所需的資源。

備註

GetScatterGatherListEx 不是可直接依名稱呼叫的系統例程。這個例程只能由 DMA_OPERATIONS結構中 傳回之位址的指標呼叫。驅動程式會呼叫IoGetDmaAdapter，並將DeviceDescription參數的Version成員設定為DEVICE_DESCRIPTION_VERSION3，以取得此例程的位址。如果 IoGetDmaAdapter 傳回 NULL，則您的平台上無法使用例程。

僅適用於總線主機適配卡的 GetScatterGatherListEx 。請勿將此例程用於系統 DMA 配接器。

總線主機裝置的驅動程式可以使用 GetScatterGatherListEx ，將 AllocateAdapterChannelEx 和 MapTransferEx 例程所執行的作業合併成一個呼叫。 GetScatterGatherListEx 會執行下列作業：

配置 DMA 傳輸所需的資源。
根據 Mdl、 Offset 和 Length 參數的值，建置散佈/收集清單。
呼叫驅動程式提供的 AdapterListControl 例程，並將散佈/收集清單提供給這個例程做為參數。

配置的資源會在 AdapterListControl 例程傳回之後自動釋放。如果 GetScatterGatherListEx 是以同步方式呼叫 (也就是說，如果 DMA_SYNCHRONOUS_CALLBACK 旗標設定) ，則可以省略 AdapterListControl 例程。在此情況下，呼叫端會使用已配置的資源，在 GetScatterGatherListEx 傳回之後起始 DMA 傳輸。呼叫端必須明確釋放這些資源。

根據預設， GetScatterGatherListEx 會 以異步方式傳回，而不需要等待要求的資源配置完成。在此傳回之後，呼叫端可以視需要呼叫 CancelAdapterChannel 例程來取消擱置的配置要求。

如果呼叫驅動程式設定 DMA_SYNCHRONOUS_CALLBACK 旗標， GetScatterGatherListEx 例程的行為如下：

如果要求的資源無法立即使用， GetScatterGatherListEx 不會等候資源、不會建置散佈/收集清單，也不會呼叫 AdapterListControl 例程。相反 地，GetScatterGatherListEx 會失敗並傳回STATUS_INSUFFICIENT_RESOURCES。
如果已設定 DMA_SYNCHRONOUS_CALLBACK 旗標，則不需要驅動程式提供 AdapterListControl 例程。
如果驅動程式提供 AdapterListControl 例程， DMA_SYNCHRONOUS_CALLBACK 旗標表示在呼叫線程的內容中呼叫此例程，然後再傳回 GetScatterGatherListEx 。
如果驅動程式未提供 AdapterListControl 例程，驅動程式可以在 GetScatterGatherListEx 傳回之後，使用配置的資源和散佈/收集清單。在此情況下，驅動程式必須提供有效的非 NULL ScatterGatherList 指標。此外，在驅動程式起始 DMA 傳輸之後，驅動程式必須呼叫 FreeAdapterObject 例程，以釋放 GetScatterGatherListEx 為配接器物件配置的資源。

GetScatterGatherListEx 是 GetScatterGatherList 例程的擴充版本。下列功能僅適用於擴充版本：

GetScatterGatherListEx 類似於 BuildScatterGatherListEx 例程，不同之處在於 GetScatterGatherListEx 會自動配置散佈/收集清單的緩衝區。

規格需求

需求	值
最低支援的用戶端	從 Windows 8 開始提供。
目標平台	桌面
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
IRQL	<= DISPATCH_LEVEL