Verwaltung der Lebensdauer von ACX-WDF-Treibern

Artikel
05/28/2024

Dieses Thema enthält eine Zusammenfassung der Verwaltung der Lebensdauer von ACX-WDF-Treibern und der ordnungsgemäßen Speicherbereinigung. Eine allgemeine Übersicht über ACX finden Sie in der Übersicht über ACX-Audioklassenerweiterungen.

Hinweis

Die ACX-Header und -Bibliotheken sind nicht im WDK 10.0.22621.2428 (veröffentlicht am 24. Oktober 2023) enthalten, sind aber in früheren Versionen sowie in der neuesten Insider-Vorschauversion (Builds der 25000er-Serie) des WDK verfügbar. Weitere Informationen zu Vorschauversionen des WDK finden Sie unter Installieren von Vorschauversionen des Windows Driver Kit (WDK).

ACX-WDF-Initialisierung und -Start

Es muss eine ordnungsgemäße ACX-Initialisierung erfolgen, um eine ordnungsgemäße Bereinigung von ACX-, WDF- und Speicherressourcen zu ermöglichen. Weitere Details zu den wichtigsten Phasen der hier zusammengefassten Geräteenumeration finden Sie in der ACX-Geräteenumeration.

WDM-Treibereintrag
WDF-Gerät hinzufügen
WDF – Vorbereiten der Hardware
WDF-Gerät-D0-Eintrag
ACX-Verbindungserstellungsprozess (ACX-Pin- und Buchsenobjekte sind mit der Verbindung verknüpft)
ACX-Streamerstellungsprozess

ACX-WDF-Objektbereinigung

In diesem Thema wird die Bereinigung von ACX-WDF-Objekten in dieser Reihenfolge beschrieben.

ACX-Stream-Abschlussprozess
ACX-Verbindungsentfernungsprozess
WDF-Gerätefreigabehardware
WDF-Treiber entladen

Es gibt mehrere gültige Ansätze zum Erstellen und Bereinigen von WDF- und ACX-Objekten. In diesem Thema werden einige Schlüsselelemente der Verwaltung der Lebensdauer von ACX/WDF-Objekten behandelt.

PnP-Energieereignisse und Objektvernichtung

PnP-Energieereignisse können die Objekterstellung und -vernichtung verursachen. Weitere Informationen zu PnP-Energieereignissen finden Sie unter ACX-Energieverwaltung und WDF PnP- und Energieverwaltungs-Rückrufsequenzen.

Lebensdauerverwaltung des WDF-Objektverweises

WDF verwendet Referenzzähler, um die Lebensdauer von Objekten zu verfolgen. In einer Rückruffunktion zur Bereinigung kann es sinnvoll sein, Objektverweise zu dereferenzieren. Das Framework ruft diese Bereinigungsrückruffunktion auf, sodass der Treiber WdfObjectDereference aufrufen kann, wenn er zuvor WdfObjectReference für das Objekt aufgerufen hat, das gelöscht wird. Weitere Informationen finden Sie unter WdfObjectReference und WdfObjectDereference.

Bewährte Methoden für die Entwicklung von Surface Team-Treibern

Eine Beschreibung häufiger Fehler, die im Treibercode bei der Speicher- und Objektlebensdauerverwaltung gemacht werden, finden Sie in den entsprechenden Abschnitten in Bewährte Methoden für die Entwicklung von Surface Team-Treibern.

ACX-Stream-Abschlussprozess

Wenn der Client den Stream schließt, muss der Treiber die mit dem Stream verknüpften Ressourcen schließen und bereinigen. Weitere Informationen finden Sie unter ACX-Streaming – Stream-Abschlussprozess. Es ist wichtig, dass der Treiber keine Ressourcen bereinigt, die den Stream unterstützen, und dass beim Bereinigungsprozess die Auswirkungen auf den Client berücksichtigt werden.

ACX-Verbindungsentfernungsprozess

ACX kann bei Bedarf eine dynamische Verbindung erstellen. Dazu weist der Treiber eine WDFDEVICE_INIT-Struktur zu, indem WdfPdoInitAllocate aufgerufen wird. Der Treiber gibt dann alle PnP-/Energierückrufe an, die er empfangen möchte, und erstellt das Gerät. Der Treiber ruft AcxDeviceRemoveCircuitDevice auf, um das Audiogerät aus der Geräteliste zu entfernen.

Weitere Informationen finden Sie unter Dynamische ACX-Verbindungsentfernung in ACX-Verbindungen.

WDF-Gerätefreigabehardware

Die EVT_WDF_DEVICE_RELEASE_HARDWARE-Rückruffunktion wird in der EvtDeviceReleaseHardware-Ereignisrückruffunktion eines Treibers verwendet, um Vorgänge auszuführen, die erforderlich sind, wenn auf ein Gerät nicht mehr zugegriffen werden kann.

WDF-Gerätekontextbereinigung

Dieser Code aus dem AudioCodec-Beispiel zeigt die Verwendung einer WDF_OBJECT_ATTRIBUTES-Struktur zum Festlegen eines EvtCleanupCallback.

    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes, CODEC_DEVICE_CONTEXT);
    attributes.EvtCleanupCallback = Codec_EvtDeviceContextCleanup;

Dieser Beispielrückruf bei einem gegebenen WdfDevice bereinigt den Gerätekontext.

VOID
Codec_EvtDeviceContextCleanup(
    _In_ WDFOBJECT      WdfDevice
)

{
    WDFDEVICE               device;
    PCODEC_DEVICE_CONTEXT   devCtx;

    device = (WDFDEVICE)WdfDevice;
    devCtx = GetCodecDeviceContext(device);
    ASSERT(devCtx != nullptr);

    if (devCtx->Capture)
    {
        CodecC_CircuitCleanup(devCtx->Capture);
    }
}

WDF-Treiber entladen

Wenn der Treiber entladen wird, sollte er alle verbleibenden Ressourcen freigeben. Weitere Informationen finden Sie unter Freigeben von vom Treiber zugewiesenen Ressourcen.

Ein Treiber registriert eine EvtDriverUnload-Rückruffunktion, wenn sie WdfDriverCreate aufruft. Die Rückruffunktion EvtDriverUnload muss alle nicht gerätespezifischen Systemressourcen behandeln, die die DriverEntry-Routine zugewiesen hat. Weitere Informationen finden Sie unter EVT_WDF_DRIVER_UNLOAD-Rückruffunktion.

Dieser Code aus dem AudioCodec-Beispiel zeigt die Struktur eines Rückrufs zum Entladen des Treibers.

EVT_WDF_DRIVER_UNLOAD               AudioCodecDriverUnload;

void AudioCodecDriverUnload(
    _In_ WDFDRIVER Driver
)
{
    PAGED_CODE();

    if (!Driver)
    {
        ASSERT(FALSE);
        return;
    }

    WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver));

// Here is where you would cleanup any allocated resources associated with the driver.

    return;
}