IPortWavePciStream：：GetMapping 方法 (portcls.h)

發行項
03/01/2024

方法 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 指標值。非零旗標值表示在此呼叫中取得的對應是I/O 封包中的最後一個對應。此旗標可用來表示硬體在完成此對應時應該中斷迷你埠驅動程式。為了回應中斷，迷你埠驅動程式可以取得新的對應來傳遞至硬體。迷你埠驅動程式不一定要以這種方式使用旗標。

傳回值

GetMapping 如果呼叫成功，會傳回STATUS_SUCCESS。否則，方法會傳回適當的錯誤碼。下表顯示一些可能的傳回狀態代碼。

傳回碼	Description
STATUS_NOT_FOUND	對應無法立即使用，但埠驅動程式會在對應可用時呼叫 IMiniportWavePciStream：：MappingAvailable 。

備註

除非埠驅動程式撤銷這些對應，否則應該呼叫 IPortWavePciStream：：ReleaseMapping 來釋放透過方法取得GetMapping的對應。埠驅動程式可以藉由呼叫數據流的 IMiniportWavePciStream：：RevokeMappings 方法來撤銷對應。

透過迷你埠驅動程序轉譯針腳播放之數據流的緩衝區記憶體會連結至一或多個 IRP。每個 IRP 都包含數據流緩衝區記憶體的一部分。每個 IRP 的緩衝區記憶體在虛擬記憶體中都是連續的，但組成緩衝區的記憶體分頁通常不會對應到物理記憶體中的連續位置。雖然驅動程式可以使用程式化 I/O，透過其對應存取緩衝區到虛擬記憶體，但 DMA 控制器需要實體對應。

WavePci 埠驅動程式會 GetMapping 使用方法，將緩衝區公開至迷你埠驅動程式做為一連串的實體對應。一般對應是一個記憶體頁面或較小的大小，雖然如果兩個以上的頁面發生佔用物理記憶體中相鄰位置，對應可能會超過頁面大小。

在緩衝區開頭輸出對應的初始呼叫 GetMapping 。每個後續呼叫都會 GetMapping 在緩衝區中呈現下一個循序對應。到達緩衝區結尾之後，下一個 GetMapping 呼叫會輸出緩衝區開頭的對應，並重複對應順序。

對應的內核模式虛擬記憶體位址是透過 VirtualAddress 參數輸出。迷你埠驅動程式會使用此位址來存取直接程式控制下的對應。包含對應的頁面已鎖定，而且驅動程式存取對應時不會發生任何頁面錯誤。音訊裝置的總線主機 DMA 控制器會使用 透過 PhysicalAddress 參數輸出的位址來存取對應。

Tag 參數是呼叫端選擇唯一識別對應的 PVOID 值：

埠驅動程式可能會使用此標記來識別後續呼叫 IMiniportWavePciStream：：RevokeMappings 的對應。
迷你埠驅動程式可以使用這個標記來識別 後續呼叫 IPortWavePciStream：：ReleaseMapping 中的對應。

雖然 Tag 定義為 PVOID 類型，但埠驅動程式永遠不會嘗試使用此值作為指標，而且不需要它是有效的指標。

典型的 WavePci 迷你埠驅動程式會維護其收到的每個對應記錄。標記可能是記錄的指標或記錄陣列中的索引，例如，視實作而定。標記的唯一需求是它可以轉換成 PVOID 類型的值。

Flags 參數指出呼叫GetMapping是否擷取附加至目前對應 IRP 之音訊數據緩衝區部分的最終對應。當 Flags 指出對應是 IRP 中的最後一個對應時，迷你埠驅動程式可以引發硬體中斷，以在迷你埠驅動程式完成播放該對應時引發。當中斷引發時，此事件會通知迷你埠驅動程式需要取得更多對應以新增至其 DMA 佇列。 Flags 參數通常是由小型埠驅動程式使用，該驅動程式會從 KMixer 系統驅動程式管理單一播放串流。 KMixer 使用數個對應 IRP (目前 KMixer 實作中至少三個) 緩衝處理單一播放數據流。因此，如果迷你埠驅動程式每次 DMA 控制器在 IRP 中完成最終對應時產生硬體中斷，則中斷的頻率應該足以讓 DMA 佇列無法耗盡。

旗標參數通常是由管理一或多個 DirectSound 硬體加速數據流的迷你埠驅動程式忽略， (請參閱 WDM 音訊) 中的 DirectSound 硬體加速。在 DirectSound 緩衝區的情況下，整個緩衝區可以附加至單一 IRP。如果緩衝區很大，而迷你埠驅動程式只會在到達緩衝區結尾時排程硬體中斷，則中斷會到目前為止發生，而 DMA 佇列可能會耗盡。此外，如果驅動程式正在管理大量的數據流，則每當 Flags 參數發出數據流最終對應條件訊號時，排程硬體中斷可能會產生許多中斷，讓效能降低。在這些情況下，迷你埠驅動程式不應該依賴硬體中斷來取得對應。相反地，它應該排程定時器 DPC 定期進行，以取得對應。

迷你埠驅動程式最有可能在呼叫迷你埠數據流物件的 SetState、Service 或 MappingAvailable 方法期間呼叫GetMapping， (請參閱 IMiniportWavePciStream) 。

若要避免潛在的死結，配接器驅動程式必須在呼叫 GetMapping期間避免保留微調鎖定。如需使用微調鎖定來串行化多處理器系統中共用數據結構和周邊存取的程式代碼範例，請參閱 Microsoft Windows 驅動程式套件 (WDK) 中的 ac97 範例音訊驅動程式。範例程式代碼會在呼叫 GetMapping 之前呼叫KeReleaseSpinLock，並在呼叫之後呼叫GetMappingKeAcquireSpinLock。在釋放和取得微調鎖定的呼叫之間，驅動程式線程不得假設其具有線程微調鎖定所防護之數據或周邊的獨佔存取權。驅動程式驗證器工具會在呼叫 GetMapping期間檢查作用中的微調鎖定;如果偵測到鎖定鎖定，則會在錯誤檢查) 產生0xC4 (死结侦测。

雖然一般對應的大小是一個記憶體頁面或更少，但如果音頻緩衝區的一部分佔用物理記憶體中的兩個或多個連續頁面，單一對應可能會超過頁面大小。較大的對應可能會為 DMA 硬體建立問題，並具有限制區塊大小的設計缺陷。例如，如果 DMA 控制器可以處理單一頁面的最大區塊大小，並 GetMapping 輸出大於頁面的對應，迷你埠驅動程式必須將對應分割成 DMA 硬體可以處理的較小區塊。如果產生的區塊數目超過 DMA 硬體中可用的地圖緩存器數目，驅動程式就無法將單一散佈/收集 DMA 作業中的所有區塊排入佇列。發生這種情況時，驅動程式必須追蹤對應的未佇列部分，並在稍後有其他地圖緩存器可用時起始剩餘區塊的 DMA 傳輸。

在 Windows 98/Me、Windows 2000、Windows XP 和 Windows Server 2003 中 GetMapping ，此方法永遠不會輸出跨越超過 16 頁的對應。未來 Windows 版本可能會變更此限制。

如需對應的詳細資訊，請參閱 WavePci 延遲。