PMAP_TRANSFER_EX コールバック関数 (wdm.h)
MapTransferEx ルーチンは、分散/収集リスト内の物理アドレスを、DMA 転送を行うために必要な論理アドレスにマップするマップ レジスタを設定します。
構文
PMAP_TRANSFER_EX PmapTransferEx;
NTSTATUS PmapTransferEx(
[in] PDMA_ADAPTER DmaAdapter,
[in] PMDL Mdl,
[in] PVOID MapRegisterBase,
[in] ULONGLONG Offset,
[in] ULONG DeviceOffset,
[in, out] PULONG Length,
[in] BOOLEAN WriteToDevice,
[out, optional] PSCATTER_GATHER_LIST ScatterGatherBuffer,
[in] ULONG ScatterGatherBufferLength,
[in, optional] PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
[in, optional] PVOID CompletionContext
)
{...}
パラメーター
[in] DmaAdapter
DMA_ADAPTER構造体へのポインター。 この構造体は、ドライバーのバス マスター DMA デバイスまたはシステム DMA チャネルを表すアダプター オブジェクトです。 呼び出し元は、 IoGetDmaAdapter ルーチンの以前の呼び出しからこのポインターを取得しました。
[in] Mdl
仮想メモリ内のロックダウン バッファーのコレクションの物理ページ レイアウトを記述する MDL チェーンへのポインター。 DMA 転送の散布/収集リストでは、 Offset パラメーターと Length パラメーターで指定されたこのメモリの領域が使用されます。 MDL チェーンの詳細については、「 MDL の使用」を参照してください。
[in] MapRegisterBase
アダプター オブジェクトに割り当てられるマップ レジスタへのハンドル。 呼び出し元は、以前に AllocateAdapterChannelEx ルーチンからこのハンドルを取得しました。
[in] Offset
MDL チェーンによって記述されるメモリの先頭からのバイト オフセット。 このオフセットは、DMA 転送に使用される I/O データ バッファーの開始を指定します。 呼び出し元に散布/収集リストが指定されている場合、このオフセットはリスト内の最初のバッファー フラグメントの開始アドレスを決定します。 MDL チェーン内の MDL で合計 N バイトのメモリが記述されている場合、 Offset の有効な値は 0 から N から 1 の範囲です。 詳細については、「解説」を参照してください。
[in] DeviceOffset
ターゲット デバイスのベース アドレスからのターゲット デバイスのデータ レジスタまたは FIFO のバイト オフセット。 このパラメーターは、システム DMA コントローラーからアクセスできる複数の FIFO を持つデバイスに適用されます。 このパラメーターは、システム DMA 転送にのみ使用されます。 バス マスター転送の場合は、このパラメーターを 0 に設定します。
[in, out] Length
DMA 転送に使用される I/O データ バッファーの長さ (バイト単位) を含む変数へのポインター。 エントリの場合、この変数には、呼び出し元のドライバーによって要求された長さが含まれます。 を返す前に、ルーチンはマップされたバッファーの実際の長さをこの変数に書き込みます。 MapTransferEx からの戻り値の *Length の値は、マップされたバイト数を示します。 呼び出し元が要求した全長をマップするのにマップ・レジスタの数と散布/収集バッファー・サイズで十分な場合、*Length の入出力値は同じです。 MDL チェーン内の MDL で N バイトのメモリの合計が記述されている場合、*Length の有効な値は 0 ~ N–Offset の範囲です。
[in] WriteToDevice
DMA 転送の方向。 メモリからデバイスにデータを転送する書き込み操作では、このパラメーターを TRUE に 設定します。 デバイスからメモリにデータを転送する読み取り操作の場合は、このパラメーターを FALSE に設定します。
[out, optional] ScatterGatherBuffer
DMA 転送のスキャッター/ギャザー リストをルーチンが書き込む呼び出し元によって割り当てられたバッファーへのポインター。 このリストは 、SCATTER_GATHER_LIST 構造体から始まり、その直後に SCATTER_GATHER_ELEMENT 配列が続きます。 バス マスター DMA デバイスを使用するドライバーの場合、 ScatterGatherBuffer は必須のパラメーターです。 システム DMA コントローラーを使用するドライバーの場合、 ScatterGatherBuffer パラメーターは省略可能であり、 NULL にすることができます。 詳細については、「解説」を参照してください。
[in] ScatterGatherBufferLength
ScatterGatherBuffer パラメーターが指すバッファーのサイズ (バイト単位)。 割り当てられたバッファー サイズは、散布図/収集リストと、オペレーティング システムがこのバッファーに格納する内部データを格納するのに十分な大きさである必要があります。 必要なバッファー サイズを確認するには、 GetDmaTransferInfo ルーチンまたは CalculateScatterGatherList ルーチンを呼び出します。 ScatterGatherBuffer が NULL の場合は、ScatterGatherBufferLength を 0 に設定します。
[in, optional] DmaCompletionRoutine
DMA 転送が完了したときに呼び出される呼び出し元から提供される DmaCompletionRoutine ルーチンへのポインター。 このルーチンは、ターゲット デバイスが DMA 完了割り込みを生成するシステム DMA コントローラーを使用する場合に呼び出されます。 DmaCompletionRoutine ルーチンは、DMA 転送が完了した後、DISPATCH_LEVELで呼び出されます。 システム DMA アダプターの場合、このパラメーターは省略可能であり、 NULL にすることができます。 バス マスター アダプターの場合は、このパラメーターを NULL に設定 します。
[in, optional] CompletionContext
DmaCompletionRoutine ルーチンのドライバーによって決定されたコンテキスト。 このコンテキストは、 CompletionContext パラメーターとして DmaCompletionRoutine ルーチンに提供されます。 DmaCompletionRoutine パラメーターが NULL の場合は、CompletionContext を NULL に設定します。
戻り値
MapTransferEx は 、呼び出しが成功した場合にSTATUS_SUCCESSを返します。 考えられるエラーの戻り値には、次の状態コードが含まれます。
| リターン コード | 説明 |
|---|---|
|
呼び出し元によって渡されたパラメーター値が無効であるため、ルーチンは失敗しました。 |
|
ScatterGatherBuffer の呼び出し元が指定したバッファーが小さすぎて、散布/収集リストを格納できません。 |
|
ルーチンは、DMA 転送に必要なリソースを割り当てませんでした。 |
|
この転送は取り消されました。 |
注釈
MapTransferEx は、名前で直接呼び出すことができるシステム ルーチンではありません。このルーチンは、DMA_OPERATIONS構造体で返されるアドレスからのポインターによってのみ呼び出すことができます 。 ドライバーは、DeviceDescription パラメーターの Version メンバーを DEVICE_DESCRIPTION_VERSION3 に設定して IoGetDmaAdapter を呼び出すことによって、このルーチンのアドレスを取得します。 IoGetDmaAdapter が NULL を返す場合、ルーチンはプラットフォームで使用できません。
システム DMA コントローラーを使用する転送の場合、呼び出し元はオプションとして、転送の終了時に呼び出される DmaCompletionRoutine コールバック ルーチンを指定できます。 オペレーティング システムは、システム DMA コントローラーからの DMA 完了割り込みに応答して、このコールバックをスケジュールします。
MapTransferEx によって設定できるマップ レジスタの数は、IoGetDmaAdapter から取得したドライバーの最大数を超えることはできません。
Mdl、Offset、Length の各パラメーターは、要求された DMA 転送の I/O データ バッファーを記述します。 割り当てられたマップ レジスタの数は、このバッファー内のすべてのメモリをマップするのに十分ではない場合があります。また、 ScatterGatherBuffer が指すスキャッター /ギャザー バッファーがバッファー全体を記述するのに十分な大きさではない可能性があります。 MapTransferEx は出力値を *Length に書き込み、要求された DMA 転送のバッファー メモリがルーチンによってマップされた量をドライバーに伝えます。 ルーチンは、 ScatterGatherBuffer が指すバッファーに散布/収集リストを書き込みます。 この一覧では、ルーチンによって正常にマップされたバッファー フラグメントについて説明します。
MapTransferEx の呼び出しが成功した場合、MapTransferEx は *Length 出力値を返す前に書き込みます。 呼び出し元が DmaCompletionRoutine を指定した場合、更新された *Length 出力値は、 DmaCompletionRoutine が実行される前に常に書き込まれます。 詳細については、「 MapTransferEx への複数の呼び出し」を参照してください。
Offset パラメーターは、I/O データ バッファー内のメモリを記述する MDL チェーン内の開始オフセットを指定します。 たとえば、MDL チェーンに MDL₁ と MDL₂ の 2 つの MDL が含まれており、MDL₁ が N₁ バイトのメモリを記述し、MDL₂ が N₂ バイトを記述しているとします。 Offset = N (N₁ < N < N₁ + N₂) の場合、バッファーには MDL₁ で記述されているメモリは含まれていないので、MDL₂ で記述されたメモリ内の N - N₁ バイトのオフセットから始まります。
転送でシステム DMA コントローラーが使用されている場合、呼び出し元は ScatterGatherBuffer = NULL を設定できます。この場合、 MapTransferEx は 内部的に割り当てられた既定のバッファーを使用して、散布/収集リストを保持します。 既定のバッファーは、少なくとも 1 つの要素の散布/収集リストを格納するのに十分な大きさであることが保証されます。 多くの要素の分散/収集転送に既定のバッファーを使用する場合、 MapTransferEx への多くの呼び出しが転送を完了する必要がある場合があります。 DMA コントローラー ハードウェアがスキャッター/ギャザー転送をサポートしている場合、既定のバッファーを使用するとパフォーマンスが低下する可能性があります。
ScatterGatherBuffer が NULL 以外で、ScatterGatherBufferSize で、少なくとも 1 つの要素の散布/収集リストを含むサイズが小さすぎる場合、MapTransferEx は失敗し、STATUS_INVALID_PARAMETERを返します。
MapTransferEx は、 MapTransfer ルーチンの拡張バージョンです。 拡張バージョンには、次の利点があります。
- MapTransferEx は MDL チェーン内のすべてのバッファー フラグメントを 1 回の呼び出しで処理できますが、 MapTransfer は 呼び出しごとに物理的に連続したバッファー フラグメントを 1 つだけ処理できます。
- MapTransferEx は 1 回の呼び出しで散布/収集リスト全体を生成できますが、 MapTransfer は 呼び出しごとに 1 つの散布図/収集リスト要素のみを生成できます。
- MapTransferEx は、1 回の呼び出しで散布/収集リスト内のすべてのバッファー フラグメントをマップできますが、 MapTransfer は 呼び出しごとに物理的に連続したバッファー フラグメントを 1 つだけマップできます。
- MapTransferEx では、散布図/収集リスト全体の開始オフセットのみが必要ですが、 MapTransfer では 、物理的に連続する各バッファー フラグメントに対して開始仮想アドレスが必要です。
- MapTransferEx 呼び出しでは、1 つ以上の MDL を介して拡張されるバッファーをマップできますが、MapTransfer 呼び出しでは、MDL によって記述されるメモリ内の物理的に連続したバッファー フラグメントを 1 つだけマップできます。
- システム DMA 転送の場合、 MapTransferEx を使用すると、呼び出し元は DmaCompletionRoutine コールバック ルーチンを指定して転送が完了した後に通知を受け取ることができますが、 MapTransfer は DMA 転送が完了したときに呼び出し元に通知する方法を提供しません。
詳細については、「 MapTransferEx ルーチンの使用」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 8 以降で使用できます。 |
| 対象プラットフォーム | デスクトップ |
| Header | wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む) |
| IRQL | <= DISPATCH_LEVEL |