IPortWavePciStream::GetMapping-Methode (portcls.h)

Artikel
02/07/2025

Die GetMapping-Methode ruft eine Zuordnung vom Porttreiber ab und ordnet ein Tag der Zuordnung zu.

Syntax

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

Parameter

[in] Tag

Gibt einen Tagwert an, der der Zuordnung zugeordnet werden soll. Der Porttreiber kann dieses Tag in einem nachfolgenden IMiniportWavePciStream::RevokeMappings Aufruf verwenden, um die Zuordnung in der Liste der zu widerrufenden Zuordnungen zu identifizieren. Der Miniporttreiber verwendet das Tag, um die Zuordnung im IPortWavePciStream::ReleaseMapping Aufruf zu identifizieren, der die Zuordnung freigibt.

[out] PhysicalAddress

Ausgabezeiger für die physische Adresse. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene Zeigervariable, in die die Methode die physische Adresse der Zuordnung schreibt. Geben Sie einen gültigen, nicht NULL-Zeigerwert für diesen Parameter an.

[out] VirtualAddress

Ausgabezeiger für die virtuelle Adresse. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene Zeigervariable, in die die Methode die virtuelle Adresse der Zuordnung schreibt. Geben Sie einen gültigen, nicht NULL-Zeigerwert für diesen Parameter an.

[out] ByteCount

Ausgabezeiger für die Byteanzahl. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene ULONG-Variable, in die die Methode die Anzahl der Bytes in der Zuordnung schreibt. Geben Sie einen gültigen, nicht NULL-Zeigerwert für diesen Parameter an.

[out] Flags

Ausgabezeiger für das Statuskennzeichnung. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene ULONG-Variable, in die die Methode ein Statuskennzeichnung schreibt. Geben Sie einen gültigen, nicht NULL-Zeigerwert für diesen Parameter an. Ein Nichtzero-Flagwert gibt an, dass die zuordnung, die in diesem Aufruf erworben wurde, die letzte Zuordnung in einem E/A-Paket ist. Diese Kennzeichnung kann verwendet werden, um zu signalisieren, dass die Hardware den Miniporttreiber unterbrechen soll, wenn sie mit dieser Zuordnung erfolgt. Als Reaktion auf den Interrupt kann der Miniporttreiber neue Zuordnungen abrufen, um die Hardware zu liefern. Der Miniport-Fahrer ist nicht verpflichtet, die Flagge auf diese Weise zu verwenden.

Rückgabewert

GetMapping gibt STATUS_SUCCESS zurück, wenn der Anruf erfolgreich war. Andernfalls gibt die Methode einen geeigneten Fehlercode zurück. In der folgenden Tabelle sind einige der möglichen Rückgabestatuscodes aufgeführt.

Rückgabecode	Beschreibung
STATUS_NOT_FOUND	Eine Zuordnung ist nicht sofort verfügbar, aber der Porttreiber ruft IMiniportWavePciStream::MappingAvailable auf, wenn eine Zuordnung verfügbar wird.

Bemerkungen

Zuordnungen, die über die GetMapping-Methode abgerufen werden, sollten durch Aufrufen von IPortWavePciStream::ReleaseMapping freigegeben werden, es sei denn, sie werden vom Porttreiber widerrufen. Der Porttreiber kann Zuordnungen widerrufen, indem er die IMiniportWavePciStream::RevokeMappings-Methode aufruft.

Der Pufferspeicher für einen Datenstrom, der über den Rendering-Pin eines Miniporttreibers wiedergegeben wird, wird an einen oder mehrere IRPs angefügt. Jedes IRP enthält einen Teil des Pufferspeichers für den Datenstrom. Der Pufferspeicher jedes IRP ist im virtuellen Speicher zusammenhängend, aber die Speicherseiten, aus denen der Puffer besteht, ordnen sich nicht im allgemeinen den zusammenhängenden Speicherorten im physischen Speicher zu. Obwohl ein Treiber programmierte E/A verwenden kann, um über die Zuordnung in den virtuellen Speicher auf den Puffer zuzugreifen, benötigt ein DMA-Controller stattdessen physische Zuordnungen.

Der WavePci-Porttreiber verwendet die GetMapping-Methode, um den Puffer als Sequenz physischer Zuordnungen für den Miniporttreiber verfügbar zu machen. Eine typische Zuordnung ist eine Speicherseite oder weniger größe, obwohl eine Zuordnung die Seitengröße überschreiten kann, wenn zwei oder mehr Seiten benachbarte Speicherorte im physischen Speicher belegen.

Der anfängliche Aufruf von GetMapping gibt die Zuordnung am Anfang des Puffers aus. Jeder aufeinander folgende Aufruf von GetMapping stellt die nächste sequenzielle Zuordnung im Puffer dar. Nachdem das Ende des Puffers erreicht wurde, gibt die nächste GetMapping die Zuordnung am Anfang des Puffers aus, und die Zuordnungssequenz wird wiederholt.

Die Virtual-Memory-Adresse des Kernelmodus der Zuordnung wird über den parameter VirtualAddress ausgegeben. Der Miniporttreiber verwendet diese Adresse, um unter direkter Programmsteuerung auf die Zuordnung zuzugreifen. Die Seite, die die Zuordnung enthält, ist gesperrt, und es kann kein Seitenfehler auftreten, wenn der Treiber auf die Zuordnung zugreift. Der DMA-Controller des Audiogeräts verwendet die Adresse, die über den parameter PhysicalAddress ausgegeben wird, um auf die Zuordnung zuzugreifen.

Der Tag Parameter ist ein PVOID-Wert, den der Aufrufer auswäht, um die Zuordnung eindeutig zu identifizieren:

Der Porttreiber kann dieses Tag verwenden, um die Zuordnung in einem nachfolgenden Aufruf von IMiniportWavePciStream::RevokeMappingszu identifizieren.
Der Miniporttreiber kann dieses Tag verwenden, um die Zuordnung in einem nachfolgenden Aufruf von IPortWavePciStream::ReleaseMappingzu identifizieren.

Obwohl Tag- als PVOID-Typ definiert ist, versucht der Porttreiber niemals, diesen Wert als Zeiger zu verwenden und erfordert nicht, dass es sich um einen gültigen Zeiger handelt.

Ein typischer WavePci Miniport-Treiber verwaltet einen Datensatz jeder von ihr empfangenen Zuordnung. Das Tag kann ein Zeiger auf einen Datensatz oder einen Index in einem Array von Datensätzen sein, z. B. abhängig von der Implementierung. Die einzige Anforderung für ein Tag besteht darin, dass es sich um einen Wert handelt, der in den Typ PVOID umwandeln kann.

Der parameter Flags gibt an, ob der Aufruf der GetMapping die endgültige Zuordnung im Teil des Audiodatenpuffers abgerufen hat, der an das aktuelle Zuordnungs-IRP angefügt ist. Wenn Flags angibt, dass eine Zuordnung die letzte Zuordnung in einem IRP ist, kann ein Miniporttreiber eine Hardwareunterbrechung armieren, um zu auslösen, wenn der Miniporttreiber die Wiedergabe dieser Zuordnung beendet hat. Wenn der Interrupt ausgelöst wird, informiert dieses Ereignis den Miniporttreiber darüber, dass er weitere Zuordnungen erwerben muss, um der DMA-Warteschlange hinzuzufügen. Der parameter Flags wird in der Regel von einem Miniporttreiber verwendet, der einen einzelnen Wiedergabedatenstrom vom KMixer-Systemtreiberverwaltet. KMixer verwendet mehrere Zuordnungs-IRPs (mindestens drei in der aktuellen KMixer-Implementierung), um einen einzelnen Wiedergabedatenstrom zu puffern. Wenn der Miniporttreiber bei jedem Abschluss des DMA-Controllers eine Hardwareunterbrechung mit der endgültigen Zuordnung in einem IRP generiert, sollten Unterbrechungen häufig genug auftreten, damit die DMA-Warteschlange nicht verhungern kann.

Der parameter Flags wird in der Regel von Miniporttreibern ignoriert, die einen oder mehrere directSound-hardwarebeschleunigte Datenströme verwalten (siehe DirectSound-Hardwarebeschleunigung in WDM Audio). Bei einem DirectSound-Puffer kann der gesamte Puffer an einen einzelnen IRP angefügt werden. Wenn der Puffer groß ist und der Miniporttreiber einen Hardwareunterbrechung nur plant, wenn er das Ende des Puffers erreicht, treten Unterbrechungen so weit auseinander, dass die DMA-Warteschlange möglicherweise verhungern kann. Wenn der Treiber eine große Anzahl von Datenströmen verwaltet, generiert die Planung einer Hardwareunterbrechung jedes Mal, wenn die Flags Parameter signalisiert, dass eine endgültige Zuordnungsbedingung für einen Datenstrom so viele Unterbrechungen erzeugt, dass die Leistung beeinträchtigt werden kann. Unter diesen Umständen sollte der Miniporttreiber nicht auf Hardwareunterbrechungen angewiesen sein, um Zuordnungen zu erwerben. Stattdessen sollten Zeitgeber-DPCs in regelmäßigen Intervallen geplant werden, um Zuordnungen zu erwerben.

Ein Miniporttreiber wird wahrscheinlich GetMapping während eines Aufrufs des SetState, Serviceoder MappingAvailable -Methode (siehe IMiniportWavePciStream) aufgerufen.

Um potenzielle Deadlocks zu vermeiden, muss der Adaptertreiber während des Aufrufs von GetMappingvermeiden, eine Drehungssperre zu halten. Im Ac97-Beispielaudiotreiber im Microsoft Windows Driver Kit (WDK) finden Sie ein Codebeispiel, das eine Drehsperre zum Serialisieren des Zugriffs auf freigegebene Datenstrukturen und Peripheriegeräte in einem Multiprozessorsystem verwendet. Der Beispielcode ruft KeReleaseSpinLock- auf, bevor GetMapping aufgerufen und KeAcquireSpinLock nach dem Aufrufen von GetMappingaufgerufen wird. Zwischen den Aufrufen zum Freigeben und Abrufen der Drehsperre darf der Treiberthread nicht davon ausgehen, dass er exklusiven Zugriff auf die Daten oder Peripheriegeräte hat, die durch die Spin-Sperre geschützt sind. Das Driver Verifier Tool sucht bei Aufrufen von GetMappingnach aktiven Drehsperren; wenn eine erkannt wird, generiert sie eine 0xC4 (Deadlock-Erkennung) Fehlerüberprüfung.

Obwohl die Größe einer typischen Zuordnung eine Speicherseite oder weniger ist, kann eine einzelne Zuordnung die Seitengröße überschreiten, wenn ein Teil eines Audiopuffers zwei oder mehr zusammenhängende Seiten im physischen Speicher belegt. Größere Zuordnungen können Probleme mit DMA-Hardware mit Entwurfsfehlern verursachen, die die Blockgröße einschränken. Wenn ein DMA-Controller beispielsweise eine maximale Blockgröße einer einzelnen Seite verarbeiten kann und GetMapping eine Zuordnung ausgibt, die größer als eine Seite ist, muss der Miniporttreiber die Zuordnung in kleinere Blöcke aufteilen, die die DMA-Hardware verarbeiten kann. Wenn die resultierende Anzahl von Blöcken die Anzahl der verfügbaren Kartenregister in der DMA-Hardware überschreitet, kann der Treiber nicht alle Blöcke in einem einzelnen Punkt/Gather-DMA-Vorgang in die Warteschlange stellen. In diesem Fall muss der Treiber den nicht abgefragten Teil der Zuordnung nachverfolgen und DMA-Übertragungen der verbleibenden Blöcke zu einem späteren Zeitpunkt initiieren, wenn zusätzliche Kartenregister verfügbar sind.

In Windows 98/Me, Windows 2000, Windows XP und Windows Server 2003 gibt die GetMapping-Methode niemals eine Zuordnung aus, die mehr als 16 Seiten umfasst. Dieser Grenzwert kann sich in zukünftigen Windows-Versionen ändern.

Weitere Informationen zu Zuordnungen finden Sie unter WavePci Latency.