EVT_ACX_CIRCUIT_PREPARE_HARDWARE Rückruffunktion (acxcircuit.h)

  • Artikel

Der EVT_ACX_CIRCUIT_PREPARE_HARDWARE Rückrufs wird vom Treiber verwendet, um Funktionen hinzuzufügen, wenn sich ein ACXCIRCUIT in der Vorbereitungsphase der Hardware befindet.

Syntax

EVT_ACX_CIRCUIT_PREPARE_HARDWARE EvtAcxCircuitPrepareHardware;

NTSTATUS EvtAcxCircuitPrepareHardware(
  WDFDEVICE Device,
  ACXCIRCUIT Circuit,
  WDFCMRESLIST ResourcesRaw,
  WDFCMRESLIST ResourcesTranslated
)
{...}

Parameter

Device

Ein WDFDEVICE-Objekt (beschrieben in WDF – Zusammenfassung von Frameworkobjekten), das dem angegebenen ACXCIRCUIT zugeordnet ist.

Circuit

Das ACXCIRCUIT-Objekt (beschrieben unter Zusammenfassung von ACX-Objekten) in der Vorbereitungsphase der Hardware.

ResourcesRaw

Ein Handle für ein Frameworkressourcenlistenobjekt, das die Rohhardwareressourcen identifiziert, die der Plug & Play-Manager dem Gerät zugewiesen hat. Weitere Informationen zu Rohressourcen finden Sie unter Unformatierte und übersetzte Ressourcen.

ResourcesTranslated

Ein Handle für ein Frameworkressourcenlistenobjekt, das die übersetzten Hardwareressourcen identifiziert, die der Plug & Play-Manager dem Gerät zugewiesen hat.

Rückgabewert

Gibt zurück STATUS_SUCCESS , wenn der Aufruf erfolgreich war. Andernfalls wird ein geeigneter Fehlercode zurückgegeben. Weitere Informationen finden Sie unter Verwenden von NTSTATUS-Werten.

Hinweise

Um eine EvtAcxCircuitPrepareHardware-Rückruffunktion zu registrieren, muss ein Treiber die AcxCircuitInitSetAcxCircuitPnpPowerCallbacks-Methode aufrufen.

Wenn der Treiber eine EvtAcxCircuitPrepareHardware-Rückruffunktion für eine ACXCIRCUIT registriert hat, ruft das ACX-Framework die Funktion auf, nachdem das WDF-Framework die Rückruffunktion EvtDevicePrepareHardware des Treibers aufgerufen hat.

Die Rückruffunktion EvtAcxCircuitPrepareHardware greift mithilfe der empfangenen Handles ResourcesRaw und ResourcesTranslated auf die rohen und übersetzten Hardwareressourcen des Geräts zu. Die Rückruffunktion kann WdfCmResourceListGetCount und WdfCmResourceListGetDescriptor aufrufen, um die Ressourcenlisten zu durchlaufen. Diese Rückruffunktion kann die Ressourcenlisten nicht ändern.

Weitere Informationen zu Ressourcenlisten und der Reihenfolge, in der die Ressourcen angezeigt werden, finden Sie unter Unformatierte und übersetzte Ressourcen.

In der Regel führt die EvtAcxCircuitPrepareHardware-Rückruffunktion Ihres Treibers bei Bedarf folgendes aus:

  • Ordnet adressen des physischen Arbeitsspeichers virtuellen Adressen des ACXCIRCUIT zu, damit der Treiber auf arbeitsspeicher zugreifen kann, der dem Gerät zugewiesen ist.
  • Optional kann die EvtAcxCircuitPrepareHardware-Rückruffunktion Ihres Treibers ein Arbeitselement in die Warteschlange stellen, um andere zeitintensive Konfigurationsaufgaben auszuführen. Die Verwendung eines Arbeitselements für solche Vorgänge kann dazu beitragen, sicherzustellen, dass die Startzeit Ihres Geräts die Systemstartzeit nicht erhöht. Weitere Informationen finden Sie unter Verwenden von Framework-Arbeitselementen.
  • In der Regel sollten alle anderen Hardwareinitialisierungsvorgänge, einschließlich des Ladens der Firmware, bei jedem Wechsel des Geräts in den Betriebszustand (D0) erfolgen und daher in der EvtDeviceD0Entry-Rückruffunktion des Treibers erfolgen.

Die Handles ResourcesRaw und ResourcesTranslated, die die Rückruffunktion EvtAcxCircuitPrepareHardware/EvtDevicePrepareHardware empfängt, bleiben gültig, bis die Rückruffunktion EvtDeviceReleaseHardware des Treibers zurückgibt.

Wenn der Treiber beim EvtAcxCircuitPrepareHardware-Rückruf fehlschlägt, wird das ACXCIRCUIT-Objekt in den Status delete-pending versetzt, und die zugeordneten ACXSTREAMS werden heruntergefahren.

Weitere Informationen zu Hardwareressourcen finden Sie unter Einführung in Hardwareressourcen.

Weitere Informationen dazu, wann diese Rückruffunktionen vom ACX- und WDF-Framework aufgerufen werden, finden Sie unter PnP- und Energieverwaltungsszenarien.

Weitere Informationen zu Treibern, die diese Rückruffunktion bereitstellen, finden Sie unter Unterstützen der PnP- und Energieverwaltung im Funktionstreiber.

Beispiel

Das Beispiel für die Verwendung ist unten dargestellt.

NTSTATUS
EvtCircuitPrepareHardware(
    _In_ WDFDEVICE      Device,
    _In_ ACXCIRCUIT     Circuit,
    _In_ WDFCMRESLIST   ResourcesRaw,
    _In_ WDFCMRESLIST   ResourcesTranslated
    )
{
    NTSTATUS            status      = STATUS_SUCCESS;
    PCIRCUIT_CONTEXT    circuitCtx  = GetCircuitContext(Circuit);
    CIpcEventReader *   eventReader = circuitCtx->EventReader;

    PASSIVE_CODE();

    UNREFERENCED_PARAMETER(Device);
    UNREFERENCED_PARAMETER(ResourcesRaw);
    UNREFERENCED_PARAMETER(ResourcesTranslated);

    //
    // Enable 'remote' circuit notifications.
    //
    ASSERT(eventReader);
    status = eventReader->EnableEvents();
    if (!NT_SUCCESS(status))
    {
        DrvLogError(g_RecorderLog, FLAG_INIT,
                    "ACXCIRCUIT %p, CIpcEventReader::EnableEvents failed, %!STATUS!",
                    Circuit, status);
        goto exit;
    }

    status = STATUS_SUCCESS;

exit:
    return status;
}

ACX-Anforderungen

ACX-Mindestversion: 1.0

Weitere Informationen zu ACX-Versionen finden Sie unter ACX-Versionsübersicht.

Anforderungen

Anforderung Wert
Header acxcircuit.h
IRQL PASSIVE_LEVEL

Weitere Informationen