Implementieren von PnP Rebalance für PortCls-Audiotreiber

Der PnP-Ausgleich wird in bestimmten PCI-Szenarien verwendet, in denen Speicherressourcen neu zugeordnet werden müssen.

Der Ausgleich kann in zwei Standardszenarien ausgelöst werden:

1. PCI-Hotplug: Ein Benutzer schließt ein Gerät an und der PCI-Bus verfügt nicht über genügend Ressourcen, um den Treiber für das neue Gerät zu laden. Einige Beispiele für Geräte, die in diese Kategorie fallen, sind Thunderbolt, USB-C und NVME Storage. In diesem Szenario müssen die Speicherressourcen neu angeordnet und konsolidiert (ausgeglichen) werden, um die zusätzlich hinzugefügten Geräte zu unterstützen.
2. In der Größe veränderbare PCI-BARs: Nachdem ein Treiber für ein Gerät erfolgreich in den Speicher geladen wurde, fordert es zusätzliche Ressourcen an. Einige Beispiele für Geräte sind High-End-Grafikkarten und Speichergeräte. Weitere Informationen zur Unterstützung von Videotreibern finden Sie unter In der Größe anpassbarer BAR-Support. In diesem Thema wird beschrieben, was unternommen werden muss, um den PnP-Ausgleich für PortCls-Audiotreiber zu implementieren.

Der PnP-Ausgleich ist in Windows 10, Version 1511 und höheren Versionen von Windows verfügbar.

Ausgleichsanforderungen

Portcls-Audiotreiber können den Ausgleich unterstützen, wenn die folgenden Bedingungen erfüllt sind:

• Der Miniport muss die IAdapterPnpManagement-Schnittstelle mit Portcls registrieren.
• Der Miniport muss PcRebalanceRemoveSubdevices von IAdapterPnpManagement::GetSupportedRebalanceType zurückgeben.
• Topologie und WaveRT sind die beiden unterstützten Porttypen.

Um den Ausgleich bei aktiven Audiostreams zu unterstützen, müssen Portcls-Audiotreiber eine dieser beiden zusätzlichen Anforderungen erfüllen.

• Der Treiber unterstützt die IMiniportWaveRTInputStream::GetReadPacket- und IMiniportWaveRTOutputStream-Paketschnittstellen für den Audiostream. Dies ist die empfohlene Option.

ODER

• Wenn der Treiber das Abrufen/Schreiben von IMiniportWaveRT für die Streams nicht unterstützt, darf der Treiber KSPROPERTY_RTAUDIO_POSITIONREGISTER und KSPROPERTY_RTAUDIO_CLOCKREGISTER nicht unterstützen. Das Audiomodul verwendet in diesem Szenario IMiniportWaveRTStream::GetPosition.

Audiostream-Verhalten bei Ausgleich

Wenn der Ausgleich bei aktiven Audiostreams ausgelöst wird und der Treiber den Ausgleich für aktive Audiostreams unterstützt, werden alle aktiven Audiostreams gestoppt und nicht automatisch neu gestartet.

IPortClsPnp-COM-Schnittstelle

IPortClsPnp ist die PnP-Verwaltungsschnittstelle, die der Portklassentreiber (PortCls) für den Adapter bereitstellt.

IPortClsPnp erbt von IUnknown und unterstützt auch die folgenden Methoden:

• IPortClsPnp::RegisterAdapterPnpManagement
• IPortClsPnp::UnregisterAdapterPnpManagement

Audio-Miniporttreiber können eine PNP-Benachrichtigungsschnittstelle mithilfe von Portcls-Exporten oder über die IPortClsPnp-COM-Schnittstelle registrieren, die IPortClsPnp für das WaveRT-Portobjekt bereitgestellt hat. Verwenden Sie IPortClsPnp::RegisterAdapterPnpManagement und IPortClsPnp::UnregisterAdapterPnpManagement zum Registrieren und Aufheben der Registrierung.

Erforderliche PortCls-Export-DDIs

IAdapterPnpManagement ist eine Schnittstelle, die Adapter implementieren und registrieren sollten, wenn sie PnP-Verwaltungsmeldungen empfangen möchten. Registrieren Sie diese Schnittstelle mit PortCls mithilfe von PcRegisterAdapterPnpManagement. Heben Sie die Registrierung dieser Schnittstelle mit PortCls mithilfe von PcUnregisterAdapterPnpManagement auf.

Erforderliche Treiber-DDIs

Die folgenden IAdapterPnpManagement-DDIs müssen implementiert werden, um den Ausgleich zu unterstützen.

• IAdapterPnpManagement::GetSupportedRebalanceType wird von Portcls während der Verarbeitung des QueryStop aufgerufen. Der Miniport gibt den unterstützten Ausgleichstyp zurück, wie in der PC_REBALANCE_TYPE-Enumeration definiert.

  Hinweis Portcls ruft die globale Gerätesperre ab, bevor dieser Aufruf ausgeführt wird. Daher muss der Miniport diesen Aufruf so schnell wie möglich ausführen.

• IAdapterPnpManagement::PnpQueryStop wird von Portcls direkt vor dem erfolgreichen Ausführen des QueryStop-IRP aufgerufen. Dies ist nur eine Benachrichtigung, und der Aufruf gibt keinen Wert zurück.

  Hinweis Portcls ruft die globale Gerätesperre ab, bevor dieser Aufruf ausgeführt wird. Daher muss der Miniport diesen Aufruf so schnell wie möglich ausführen. Während ein Stopp aussteht, blockiert (hält) Portcls alle neuen Erstellungsanforderungen.

• IAdapterPnpManagement::P npCancelStop wird von Portcls aufgerufen, während das CanceStop-IRP verarbeitet wird. Dies ist nur eine Benachrichtigung. Es ist möglich, dass der Miniport PnpCancelStop empfängt, auch ohne zuvor eine PnpQueryStop-Benachrichtigung zu erhalten. Der Miniport sollte so geschrieben sein, dass er diesem Verhalten Rechnung trägt. Dies ist beispielsweise der Fall, wenn die QueryStop-Logik das IRP als fehlgeschlagen angibt, bevor Portcls die Möglichkeit hat, diese Benachrichtigung an den Miniport weiterzuleiten. In diesem Szenario ruft der PnP-Manager weiterhin einen PnP Cancel Stop auf.

  Hinweis Portcls ruft die globale Gerätesperre ab, bevor dieser Aufruf ausgeführt wird. Daher muss der Miniport diesen Aufruf so schnell wie möglich ausführen. Während ein Stopp aussteht, blockiert (hält) Portcls alle neuen Erstellungsanforderungen. PortCls startet alle ausstehenden Erstellungsanforderungen neu, wenn ein ausstehender Stopp abgebrochen wird.

• IAdapterPnpManagement::PnpStop wird von Portcls aufgerufen, nachdem alle Ioctl-Vorgänge gestoppt und aktive Streams vom Status [run|pause|acquire] in den Status [stop] verschoben wurden. Dieser Aufruf wird beim Halten der globalen Gerätesperre nicht ausgeführt. Somit hat der Miniport die Möglichkeit, auf seine asynchronen Vorgänge (Arbeitselemente, DPC, asynchrone Threads) zu warten und die Registrierung seiner Audio-Untergeräte aufzuheben. Bevor der Miniport von diesem Aufruf zurückkehrt, muss er sicherstellen, dass alle Hardwareressourcen freigegeben wurden.

  Hinweis Der Miniport darf nicht warten, bis die aktuellen Miniport-/Streamobjekte gelöscht werden, da es unklar ist, wann vorhandene Audioclients die aktuellen Handles freigeben. Der PnpStop-Thread kann nicht für immer blockiert werden, ohne dass das System abstürzt, d. h. es handelt sich um einen PnP/Power-Thread.

IMiniportPnpNotify

IMiniportPnpNotify ist eine optionale Schnittstelle, mit der Miniportobjekte (Audiounterfunktionen) PnP-Zustandsänderungsbenachrichtigungen empfangen können.

Miniports haben die Möglichkeit, für jedes von ihnen registrierte Audio-Untergerät eine PnP-Stopp-Benachrichtigung zu erhalten. Um diese Benachrichtigung zu erhalten, muss das Untergerät IMiniportPnpNotify unterstützen. Nur die IMiniportPnpNotify::PnpStop-Benachrichtigung wird auf dieser Schnittstelle definiert.

Die IMiniportPnpNotify-Schnittstelle ist sowohl für WaveRT als auch für die Topologie verfügbar.

Hinweis Da Portcls die globale Gerätesperre abruft, bevor dieser Aufruf ausgeführt wird, muss der Miniport diesen Aufruf so schnell wie möglich ausführen. Der Miniport darf während der Verarbeitung dieses Aufrufs nicht auf andere Aktivitäten warten, um einen Deadlock zu verhindern, wenn andere Threads/Arbeitselemente auf die globale Gerätesperre warten. Bei Bedarf kann der Miniport im IAdapterPnpManagement::PnpStop-Aufruf warten.