IPortWavePciStream::GetMapping メソッド (portcls.h)

[アーティクル]
02/07/2025

GetMapping メソッドは、ポートドライバーからマッピングを取得し、タグをマッピングに関連付けます。

構文

NTSTATUS GetMapping(
  [in]  PVOID             Tag,
  [out] PPHYSICAL_ADDRESS PhysicalAddress,
  [out] PVOID             *VirtualAddress,
  [out] PULONG            ByteCount,
  [out] PULONG            Flags
);

パラメーター

[in] Tag

マッピングに関連付けるタグ値を指定します。ポートドライバーは、後続の IMiniportWavePciStream::RevokeMappings 呼び出しでこのタグを使用して、取り消すマッピングの一覧内のマッピングを識別できます。ミニポートドライバーは、タグを使用して、マッピングを解放する IPortWavePciStream::ReleaseMapping 呼び出し内のマッピングを識別します。

[out] PhysicalAddress

物理アドレスの出力ポインター。このパラメーターは、メソッドがマッピングの物理アドレスを書き込む呼び出し元によって割り当てられたポインター変数を指します。このパラメーターに有効な NULL 以外のポインター値を指定します。

[out] VirtualAddress

仮想アドレスの出力ポインター。このパラメーターは、メソッドがマッピングの仮想アドレスを書き込む呼び出し元によって割り当てられたポインター変数を指します。このパラメーターに有効な NULL 以外のポインター値を指定します。

[out] ByteCount

バイト数の出力ポインター。このパラメーターは、メソッドがマッピングのバイト数を書き込む呼び出し元によって割り当てられた ULONG 変数を指します。このパラメーターに有効な NULL 以外のポインター値を指定します。

[out] Flags

状態フラグの出力ポインター。このパラメーターは、メソッドがステータスフラグを書き込む呼び出し元によって割り当てられた ULONG 変数を指します。このパラメーターに有効な NULL 以外のポインター値を指定します。 0 以外のフラグ値は、この呼び出しで取得されたマッピングが I/O パケットの最後のマッピングであることを示します。このフラグを使用すると、このマッピングが完了したときに、ハードウェアがミニポートドライバーを中断する必要があることを通知できます。割り込みに応答して、ミニポートドライバーは、ハードウェアに配信する新しいマッピングを取得できます。ミニポートドライバーは、この方法でフラグを使用する必要はありません。

戻り値

GetMapping は、呼び出しが成功した場合にSTATUS_SUCCESSを返します。それ以外の場合、メソッドは適切なエラーコードを返します。次の表に、考えられる戻り状態コードの一部を示します。

リターンコード	形容
STATUS_NOT_FOUND	マッピングはすぐには使用できませんが、マッピングが使用可能になると、ポートドライバーは IMiniportWavePciStream::MappingAvailable 呼び出します。

備考

GetMapping メソッドを使用して取得したマッピングは、ポートドライバーによって取り消されない限り、IPortWavePciStream::ReleaseMapping を呼び出すことによって解放する必要があります。ポートドライバーは、ストリームの IMiniportWavePciStream::RevokeMappings メソッドを呼び出すことによって、マッピングを取り消すことができます。

ミニポートドライバーのレンダリングピンを介して再生されるストリームのバッファーストレージは、1 つ以上の IRP に接続されます。各 IRP には、ストリームのバッファーストレージの一部が含まれています。各 IRP のバッファーストレージは仮想メモリ内で連続していますが、バッファーを構成するメモリページは、一般的に物理メモリ内の連続した場所にマップされません。ドライバーは、プログラミングされた I/O を使用して、仮想メモリへのマッピングを介してバッファーにアクセスできますが、DMA コントローラーでは代わりに物理マッピングが必要です。

WavePci ポートドライバーは、物理マッピングのシーケンスとしてミニポートドライバーにバッファーを公開する GetMapping メソッドを使用します。一般的なマッピングは 1 つのメモリページ以下ですが、2 つ以上のページが物理メモリ内の隣接する場所を占有する場合、マッピングはページサイズを超える可能性があります。

GetMapping の最初の呼び出しでは、バッファーの先頭にマッピングが出力されます。 GetMapping を連続して呼び出すたびに、バッファー内の次の順次マッピングが表示されます。バッファーの末尾に達すると、次の GetMapping 呼び出しによってバッファーの先頭にマッピングが出力され、マッピングシーケンスが繰り返されます。

マッピングのカーネルモードの仮想メモリアドレスは、VirtualAddress パラメーターを介して出力されます。ミニポートドライバーは、直接プログラム制御下のマッピングにアクセスするには、このアドレスを使用します。マッピングを含むページはロックされており、ドライバーがマッピングにアクセスしてもページエラーは発生しません。オーディオデバイスのバスマスター DMA コントローラーは、PhysicalAddress パラメーターを介して出力されるアドレスを使用してマッピングにアクセスします。

Tag パラメーターは、呼び出し元がマッピングを一意に識別するために選択する PVOID 値です。

ポートドライバーは、このタグを使用して、IMiniportWavePciStream::RevokeMappings 後続の呼び出しでマッピングを識別できます。
ミニポートドライバーは、このタグを使用して、IPortWavePciStream::ReleaseMapping への後続の呼び出しマッピングを識別できます。

タグは PVOID 型として定義されていますが、ポートドライバーはこの値をポインターとして使用しようとせず、有効なポインターである必要はありません。

一般的な WavePci ミニポートドライバーは、受信した各マッピングのレコードを保持します。タグは、例えば、実装に応じて、レコードへのポインターまたはレコードの配列へのインデックスである可能性があります。タグの唯一の要件は、PVOID 型にキャストできる値であるということです。

Flags パラメーターは、GetMapping への呼び出しが、現在のマッピング IRP に接続されているオーディオデータバッファーの部分で最終的なマッピングを取得したかどうかを示します。 フラグ が、マッピングが IRP の最後のマッピングであることを示す場合、ミニポートドライバーは、ミニポートドライバーがそのマッピングの再生を完了したときに発生するハードウェア割り込みを起動できます。割り込みが発生すると、このイベントは、DMA キューに追加するより多くのマッピングを取得する必要があることをミニポートドライバーに通知します。 フラグ パラメーターは、通常、KMixer システムドライバーからの単一の再生ストリームを管理するミニポートドライバーによって使用されます。 KMixer では、複数のマッピング IRP (現在の KMixer 実装では 3 つ以上) を使用して、1 つの再生ストリームをバッファー処理します。したがって、ミニポートドライバーは、DMA コントローラーが IRP の最終的なマッピングで終了するたびにハードウェア割り込みを生成する場合、割り込みは、DMA キューが不足しないようにするために十分に頻繁に発生する必要があります。

Flags パラメーターは、通常、1 つ以上の DirectSound ハードウェアアクセラレータストリームを管理するミニポートドライバーによって無視されます (WDM オーディオの DirectSound ハードウェアアクセラレーション参照)。 DirectSound バッファーの場合、バッファー全体を 1 つの IRP にアタッチできます。バッファーが大きく、ミニポートドライバーは、バッファーの末尾に達した場合にのみハードウェア割り込みをスケジュールする場合、割り込みは、DMA キューが不足する可能性がある離れて発生します。さらに、ドライバーが多数のストリームを管理している場合、Flags パラメーターがストリームの最終的なマッピング条件を通知するたびにハードウェア割り込みをスケジュールすると、パフォーマンスが低下する可能性のある非常に多くの割り込みが生成される可能性があります。このような状況では、ミニポートドライバーは、マッピングを取得するハードウェア割り込みに依存しないでください。代わりに、マッピングを取得するために、タイマー DPC が一定の間隔で実行されるようにスケジュールする必要があります。

ミニポートドライバーは、ミニポートストリームオブジェクトの SetState、Service、または MappingAvailable メソッドの呼び出し中にGetMapping を呼び出す可能性が最も高くなります (IMiniportWavePciStream 参照)。

潜在的なデッドロックを回避するには、アダプタードライバーは、GetMappingへの呼び出し中にスピンロックを保持しないようにする必要があります。スピンロックを使用してマルチプロセッサシステムの共有データ構造と周辺機器へのアクセスをシリアル化するコード例については、Microsoft Windows Driver Kit (WDK) の ac97 サンプルオーディオドライバーを参照してください。サンプルコードは、GetMapping を呼び出す前に KeReleaseSpinLock 呼び出し、GetMapping呼び出した後に KeAcquireSpinLock 呼び出します。スピンロックを解放して取得する呼び出しの間に、ドライバースレッドは、スピンロックによって保護されているデータまたは周辺機器への排他的アクセス権を持っていると想定してはなりません。ドライバー検証ツールツールは、GetMappingへの呼び出し中にアクティブなスピンロックをチェックします。検出された場合は、0xC4 (デッドロック検出) バグチェックが生成されます。

一般的なマッピングのサイズは 1 メモリページ以下ですが、オーディオバッファーの一部が物理メモリ内の 2 つ以上の連続したページを占有する場合、1 つのマッピングがページサイズを超える可能性があります。マッピングを大きくすると、ブロックサイズを制限する設計上の欠陥がある DMA ハードウェアの問題が発生する可能性があります。たとえば、DMA コントローラーが単一ページの最大ブロックサイズを処理でき、ページよりも大きいマッピングを出力 GetMapping 場合、ミニポートドライバーは、DMA ハードウェアが処理できる小さなブロックにマッピングを分割する必要があります。結果として得られるブロック数が DMA ハードウェアで使用可能なマップレジスタの数を超えた場合、ドライバーは、1 つの散布図/収集 DMA 操作ですべてのブロックをキューに入れることはできません。これが発生した場合、ドライバーは、マッピングのキューに入っていない部分を追跡し、後で追加のマップレジスタが使用可能になったときに残りのブロックの DMA 転送を開始する必要があります。

Windows 98/Me、Windows 2000、Windows XP、および Windows Server 2003 では、GetMapping メソッドは 16 ページを超えるマッピングを出力しません。この制限は、今後の Windows リリースで変更される可能性があります。

マッピングの詳細については、「WavePci Latency」を参照してください。

必要条件

要件	価値
ターゲットプラットフォームの	万国
ヘッダー	portcls.h (Portcls.h を含む)
IRQL	<=DISPATCH_LEVEL

次の方法で共有

IPortWavePciStream::GetMapping メソッド (portcls.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース