DMA_COMPLETION_ROUTINE回呼函式 (wdm.h)

DmaCompletionRoutine回呼常式會通知驅動程式先前要求完成此傳輸的系統 DMA 傳輸。

語法

DMA_COMPLETION_ROUTINE DmaCompletionRoutine;

void DmaCompletionRoutine(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PVOID CompletionContext,
  [in] DMA_COMPLETION_STATUS Status
)
{...}

參數

[in] DmaAdapter

DMA_ADAPTER結構的指標。 這個結構是代表驅動程式系統 DMA 通道的配接器物件。

[in] DeviceObject

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

[in] CompletionContext

DmaCompletionRoutine常式之驅動程式決定內容的指標。 此內容是驅動程式先前傳遞至啟動系統 DMA 傳輸之MapTransferEx呼叫的CompletionCoNtext參數值。

[in] Status

DMA 傳輸的完成狀態。 此參數是 DMA_COMPLETION_STATUS 列舉值,指出 DMA 傳輸是否已順利完成。

傳回值

備註

作為選項,驅動程式可以實作 DmaCompletionRoutine 常式。 當驅動程式要求系統 DMA 傳輸時,驅動程式可以使用要求來提供此常式的指標。 DMA 傳輸完成之後,會自動呼叫 DmaCompletionRoutine 常式來通知驅動程式。

只有在驅動程式要求的 DMA 傳輸使用系統 DMA 控制器,在 DMA 傳輸完成之後,才會呼叫驅動程式的 DmaCompletionRoutine 常式。 使用匯流排主機 DMA 裝置或使用系統 DMA 控制器而不會產生中斷的驅動程式,必須使用其他方法來判斷 DMA 傳輸何時完成。 例如,此驅動程式可能會使用計時器中斷定期輪詢 DMA 傳輸的狀態。

驅動程式可以提供 DmaCompletionRoutine 常式的指標,做為 MapTransferEx 常式的選擇性參數。

範例

若要定義 DmaCompletionRoutine 回呼常式,您必須先提供函式宣告來識別您要定義的回呼常式類型。 Windows 提供一組驅動程式的回呼函式類型。 使用回呼函式類型宣告函式有助於 驅動程式的程式碼分析靜態驅動程式驗證器 (SDV) ,以及其他驗證工具尋找錯誤,而且這是撰寫 Windows 作業系統驅動程式的需求。

例如,若要定義名為 MyDmaCompletionRoutineDmaCompletionRoutine回呼常式,請使用 DMA_COMPLETION_ROUTINE 類型,如下列程式碼範例所示:

DMA_COMPLETION_ROUTINE MyDmaCompletionRoutine;

然後,實作回呼常式,如下所示:


_Use_decl_annotations_
VOID
  MyDmaCompletionRoutine(
    PDMA_ADAPTER DmaAdapter,
    PDEVICE_OBJECT DeviceObject,
    PVOID CompletionContext,
    DMA_COMPLETION_STATUS Status
    )
  {
      // Function body
  }

DMA_COMPLETION_ROUTINE函式類型定義于 Wdm.h 標頭檔中。 若要在執行程式碼分析工具時更精確地識別錯誤,請務必將 Use_decl_annotations 批註新增至函式定義。 Use_decl_annotations注釋可確保使用標頭檔中套用至DMA_COMPLETION_ROUTINE函式類型的注釋。 如需函數宣告需求的詳細資訊,請參閱 使用 WDM 驅動程式的函式角色類型來宣告函式。 如需 Use_decl_annotations的詳細資訊,請參閱 標注函式行為

必要條件

   
最低支援的用戶端 從 Windows 8 開始提供。
目標平臺 桌面
標頭 wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
IRQL 在 DISPATCH_LEVEL呼叫。

另請參閱

BuildScatterGatherListEx

DEVICE_OBJECT

DMA_ADAPTER

DMA_COMPLETION_STATUS

DMA_OPERATIONS

GetScatterGatherListEx

MapTransferEx