次の方法で共有


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

メソッドは 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 が一定の間隔で発生するようにスケジュールする必要があります。

ミニポート ドライバーは、ミニポート ストリーム オブジェクトの SetStateService、または 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 待機時間」を参照してください。

要件

要件
対象プラットフォーム ユニバーサル
Header portcls.h (Portcls.h を含む)
IRQL <=DISPATCH_LEVEL

こちらもご覧ください

IMiniportWavePciStream::GetAllocatorFraming

IMiniportWavePciStream::MappingAvailable

IMiniportWavePciStream::RevokeMappings

IPortWavePciStream

IPortWavePciStream::ReleaseMapping

KeAcquireSpinLock

KeReleaseSpinLock