WdfDmaTransactionAllocateResources 関数 (wdfdmatransaction.h)

2023-08-08

[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 イネーブラーオブジェクトを作成した後、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
ヘッダー	wdfdmatransaction.h (Wdf.h を含む)
図書館	Wdf01000.sys (フレームワークライブラリのバージョン管理を参照)。
IRQL	<=DISPATCH_LEVEL
DDI コンプライアンス規則をする	DriverCreate(kmdf)