PGET_DMA_TRANSFER_INFO コールバック関数 (wdm.h)

[アーティクル]
02/29/2024

GetDmaTransferInfo ルーチンは、散布図/収集 DMA 転送の割り当て要件を計算します。

構文

PGET_DMA_TRANSFER_INFO PgetDmaTransferInfo;

NTSTATUS PgetDmaTransferInfo(
  [in]      PDMA_ADAPTER DmaAdapter,
  [in]      PMDL Mdl,
  [in]      ULONGLONG Offset,
  [in]      ULONG Length,
  [in]      BOOLEAN WriteOnly,
  [in, out] PDMA_TRANSFER_INFO TransferInfo
)
{...}

パラメーター

[in] DmaAdapter

DMA_ADAPTER構造体へのポインター。この構造体は、ドライバーのバスマスター DMA デバイスまたはシステム DMA チャネルを表すアダプターオブジェクトです。呼び出し元は、 IoGetDmaAdapter ルーチンの以前の呼び出しからこのポインターを取得しました。

[in] Mdl

転送されるメモリのページを記述する MDL チェーンへのポインター。詳細については、「解説」を参照してください。

[in] Offset

スキャッター/ギャザー DMA 転送の開始オフセット。このパラメーターは、MDL チェーン内の最初の MDL 内のバッファーの先頭からのバイトオフセットです。 MDL チェーン内の MDL でバッファー領域の合計 N バイトを指定した場合、 Offset の有効な値は 0 から N から 1 の範囲になります。

[in] Length

DMA 転送の長さ (バイト単位)。 MDL チェーンがバッファー領域の N バイトの合計を指定する場合、有効な値 の長さは 1 ~ N オフセットの範囲です。

[in] WriteOnly

転送が書き込み専用操作 (つまり、メモリからデバイスへの転送) であるかどうかを示します。 WriteOnly が TRUE の場合、転送に関して返される情報が読み取りトランザクションに対して有効でない可能性があります。このパラメーターは、キャッシュの一貫性を強制するために、バッファー境界で追加のキャッシュ制御操作が必要であることを示している可能性があります。

[in, out] TransferInfo

呼び出し元によって割り当てられた DMA_TRANSFER_INFO 構造体へのポインター。呼び出し元は、GetDmaTransferInfo を呼び出す前に、構造体の Version メンバーを DMA_TRANSFER_INFO_VERSION1 に設定する必要があります。

戻り値

GetDmaTransferInfo は、呼び出しが成功した場合にSTATUS_SUCCESSを返します。考えられるエラーの戻り値には、次の状態コードが含まれます。

リターンコード	説明
STATUS_NOT_SUPPORTED	ルーチンは、指定されたバージョンの DMA_TRANSFER_INFO_XXX 構造体をサポートしていません。

注釈

GetDmaTransferInfo は、名前で直接呼び出すことができるシステムルーチンではありません。このルーチンは、DMA_OPERATIONS構造体で返されるアドレスからのポインターによってのみ呼び出すことができます。ドライバーは、DeviceDescription パラメーターの Version メンバーを DEVICE_DESCRIPTION_VERSION3 に設定して IoGetDmaAdapter を呼び出すことによって、このルーチンのアドレスを取得します。 IoGetDmaAdapter が NULL を返す場合、ルーチンはプラットフォームで使用できません。

GetDmaTransferInfo を使用して、BuildScatterGatherListEx ルーチンおよび MapTransferEx ルーチンに割り当てる散布/収集バッファーのサイズを計算します。

GetDmaTransferInfo は CalculateScatterGatherList ルーチンを置き換え、 BuildScatterGatherListEx で使用する方が便利です。

Mdl、Offset、Length の各パラメーターは、分散/収集 DMA 転送のバッファーとして使用する物理メモリ領域のコレクションを指定します。各物理メモリ領域は、通常、ページまたはページの一部です。 GetDmaTransferInfo は、この転送の割り当て要件を決定します。次の要件があります。

散布図/収集リスト内の要素の数。各要素は、物理的に連続したメモリブロックを記述する SCATTER_GATHER_ELEMENT 構造体です。
指定した散布図/収集リストを保持するために割り当てるメモリの量。 (このメモリ割り当てには、I/O バッファーを記述するが、I/O バッファー自体については説明しないスキャッター/ギャザーリストに必要な領域が含まれます)。
散布図/収集リスト内の物理アドレスを論理アドレスに変換するために必要なマップレジスタの数。

DMA_TRANSFER_INFO_XXX 構造体のバージョン 1 で提供される DMA 転送情報については、「DMA_TRANSFER_INFO_V1」を参照してください。

MDL は、ロックダウンされた連続した仮想メモリブロックの基になる物理メモリページを記述します。通常、これらの物理メモリページは連続しません。 MDL チェーンは、I/O データのバッファーに使用できるメモリを記述する MDL の順序付きコレクションです。通常、チェーン内の MDLs によって記述される仮想メモリ領域は連続していない状態です。 MDL と MDL チェーンの詳細については、「MDL の使用」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows 8以降で使用できます。
対象プラットフォーム	デスクトップ
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
IRQL	<= DISPATCH_LEVEL