PoFxRegisterComponentPerfStates-Funktion (wdm.h)

  • Artikel

Die PoFxRegisterComponentPerfStates-Routine registriert eine Gerätekomponente für die Leistungszustandsverwaltung 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
);

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 Leistungsstatus verwaltet wird. Dieser Parameter ist ein Index im Komponentenarray in der PO_FX_DEVICE Struktur, die der Gerätetreiber zum Registrieren des Geräts bei PoFx verwendet hat. Wenn das Komponentenarray N-Elemente enthält, reichen die Komponentenindizes von 0 bis N–1.

[in] Flags

Die Flags, die das Verhalten der Leistungsstatusregistrierung ändern. Legen Sie dieses Element auf null oder auf eines 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 durch das Plattformerweiterungs-Plug-In (PEP) ändern kann oder dass der Treiber Leistungszustände bei PoFx nur zu Protokollierungszwecken registriert. Wenn dieses Flag festgelegt ist, ist der PoFxRegisterComponentPerfStates-Aufruf weiterhin erfolgreich, wenn pep keine Leistungszustände für die Komponente unterstützt.
PO_FX_FLAG_PERF_QUERY_ON_F0
0x2
 Bei einigen Geräten muss pep möglicherweise einen für eine Komponente festgelegten Leistungszustand in einen bestimmten Leistungszustand (auch als nominaler Leistungszustand bezeichnet) versetzen, wenn die Komponente im Leerlauf ausgeführt wird. Treiber legen dieses Flag fest, wenn die Komponente nominale Leistungszustände enthält. In diesem Fall fragt PoFx den PEP ab, um den aktuellen Leistungszustand zu bestimmen, wenn die Komponente zu F0 übergibt.
PO_FX_FLAG_PERF_QUERY_ON_ALL_IDLE_STATES
0x4
 Bei einigen Geräten muss pep möglicherweise einen für eine Komponente festgelegten Leistungszustand in einen bestimmten Leistungszustand (auch als nominaler Leistungszustand bezeichnet) versetzen, wenn die Komponente zwischen Leerlaufzuständen wechselt. Treiber legen dieses Flag fest, wenn diese Komponente nominale Leistungszustände enthält. In diesem Fall fragt PoFx pep ab, um den aktuellen Leistungszustand zu bestimmen, wenn die Komponente zwischen Leerlaufzuständen wechselt.

[in] ComponentPerfStateCallback

Ein Zeiger auf eine ComponentPerfStateCallback-Routine . Diese Routine wird aufgerufen, wenn PoFx die Protokollierung abgeschlossen und 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 das Gerätehandle und den 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 und Informationen zum Leistungszustand für PoFx bereitstellt. Wenn der Treiber Leistungszustandsinformationen vom PEP erfordert, muss dieser Parameter auf NULL festgelegt werden.

[out] OutputStateInfo

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

Der für diesen Parameter zugeordnete Arbeitsspeicher wird von PoFx verwaltet, und der Treiber sollte diesen Arbeitsspeicher nicht freigeben, wenn das Gerät entfernt wird. Die Lebensdauer dieses Arbeitsspeichers überschreitet garantiert die Lebensdauer der PoFx-Komponente, die diese Leistungszustandssä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 status Codes.

Rückgabecode Beschreibung
STATUS_NOT_IMPLEMENTED
 Der Flags-Parameter enthält nicht das flag PO_FX_FLAG_PERF_PEP_OPTIONAL , und PEP kann keine Leistungszustandsverwaltung 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 Leistungszustandssätze in der PO_FX_COMPONENT_PERF_INFO-Struktur, die dem InputStateInfo-Parameter zugewiesen wurde.

Hinweise

Beachten Sie, dass PoFx eine tiefe Kopie der Gerätestrukturen in den Arbeitsspeicher ausführt.

Entweder der Treiber oder das Plattformerweiterungs-Plug-In (PEP) kann 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 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 pep keine Leistungszustände unterstützt, kann sich der Treiber nur zu Protokollierungszwecken für die Unterstützung des Leistungszustands bei PoFx registrieren.

Wenn sich der Treiber nur zu Protokollierungszwecken für die Unterstützung des Leistungszustands registriert oder der Treiber ordnungsgemäß mit oder ohne PEP-Unterstützung für die Leistungszustandsverwaltung funktionieren kann, muss der Treiber das flag PO_FX_FLAG_PERF_PEP_OPTIONAL im Flags-Parameter festlegen. Wenn das Flag festgelegt ist, ist der Registrierungsaufruf auch dann erfolgreich, wenn pep keine Unterstützung für Leistungszustände bereitstellt.

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

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Ab Windows 10 verfügbar.
Zielplattform Universell
Header wdm.h
Bibliothek Ntoskrnl.lib
DLL Ntoskrnl.exe
IRQL <= APC_LEVEL

Weitere Informationen

ComponentPerfStateCallback

Geräteleistungsstatusverwaltung

PO_FX_COMPONENT_PERF_INFO

PoFxRegisterDevice