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

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

メソッドは 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 の呼び出しでマッピングを識別できます。

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

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

Flags パラメーターは、の呼び出しが、現在のマッピング IRP にGetMapping接続されているオーディオデータバッファーの部分で最終的なマッピングを取得したかどうかを示します。 フラグがマッピングが IRP の最後のマッピングであることを示す場合、ミニポートドライバーは、ミニポートドライバーがそのマッピングの再生を完了したときに発生するハードウェア割り込みをアームできます。割り込みが発生すると、このイベントは、DMA キューに追加するより多くのマッピングを取得する必要があることをミニポートドライバーに通知します。 Flags パラメーターは通常、KMixer システムドライバーから 1 つの再生ストリームを管理するミニポートドライバーによって使用されます。 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 サンプルオーディオドライバーに関するページを参照してください。サンプルコードでは、を呼び出す前に KeReleaseSpinLock を呼び出し、を呼び出 GetMapping した後に KeAcquireSpinLock を呼び出します GetMapping。スピンロックを解放して取得する呼び出しの間に、ドライバースレッドは、スピンロックによって保護されているデータまたは周辺機器への排他的アクセス権を持っていると見なす必要があります。ドライバー検証ツールは、の呼び出し中にGetMappingアクティブなスピンロックをチェックします。検出されると、0xC4 (デッドロック検出) バグチェックが生成されます。

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

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

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