WdfDmaTransactionAllocateResources 関数 (wdfdmatransaction.h)

[アーティクル]
08/08/2023

[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)