EVT_ACX_CIRCUIT_PREPARE_HARDWARE Rückruffunktion (acxcircuit.h)
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 |