PBUILD_SCATTER_GATHER_LIST_EX回呼函式 （wdm.h）

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

語法

PBUILD_SCATTER_GATHER_LIST_EX PbuildScatterGatherListEx;

NTSTATUS PbuildScatterGatherListEx(
  [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]            PVOID ScatterGatherBuffer,
  [in]            ULONG ScatterGatherLength,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext,
  [out, optional] PVOID ScatterGatherList
)
{...}

參數

[in] DmaAdapter

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

[in] DeviceObject

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

[in] DmaTransferContext

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

[in] Mdl

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

[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 旗標，則 ExecutionRoutine 參數是選擇性的，而且可以 NULL。 如果未設定此旗標，ExecutionRoutine 必須是有效的非NULL 指標。 如需此旗標的詳細資訊，請參閱一節。

[in, optional] ExecutionRoutine

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

如果已設定 DMA_SYNCHRONOUS_CALLBACK 旗標，ExecutionRoutine 是選擇性的，而且可以 NULL。 如果 ExecutionRoutineNULL，則呼叫端可以使用 buildScatterGatherListEx 所配置的資源。 如需詳細資訊，請參閱一節。

[in, optional] Context

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

[in] WriteToDevice

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

[in] ScatterGatherBuffer

呼叫端配置的緩衝區指標，例程會將 DMA 傳輸的散佈/收集清單寫入其中。 此清單開頭為 SCATTER_GATHER_LIST 結構，後面接著 SCATTER_GATHER_ELEMENT 陣列。

[in] ScatterGatherLength

在 ScatterGatherBuffer 參數中傳遞之緩衝區的大小，以位元組為單位。 配置的緩衝區大小必須夠大，才能包含散佈/收集清單，以及操作系統在此緩衝區中儲存的內部數據。 若要計算所需的緩衝區大小，請呼叫 GetDmaTransferInfo 或 CalculateScatterGatherList 例程。

[in, optional] DmaCompletionRoutine

未使用。 設定為 NULL。

[in, optional] CompletionContext

未使用。 設定為 NULL。

[out, optional] ScatterGatherList

變數的指標，例程會將指標寫入 DMA 傳輸的散佈/收集清單。 此清單開頭為 SCATTER_GATHER_LIST 結構，其中包含 SCATTER_GATHER_ELEMENT 陣列的指標。 此輸出指標一律符合 ScatterGatherBuffer 參數值。

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

傳回值

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

言論

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

請只針對總線主要適配卡使用 BuildScatterGatherListEx。 請勿將此例程用於系統 DMA 配接器。

BuildScatterGatherListEx 類似於 getScatterGatherListEx 例程 ，不同之處在於呼叫端需要呼叫者配置散佈/收集清單的緩衝區。

例如，驅動程式可能會在裝置初始化期間預先配置一或多個散佈/收集緩衝區。 稍後，BuildScatterGatherListEx 呼叫，使用這類緩衝區的呼叫可能會在記憶體不足的情況下成功，而可能導致 GetScatterGatherListEx 呼叫失敗。

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

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

• 如果要求的資源無法立即使用，BuildScatterGatherListEx 不會等候資源、未建置散佈/收集清單，也不會呼叫 AdapterListControl 例程。 相反地，BuildScatterGatherListEx 會失敗並傳回STATUS_INSUFFICIENT_RESOURCES。

• 如果設定 DMA_SYNCHRONOUS_CALLBACK 旗標，則不需要驅動程式提供 AdapterListControl 例程。

• 如果驅動程式提供 AdapterListControl 例程，DMA_SYNCHRONOUS_CALLBACK 旗標會指出此例程是在呼叫線程的內容中呼叫，BuildScatterGatherListEx 傳回。

• 如果驅動程式未提供 AdapterListControl 例程，驅動程式可以在傳回 buildScatterGatherList Ex 之後，使用配置的資源和散佈/收集清單。 在此情況下，驅動程式必須提供有效的非NULLScatterGatherList 指標。 此外，驅動程式起始的 DMA 傳輸完成之後，驅動程式必須呼叫 FreeAdapterObject 例程，以釋放配置給配接器對象的 BuildScatterGatherListEx 的資源。

BuildScatterGatherListEx 是 BuildScatterGatherList 例程的擴充版本。 下列清單摘要說明只能在擴充版本中使用的功能：

要求

另請參閱

AdapterListControl

AllocateAdapterChannelEx

CalculateScatterGatherList

DMA_OPERATIONS

DmaCompletionRoutine

FreeAdapterObject

GetScatterGatherList

GetScatterGatherListEx

MapTransferEx