PALLOCATE_COMMON_BUFFER_EX コールバック関数 (wdm.h)
AllocateCommonBufferEx ルーチンは、共通バッファーにメモリを割り当て、このメモリをマップして、プロセッサと DMA 操作を実行するデバイスの両方からアクセスできるようにします。
構文
PALLOCATE_COMMON_BUFFER_EX PallocateCommonBufferEx;
PVOID PallocateCommonBufferEx(
[in] PDMA_ADAPTER DmaAdapter,
[in, optional] PPHYSICAL_ADDRESS MaximumAddress,
[in] ULONG Length,
[out] PPHYSICAL_ADDRESS LogicalAddress,
[in] BOOLEAN CacheEnabled,
[in] NODE_REQUIREMENT PreferredNode
)
{...}
パラメーター
[in] DmaAdapter
DMA_ADAPTER構造体へのポインター。 この構造体は、ドライバーのバス マスター DMA デバイスまたはシステム DMA チャネルを表すアダプター オブジェクトです。 呼び出し元は、 IoGetDmaAdapter ルーチンの以前の呼び出しからこのポインターを取得しました。
[in, optional] MaximumAddress
共通バッファーの最大論理アドレスを含む変数へのポインター。 このパラメーターは、このアドレスより下のメモリからバッファーを割り当てる必要があることを示します。 このパラメーターは省略可能であり、最大アドレスがないことを示すために NULL として指定できます。
[in] Length
DMA 操作に割り当てられる共通バッファーのサイズ (バイト単位)。
[out] LogicalAddress
このルーチンが共通バッファーにアクセスするためにデバイスが使用できる論理アドレスを書き込む変数へのポインター。 DMA デバイスでは、 MmGetPhysicalAddress などのルーチンによって返される物理アドレスではなく、この論理アドレスを使用する必要があります。
[in] CacheEnabled
ルーチンで、割り当てる共通バッファー内のキャッシュされたメモリを有効または無効にする必要があるかどうか。 TRUE の場合、キャッシュは有効になります。 FALSE の場合は無効になります。 ハードウェア プラットフォームで DMA 操作にキャッシュの一貫性が強制されない場合は、FALSE を渡します。 ARM または ARM 64 ベースのプロセッサ ターゲット コンピューターでのこのパラメーターの詳細については、「解説」を参照してください。
[in] PreferredNode
メモリの割り当て元となる優先 NUMA ノード。 N がマルチプロセッサ システム内の NUMA ノードの数である場合、 PreferredNode は 0 ~ N - 1 の範囲の数値です。 1 プロセッサ システムまたは NUMA 以外のマルチプロセッサ システムの場合は、 PreferredNode を 0 に設定します。
戻り値
AllocateCommonBufferEx は、共通バッファーに割り当てられたメモリの仮想アドレスを返します。 バッファーを割り当てることができない場合は、NULL が返されます。
注釈
AllocateCommonBufferEx は、名前で直接呼び出すことができるシステム ルーチンではありません。 このルーチンは、 DMA_OPERATIONS 構造体で返されるアドレスからのポインターによってのみ呼び出すことができます。 ドライバーは、DeviceDescription パラメーターの Version メンバーをDEVICE_DESCRIPTION_VERSION3に設定して IoGetDmaAdapter を呼び出すことによって、このルーチンのアドレスを取得します。 IoGetDmaAdapter が NULL を返す場合、ルーチンはプラットフォームで使用できません。
AllocateCommonBufferEx は、 AllocateCommonBuffer ルーチンの拡張バージョンです。 次の一覧は、拡張バージョンでのみ使用できる機能をまとめたものです。
呼び出し元は、割り当てる共通バッファーの最大論理アドレスを指定できます。
呼び出し元は、共通バッファーを割り当てる優先 NUMA ノードを指定できます。
ARM または ARM 64 ベースのプロセッサを搭載したコンピューターでは、システム ACPI のキャッシュ設定の優先順位は、ドライバーによって渡される CacheEnabled パラメーター値よりも高くなります。 ACPI _CCA メソッドが、デバイスがキャッシュに一貫性がないことを示す場合、ドライバーが CacheEnabled を TRUE に設定してキャッシュされたメモリを割り当てた場合でも、オペレーティング システムはキャッシュを無効にします。
ARM または ARM 64 ベースのプロセッサを搭載したコンピューターでは、オペレーティング システムはキャッシュされていない共通バッファーをデバイス メモリとして割り当てます。 バッファーの詳細については、 ARMv7 アーキテクチャ リファレンス マニュアルのセクション A3.5.1 および A3.5.6 を参照してください。
プロセッサは、デバイス メモリへの不適切なアクセスを許可しません。 ドライバーは、自然に配置された操作を使用して、常に共通バッファーからデータにアクセスする必要があります。 ほとんどのカーネル ルーチンでは、デバイス メモリを入力パラメーターとして受け入れられません。 たとえば、ネットワーク ドライバーはデバイス メモリを NdisMIndicateReceiveNetBufferLists に渡すことができません。 ドライバーが DMA 共通バッファーからカーネル ルーチンにデータを渡す必要がある場合は、 CacheEnabled を TRUE に設定してバッファーを割り当てるか、キャッシュされていない共通バッファーから一時的なプール割り当てにデータをコピーします。
共通バッファーを使用する DMA 操作の詳細については、次のトピックを参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 8以降で使用できます。 |
| 対象プラットフォーム | デスクトップ |
| Header | wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む) |
| IRQL | PASSIVE_LEVEL |