次の方法で共有

WdfDmaTransactionAllocateResources 関数 (wdfdmatransaction.h)

  • [アーティクル]

[KMDF にのみ適用]

WdfDmaTransactionAllocateResources メソッドは、指定されたトランザクション オブジェクトで排他 (および繰り返し) 使用するために、単一パケットまたはシステム モードの DMA イネーブラーを予約します。 ドライバーは、予約済みリソースを保持しながら、トランザクションを複数回初期化して開始できます。

構文

NTSTATUS WdfDmaTransactionAllocateResources(
  [in] WDFDMATRANSACTION   DmaTransaction,
  [in] WDF_DMA_DIRECTION   DmaDirection,
  [in] ULONG               RequiredMapRegisters,
  [in] PFN_WDF_RESERVE_DMA EvtReserveDmaFunction,
  [in] PVOID               EvtReserveDmaContext
);

パラメーター

[in] DmaTransaction

DMA リソースを予約する必要がある DMA トランザクション オブジェクトへのハンドル。

[in] DmaDirection

リソースが予約されている DMA 転送方向を指定する、 WDF_DMA_DIRECTION型指定された値。 ドライバーで二重プロファイルが指定されていない場合、フレームワークはこの値を無視します。

[in] RequiredMapRegisters

ドライバーが予約するマップ レジスタの数。 0 の場合、フレームワークは、初期化されたトランザクションから必要な数のマップ レジスタを派生させます。

[in] EvtReserveDmaFunction

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

[in] EvtReserveDmaContext

ドライバーの EvtReserveDma イベント コールバック関数に提供されるコンテキストを含むバッファーへのポインター。

戻り値

WdfDmaTransactionAllocateResources は、操作が成功した場合にSTATUS_SUCCESSを返します。 それ以外の場合、このメソッドは次のいずれかの値を返します。

リターン コード 説明
STATUS_INVALID_PARAMETER
 DmaDirection パラメーターに無効な値が含まれています。
STATUS_INSUFFICIENT_RESOURCES
 マップ レジスタ要求の数が、イネーブラーに割り当てられた数を超えているか、以前 に WdfDmaTransactionSetImmediateExecution と呼ばれ、要求に必要なリソースを使用できません。
STATUS_INVALID_DEVICE_REQUEST
 DMA バージョン 3 以降が有効になっていないか、散布図 DMA イネーブラーに対してこのメソッドを呼び出したドライバー。

注釈

WdfDmaTransactionAllocateResources は、マップ レジスタの要求をシステム DMA エンジンに送信します。 要求が満たされると、フレームワークはドライバーの EvtReserveDma イベント コールバック関数を呼び出します。 リソースの予約の詳細については、「 DMA リソースの予約」を参照してください。

フレームワーク ベースのドライバーは、通常、I/O 要求ハンドラー内から WdfDmaTransactionAllocateResources を呼び出します。 ドライバーは、DMA enabler オブジェクトを作成した後、EvtDriverDeviceAdd コールバック関数から WdfDmaTransactionAllocateResources を呼び出すこともできます。

スキャッター/ギャザー DMA イネーブラーを使用して呼び出されると、WdfDmaTransactionAllocateResources によって検証ツールのバグチェックが発生します。

ドライバーは、WdfDmaTransactionAllocateResources を呼び出す前に、DmaTransaction で指定されたトランザクションを作成する必要があります。 WdfDmaTransactionAllocateResources を呼び出した後、ドライバーはトランザクションを初期化して開始します。 ドライバーは、同じトランザクション オブジェクトを複数回再初期化して再初期化できるため、マップ レジスタが HAL に解放されてから再割り当てされた場合にトランザクション間で発生する遅延を回避できます。

ドライバーは、次の状況で WdfDmaTransactionAllocateResources を呼び出す可能性があります。

  • ドライバーは、 EvtDevicePrepareHardware コールバック関数で DMA チャネルのセットを受け取ります。 EvtDevicePrepareHardware では、ドライバーは DMA トランザクションを初期化し、WdfDmaTransactionAllocateResources を呼び出して、このトランザクションで排他的に使用するためにイネーブラを予約します。 または、ドライバーは要求ハンドラーから WdfDmaTransactionAllocateResources を呼び出し、トランザクションを複数回開始できます。
  • ドライバーは、イネーブラーで一連のトランザクションを実行する必要があります。 ドライバーは、イネーブラーを予約し、同じトランザクション オブジェクトを使用して複数のトランザクションを初期化して開始してから、イネーブラーを解放します。
WdfDmaTransactionAllocateResources を呼び出す前に、ドライバーは、この予約を使用して開始するトランザクションに必要なマップ レジスタの数を決定する必要があります。 これを行うには、ドライバーは [ADDRESS_AND_SIZE_TO_SPAN_PAGES](.. のいずれかを呼び出すことができます。/wdm/nf-wdm-address_and_size_to_span_pages.md) マクロまたは WdfDmaTransactionGetTransferInfo。

WdfDmaTransactionAllocateResources を呼び出すとき、ドライバーはイネーブラーの作成時に要求したマップ レジスタよりも多くのマップ レジスタを要求しないでください。

WdfDmaTransactionAllocateResources を非ブロッキング方式で呼び出すには、ドライバーは最初に WdfDmaTransactionSetImmediateExecution を呼び出す必要があります。

WdfDmaTransactionAllocateResources には DMA バージョン 3 が必要です。 DMA バージョン 3 を選択するには、WDF_DMA_ENABLER_CONFIGの WdmDmaVersionOverride メンバーを 3 に設定します。

要件

要件 値
対象プラットフォーム ユニバーサル
最小 KMDF バージョン 1.11
Header wdfdmatransaction.h (Wdf.h を含む)
Library Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。
IRQL <=DISPATCH_LEVEL
DDI コンプライアンス規則 DriverCreate(kmdf)

こちらもご覧ください

EvtDevicePrepareHardware

WdfDmaEnablerCreate

WdfDmaTransactionCreate

WdfDmaTransactionExecute

WdfDmaTransactionFreeResources

WdfDmaTransactionSetImmediateExecution