IPortWavePciStream::GetMapping-Methode (portcls.h)

Artikel
08/07/2023

Die GetMapping -Methode ruft eine Zuordnung vom Porttreiber ab und ordnet der Zuordnung ein Tag 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 zugeordnete Zeigervariable, in die die Methode die physische Adresse der Zuordnung schreibt. Geben Sie einen gültigen Zeigerwert ohne NULL für diesen Parameter an.

[out] VirtualAddress

Ausgabezeiger für die virtuelle Adresse. Dieser Parameter verweist auf eine vom Aufrufer zugeordnete Zeigervariable, in die die Methode die virtuelle Adresse der Zuordnung schreibt. Geben Sie einen gültigen Zeigerwert ohne NULL 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 die Zuordnung schreibt. Geben Sie einen gültigen Zeigerwert ohne NULL für diesen Parameter an.

[out] Flags

Ausgabezeiger für das status-Flag. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene ULONG-Variable, in die die Methode ein status-Flag schreibt. Geben Sie einen gültigen Zeigerwert ohne NULL für diesen Parameter an. Ein Flagwert ungleich null gibt an, dass die in diesem Aufruf abgerufene Zuordnung die letzte Zuordnung in einem E/A-Paket ist. Dieses Flag kann verwendet werden, um zu signalisieren, dass die Hardware den Miniporttreiber unterbrechen soll, wenn sie mit dieser Zuordnung abgeschlossen ist. Als Reaktion auf den Interrupt kann der Miniporttreiber neue Zuordnungen für die Hardware abrufen. Der Miniportfahrer ist nicht verpflichtet, die Flagge auf diese Weise zu verwenden.

Rückgabewert

GetMapping gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich war. Andernfalls gibt die Methode einen geeigneten Fehlercode zurück. In der folgenden Tabelle sind einige der möglichen Rückgabecodes status 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 ist.

Hinweise

Über die GetMapping -Methode abgerufene Zuordnungen 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 des Streams aufruft .

Der Pufferspeicher für einen Stream, der über den Rendering-Pin eines Miniporttreibers wiedergegeben wird, wird an eine oder mehrere IRPs angefügt. Jedes IRP enthält einen Teil des Pufferspeichers für den Stream. Der Pufferspeicher jedes IRP ist im virtuellen Arbeitsspeicher zusammenhängend, aber die Speicherseiten, aus denen der Puffer besteht, werden im Allgemeinen nicht zusammenhängenden Speicherorten im physischen Speicher zugeordnet. Obwohl ein Treiber über programmierte E/A-Vorgänge über seine Zuordnung zum virtuellen Speicher auf den Puffer zugreifen kann, erfordert ein DMA-Controller stattdessen physische Zuordnungen.

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

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

Die Adresse des virtuellen Speichers im Kernelmodus der Zuordnung wird über den VirtualAddress-Parameter 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 Bus-master DMA-Controller des Audiogeräts verwendet die Adresse, die über den PhysicalAddress-Parameter 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::RevokeMappings zu identifizieren.
Der Miniporttreiber kann dieses Tag verwenden, um die Zuordnung in einem nachfolgenden Aufruf von IPortWavePciStream::ReleaseMapping zu identifizieren.

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

Ein typischer WavePci-Miniporttreiber verwaltet einen Datensatz jeder zuordnung, die er empfängt. Das Tag kann ein Zeiger auf einen Datensatz oder ein Index in ein Array von Datensätzen sein, z. B. abhängig von der Implementierung. Die einzige Voraussetzung für ein Tag ist, dass es sich um einen Wert handelt, der in den Typ PVOID umgewandelt werden kann.

Der Flags-Parameter gibt an, ob der Aufruf zum GetMapping Abrufen der endgültigen Zuordnung im Teil des Audiodatenpuffers, der an die aktuelle Zuordnungs-IRP angefügt ist, ausgeführt wurde. Wenn Flags angibt, dass eine Zuordnung die letzte Zuordnung in einem IRP ist, kann ein Miniporttreiber einen Hardwareunterbrechung so ausrüsten, dass er ausgelöst wird, wenn der Miniporttreiber die Wiedergabe dieser Zuordnung beendet. Wenn der Interrupt ausgelöst wird, informiert dieses Ereignis den Miniporttreiber darüber, dass er weitere Zuordnungen abrufen muss, um seiner DMA-Warteschlange hinzuzufügen. Der Flags-Parameter wird in der Regel von einem Miniporttreiber verwendet, der einen einzelnen Wiedergabestream vom KMixer-Systemtreiber verwaltet. KMixer verwendet mehrere Zuordnungs-IRPs (mindestens drei in der aktuellen KMixer-Implementierung), um einen einzelnen Wiedergabedatenstrom zu puffern. Wenn der Miniporttreiber also bei jedem Abschluss des DMA-Controllers mit der endgültigen Zuordnung in einem IRP einen Hardwareunterbrechung generiert, sollten Unterbrechungen häufig genug auftreten, um das Aushungen der DMA-Warteschlange zu verhindern.

Der Flags-Parameter wird in der Regel von Miniporttreibern ignoriert, die einen oder mehrere directSound-Streams mit Hardwarebeschleunigung verwalten (siehe DirectSound-Hardwarebeschleunigung in WDM-Audio). Im Fall eines DirectSound-Puffers kann der gesamte Puffer an eine einzelne IRP angefügt werden. Wenn der Puffer groß ist und der Miniporttreiber einen Hardwareunterbrechung nur dann 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 Streams verwaltet, kann die Planung eines Hardwareunterbrechungs jedes Mal, wenn der Flags-Parameter eine endgültige Zuordnungsbedingung für einen Stream signalisiert, so viele Interrupts generieren, dass die Leistung beeinträchtigt werden kann. Unter diesen Umständen sollte sich der Miniporttreiber nicht auf Hardwareunterbrechungen verlassen, um Zuordnungen zu erhalten. Stattdessen sollte geplant werden, dass Timer-DPCs in regelmäßigen Abständen zum Abrufen von Zuordnungen auftreten.

Ein Miniporttreiber ruft GetMapping höchstwahrscheinlich während eines Aufrufs der SetState-, Service- oder MappingAvailable-Methode des Miniportstreamobjekts auf (siehe IMiniportWavePciStream).

Um potenzielle Deadlocks zu vermeiden, muss der Adaptertreiber vermeiden, dass während des Aufrufs GetMappingvon eine Drehsperre gedrückt wird. Im Ac97-Beispiel-Audiotreiber im Microsoft Windows Driver Kit (WDK) finden Sie ein Codebeispiel, das eine Drehsperre verwendet, um Zugriffe auf freigegebene Datenstrukturen und Peripheriegeräte in einem Multiprozessorsystem zu serialisieren. Der Beispielcode ruft KeReleaseSpinLock vor dem Aufrufen GetMapping auf, und ruft KeAcquireSpinLock auf, nachdem aufgerufen wurde GetMapping. Zwischen den Aufrufen zum Freigeben und Abrufen der Spin-Sperre darf der Treiberthread nicht davon ausgehen, dass er exklusiven Zugriff auf die Daten oder Peripheriegeräte hat, die durch die Spin-Sperre geschützt werden. Das Driver Verifier-Tool überprüft während der Aufrufe von auf GetMappingaktive Spinsperren. Wenn es eine erkennt, generiert es eine 0xC4 -Fehlerprüfung (Deadlockerkennung).

Obwohl die Größe einer typischen Zuordnung eine Speicherseite oder weniger beträgt, 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 für DMA-Hardware mit Entwurfsfehlern verursachen, die die Blockgröße einschränken. Wenn beispielsweise ein DMA-Controller 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 einer Warteschlange in einem einzelnen Punkt/Sammeln-DMA-Vorgang in die Warteschlange stellen. In diesem Fall muss der Treiber den nicht in die Warteschlange stehenden Teil der Zuordnung nachverfolgen und DMA-Übertragungen der verbleibenden Blöcke zu einem späteren Zeitpunkt initiieren, wenn zusätzliche Kartenregister verfügbar werden.

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

Weitere Informationen zu Zuordnungen finden Sie unter WavePci Latency.