WdfDmaTransactionInitialize 関数 (wdfdmatransaction.h)

[KMDF にのみ適用]

WdfDmaTransactionInitialize メソッドは、指定された DMA トランザクションを初期化します。

構文

NTSTATUS WdfDmaTransactionInitialize(
  [in] WDFDMATRANSACTION   DmaTransaction,
  [in] PFN_WDF_PROGRAM_DMA EvtProgramDmaFunction,
  [in] WDF_DMA_DIRECTION   DmaDirection,
  [in] PMDL                Mdl,
  [in] PVOID               VirtualAddress,
  [in] size_t              Length
);

パラメーター

[in] DmaTransaction

ドライバーが WdfDmaTransactionCreate の以前の呼び出しから取得した DMA トランザクション オブジェクトへのハンドル。

[in] EvtProgramDmaFunction

ドライバーの EvtProgramDma イベント コールバック関数へのポインター。

[in] DmaDirection

WDF_DMA_DIRECTION型指定された値。

[in] Mdl

DMA トランザクションに使用されるバッファーを記述するメモリ記述子リスト (MDL) へのポインター。 詳細については、「解説」を参照 してください。

[in] VirtualAddress

DMA トランザクションに使用されるバッファーの仮想アドレス。

[in] Length

転送するバイト数。

戻り値

操作が成功した場合、WdfDmaTransactionInitialize はSTATUS_SUCCESSを返します。 それ以外の場合、メソッドは次のいずれかの値を返す可能性があります。

このメソッドは、他の NTSTATUS 値を返す場合もあります。

ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。

注釈

WdfDmaTransactionInitialize メソッドは、トランザクションの散布/収集リストの割り当てなどの初期化操作を実行することで、DMA 操作を実行できるように準備します。 ドライバーが WdfDmaTransactionInitialize を呼び出した後、ドライバーは WdfDmaTransactionExecute を呼び出してトランザクションの実行を開始する必要があります。

フレームワーク ベースのドライバーは、通常、I/O キュー イベント コールバック関数内から WdfDmaTransactionInitialize を呼び出します。

フレームワーク要求オブジェクトに含まれる情報に基づく DMA トランザクションを作成する場合、ドライバーは WdfDmaTransactionInitializeUsingRequest を呼び出す必要があります。 要求オブジェクトに基づかない DMA トランザクションを作成する場合は、 WdfDmaTransactionInitialize または WdfDmaTransactionInitializeUsingOffset を使用します。

ドライバーは、このメソッドの Mdl パラメーターで MDL チェーンを指定できます。 MDL チェーンは、ドライバーが MDL 構造体の Next メンバーを使用して連結された MDL 構造体のシーケンスです。 1.11 より前のフレームワーク バージョンでは、分散/収集 DMA 転送のみが MDL チェーンを使用できます。 バージョン 1.11 以降では、ドライバーが DMA バージョン 3 を使用している場合、単一パケット転送でチェーンされた MDL を使用することもできます。

ドライバーが指定するバッファーが、 WdfDmaEnablerCreate または WdfDmaTransactionSetMaximumLength を呼び出したときにドライバーが指定した転送の最大長よりも大きい場合、フレームワークはトランザクションを複数の 転送に分割します。

DMA トランザクションの詳細については、「DMA トランザクション の作成と初期化」を参照してください。

例

次のコード例は、 PLX9x5x サンプル ドライバーのものです。 最初に、この例では 、WDF_OBJECT_ATTRIBUTES 構造体を初期化し、DMA トランザクション オブジェクトを作成します。 次に、受信した I/O 要求の入力バッファーを表す MDL を取得し、バッファーの仮想アドレスと長さを取得します。 最後に、この例では WdfDmaTransactionInitialize を呼び出してトランザクションを初期化します。

WDF_OBJECT_ATTRIBUTES  attributes;
PMDL  mdl;
PVOID  virtualAddress;
ULONG  length;
NTSTATUS  status;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &attributes,
                                        TRANSACTION_CONTEXT
                                        );

status = WdfDmaTransactionCreate(
                                 devExt->DmaEnabler,
                                 &attributes,
                                 &dmaTransaction
                                 );
if(!NT_SUCCESS(status)) {
    goto CleanUp;
}

status = WdfRequestRetrieveInputWdmMdl(
                                       Request,
                                       &mdl
                                       );
if (!NT_SUCCESS(status)) {
    goto CleanUp;
}

virtualAddress = MmGetMdlVirtualAddress(mdl);
length = MmGetMdlByteCount(mdl);

status = WdfDmaTransactionInitialize(
                                     dmaTransaction,
                                     PLxEvtProgramWriteDma,
                                     WdfDmaDirectionWriteToDevice,
                                     mdl,
                                     virtualAddress,
                                     length
                                     );
if(!NT_SUCCESS(status)) {
    goto CleanUp;
}

要件

こちらもご覧ください

EvtProgramDma

MmGetMdlByteCount

MmGetMdlVirtualAddress

WDF_DMA_DIRECTION

WdfDmaEnablerSetMaximumScatterGatherElements

WdfDmaTransactionCreate

WdfDmaTransactionExecute

WdfDmaTransactionInitializeUsingRequest