Freigeben über

PoFxRegisterComponentPerfStates-Funktion (wdm.h)

Die PoFxRegisterComponentPerfStates-Routine registriert eine Gerätekomponente für die Verwaltung des Leistungszustands durch das Power Management Framework (PoFx).

Syntax

NTSTATUS PoFxRegisterComponentPerfStates(
  [in]  POHANDLE                             Handle,
  [in]  ULONG                                Component,
  [in]  ULONGLONG                            Flags,
  [in]  PPO_FX_COMPONENT_PERF_STATE_CALLBACK ComponentPerfStateCallback,
  [in]  PPO_FX_COMPONENT_PERF_INFO           InputStateInfo,
  [out] PPO_FX_COMPONENT_PERF_INFO           *OutputStateInfo
);

Die Parameter

[in] Handle

Ein Handle, das die Registrierung des Geräts bei PoFx darstellt. Der Gerätetreiber hat dieses Handle zuvor von der PoFxRegisterDevice-Routine erhalten.

[in] Component

Der Index, der die Komponente identifiziert, deren Leistungszustände verwaltet werden. Dieser Parameter ist ein Index im Komponentenarray in der PO_FX_DEVICE Struktur, mit der der Gerätetreiber das Gerät bei PoFx registriert hat. Wenn das Komponentenarray N-Elemente enthält, reichen Komponentenindizes von 0 bis N-1.

[in] Flags

Die Flags, die das Verhalten der Registrierung des Leistungsstatus ändern. Legen Sie dieses Element auf Null oder auf eine der folgenden Flags PO_FX_FLAG_PERF_XXX-Bits fest:

Wert Bedeutung
PO_FX_FLAG_PERF_PEP_OPTIONAL
0x1
 Gibt an, dass der Treiber Leistungszustände ohne Unterstützung des Plattformerweiterungs-Plug-Ins (PEP) ändern kann oder dass der Treiber Leistungszustände nur für Protokollierungszwecke bei PoFx registriert. Wenn dieses Flag festgelegt ist, wird der PoFxRegisterComponentPerfStates-Aufruf weiterhin erfolgreich ausgeführt, wenn der PEP keine Leistungszustände für die Komponente unterstützt.
PO_FX_FLAG_PERF_QUERY_ON_F0
0 x 2
 Bei einigen Geräten muss der PEP möglicherweise einen Leistungsstatus platzieren, der für eine Komponente in einen bestimmten Leistungszustand (als nominaler Leistungszustand bezeichnet) festgelegt wird, wenn die Komponente leer ist. Treiber legen dieses Kennzeichen fest, wenn die Komponente nominale Leistungszustände enthält. In diesem Fall fragt PoFx den PEP ab, um den aktuellen Leistungsstatus zu ermitteln, wenn die Komponente zu F0 wechselt.
PO_FX_FLAG_PERF_QUERY_ON_ALL_IDLE_STATES
0 x 4
 Bei einigen Geräten muss der PEP möglicherweise einen Leistungsstatus platzieren, der für eine Komponente in einen bestimmten Leistungszustand (als nominaler Leistungszustand bezeichnet) festgelegt wird, wenn die Komponente zwischen Leerlaufzuständen wechselt. Treiber legen dieses Kennzeichen fest, wenn diese Komponente nominale Leistungszustände enthält. In diesem Fall fragt PoFx den PEP ab, um den aktuellen Leistungsstatus zu ermitteln, wenn die Komponente zwischen leerlaufstatus wechselt.

[in] ComponentPerfStateCallback

Ein Zeiger auf eine ComponentPerfStateCallback-Routine . Diese Routine wird aufgerufen, wenn PoFx die Protokollierung abgeschlossen hat und den PEP über einen Leistungszustandsübergang benachrichtigt, der durch den Aufruf des Treibers an PoFxIssueComponentPerfStateChange oder PoFxIssueComponentPerfStateChangeMultiple initiiert wird. Dieser Rückruf kann für alle Komponenten und alle Geräte identisch sein; PoFx stellt den Gerätehandle- und Komponentenindex in jedem Abschlussaufruf bereit.

[in] InputStateInfo

Wenn der Treiber Leistungsstatusinformationen bereitstellt, enthält dieser Parameter einen Zeiger auf einen Treiber , der PO_FX_COMPONENT_PERF_INFO Struktur zugeordnet ist, die Leistungsstatusinformationen zu PoFx bereitstellt. Wenn der Treiber Leistungsstatusinformationen aus dem PEP erfordert, muss dieser Parameter auf NULL festgelegt werden.

[out] OutputStateInfo

Wenn der Treiber Leistungsstatusinformationen vom PEP erfordert, enthält dieser Parameter nach einer erfolgreichen Registrierung einen Zeiger auf eine PO_FX_COMPONENT_PERF_INFO Struktur, die vom PEP definierte Leistungsstatusinformationen bereitstellt. Wenn der Treiber Leistungsstatusinformationen bereitstellt, muss dieser Parameter auf NULL festgelegt werden.

Der für diesen Parameter zugewiesene Speicher wird von PoFx verwaltet, und der Treiber sollte diesen Speicher nicht freigeben, wenn das Gerät entfernt wird. Die Lebensdauer dieses Speichers wird garantiert die Lebensdauer der PoFx-Komponente überschreiten, die diese Leistungsstatussätze enthält.

Rückgabewert

PoFxRegisterComponentPerfStates gibt STATUS_SUCCESS zurück, wenn PoFx die Registrierung von Leistungszuständen des Geräts akzeptiert. Wenn eine der erforderlichen Informationen nicht angegeben oder falsch ist, schlägt die Registrierung mit einem anderen Rückgabecode als STATUS_SUCCESS fehl. Mögliche Fehlerrückgabewerte sind die folgenden Statuscodes.

Rückgabecode Description
STATUS_NOT_IMPLEMENTED
 Der Parameter "Flags " enthält nicht das PO_FX_FLAG_PERF_PEP_OPTIONAL Flag, und der PEP kann keine Leistungsstatusverwaltung für dieses Gerät bereitstellen.
STATUS_INVALID_PARAMETER
 Sowohl InputStateInfo als auch OutputStateInfo sind NULL, oder beide Parameter sind nicht NULL, oder es gibt keine Leistungsstatussätze in der PO_FX_COMPONENT_PERF_INFO Struktur, die dem InputStateInfo-Parameter zugewiesen wurde.

Bemerkungen

Beachten Sie, dass PoFx eine tiefe Kopie der Gerätestrukturen in seinem Speicher durchführt.

Entweder der Treiber oder das Plattformerweiterungs-Plug-In (PEP) können Informationen zu den Leistungszuständen bereitstellen, die von den einzelnen Komponenten unterstützt werden:

  • Wenn der Treiber Leistungsstatusinformationen bereitstellt, muss der Treiber den InputStateInfo-Parameter auf einen Zeiger auf eine PO_FX_COMPONENT_PERF_INFO Struktur festlegen, die die Leistungsstatusinformationen enthält. Andernfalls muss der Treiber diesen Parameter auf NULL festlegen.
  • Wenn der PEP Leistungsstatusinformationen bereitstellt, muss der Treiber den OutputStateInfo-Parameter auf einen gültigen Zeiger auf eine PO_FX_COMPONENT_PERF_INFO Struktur festlegen, die die Leistungsstatusinformationen empfängt. Andernfalls muss der Treiber diesen Parameter auf NULL festlegen.
Wenn der PEP keine Leistungszustände unterstützt, kann der Treiber nur zur Protokollierung zur Leistungsstatusunterstützung bei PoFx registriert werden.

Wenn sich der Treiber nur für die Leistungsstatusunterstützung für Protokollierungszwecke registriert oder der Treiber ordnungsgemäß mit oder ohne PEP-Unterstützung für die Leistungsstatusverwaltung funktionieren kann, muss der Treiber das PO_FX_FLAG_PERF_PEP_OPTIONAL Flag im Flags-Parameter festlegen. Wenn die Kennzeichnung festgelegt ist, wird der Registrierungsaufruf erfolgreich ausgeführt, auch wenn der PEP keine Unterstützung für Leistungszustände bietet.

Wenn der Treiber den PEP benötigt, um Leistungsstatusinformationen bereitzustellen, kann der Treiber das PO_FX_FLAG_PERF_PEP_OPTIONAL Flag im Parameter "Flags " nicht festlegen.

Anforderungen

Anforderung Wert
Mindestens unterstützter Client Verfügbar ab Windows 10.
Zielplattform Universal
Header wdm.h
Library Ntoskrnl.lib
DLL Ntoskrnl.exe
IRQL <= APC_LEVEL

Siehe auch

ComponentPerfStateCallback

Geräteleistungsstatusverwaltung

PO_FX_COMPONENT_PERF_INFO

PoFxRegisterDevice

  • Last updated on