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

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

CreateCommonBufferFromMdl ルーチンは、デバイスアクセスの互換性をテストし、変換の種類に応じてメモリを連続する論理範囲にマッピングすることで、MDL から共通バッファーの作成を試みます。他のすべての一般的なバッファー割り当て関数と同様に、この関数は前方進行の保証を提供しません。

構文

PCREATE_COMMON_BUFFER_FROM_MDL PcreateCommonBufferFromMdl;

NTSTATUS PcreateCommonBufferFromMdl(
  [in]  PDMA_ADAPTER DmaAdapter,
  [in]  PMDL Mdl,
  [in]  PDMA_COMMON_BUFFER_EXTENDED_CONFIGURATION ExtendedConfigs,
  [in]  ULONG ExtendedConfigsCount,
  [out] PPHYSICAL_ADDRESS LogicalAddress
)
{...}

パラメーター

[in] DmaAdapter

操作を実行している DMA アダプターへのポインターを提供します。

[in] Mdl

共通バッファーにマップされる MDL を提供します。

MDL が共通バッファーをバックできるようにするには、次の条件を満たす必要があります。

MDL には、共通バッファーの有効期間中は常に常駐し、システム・アドレス・スペースにマップされるページが必要です。これは、次の方法で実現できます。
MDL は、 MmBuildMdlForNonPagedPool を使用して、非ページプール内のバッファーから作成されます。
MDL は MmProbeAndLockPages を介してロックされ、 MmGetSystemAddressForMdlSafe を介してシステム空間にマップされています。
MDL の物理ページは MmAllocatePagesForMdlEx を介して割り当てられ、 MmGetSystemAddressForMdlSafe を介してシステム空間にマップされています。
MDL は、ページアライン領域を表し、PAGE_SIZEの倍数である必要があります。
- SubSection 拡張構成が使用されている場合、使用される MDL の部分はページアラインされ、PAGE_SIZEの倍数である必要があります。
MDL は、チェーンされた MDL にすることはできません。
- SubSection 拡張構成を使用している場合は、チェーンされた MDL を指定できますが、使用される MDL の部分はチェーン内の単一の MDL に含まれている必要があります。
DMA 再マッピングが使用されていない場合、MDL は物理的に連続したメモリを表し、デバイスからアクセスできる必要があります。

[in] ExtendedConfigs

MDL でサポートされる共通バッファーの作成をさらに構成するために、 DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION 構造体の省略可能な配列を提供します。

配列に同じ DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION_TYPE の複数の構成が指定されている場合、作成は失敗します。

[in] ExtendedConfigsCount

ExtendedConfigs 配列内の拡張構成の数 を提供します 。

[out] LogicalAddress

成功すると、結果の共通バッファーの論理アドレスが提供されます。

戻り値

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

リターンコード	説明
STATUS_INVALID_PARAMETER	呼び出し元が互換性のない MDL または拡張構成を提供しました。
STATUS_NOT_SUPPORTED	呼び出し元は、現在のシステムでサポートされていない拡張構成を提供しました。
STATUS_INSUFFICIENT_RESOURCES	システムには、ブックの保持とマッピングのメタデータを作成するのに十分なメモリがありません。

注釈

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

CreateCommonBufferFromMdl によって作成された共通バッファーは、FreeCommonBuffer 経由で削除されます。呼び出し元は、アダプターの共通バッファーの簿記構造から共通バッファーが正しく削除されるように、システム仮想アドレスを仮想アドレスとして指定する必要があります。ドライバーは、MDL とそのバッキングページのロック解除と解放を引き続き担当します。

HAL がバッキングメモリの保守を担当する共通バッファーを作成するには、 AllocateCommonBufferWithBounds を使用します。

要件

要件	値
サポートされている最小のサーバー	Windows Server 2022
対象プラットフォーム	デスクトップ
Header	wdm.h
IRQL	PASSIVE_LEVEL