PoFxRegisterComponentPerfStates 函式 (wdm.h)

  • 發行項

PoFxRegisterComponentPerfStates 例程會註冊裝置元件，以供電源管理架構 (PoFx) 進行效能狀態管理。

語法

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
);

參數

[in] Handle

句柄，表示向PoFx註冊裝置。 裝置驅動程式先前已從 PoFxRegisterDevice 例程收到此句柄。

[in] Component

識別將管理其效能狀態之元件的索引。 此參數是裝置驅動程式用來向PoFx註冊裝置之PO_FX_DEVICE結構中 Components 陣列的索引。 如果 Components 陣列包含 N 個元素，元件索引的範圍從 0 到 N–1。

[in] Flags

修改效能狀態註冊行為的旗標。 將此成員設定為零或下列其中一個旗標 ，PO_FX_FLAG_PERF_XXX 位：

值 意義
PO_FX_FLAG_PERF_PEP_OPTIONAL
0x1
 表示驅動程式可以變更效能狀態，而不需要平臺擴充功能外掛程式的協助， (PEP) ，或驅動程式只向 PoFx 註冊效能狀態以供記錄之用。 如果設定此旗標，如果 PEP 不支援元件的效能狀態， PoFxRegisterComponentPerfStates 呼叫仍會成功。
PO_FX_FLAG_PERF_QUERY_ON_F0
0x2
 對於某些裝置，PEP 可能需要將元件的效能狀態設定為特定效能狀態， (稱為閑置元件時， ) 為具名的效能狀態 。 如果元件包含標準效能狀態，驅動程式會設定此旗標，在此情況下，PoFx 會查詢 PEP，以在元件轉換為 F0 時判斷目前的效能狀態。
PO_FX_FLAG_PERF_QUERY_ON_ALL_IDLE_STATES
0x4
 對於某些裝置，PEP 可能需要將元件的效能狀態設定為特定效能狀態， (稱為在閑置狀態之間轉換元件時，) 稱為「具名效能狀態 」。 如果此元件包含標準效能狀態，驅動程式會設定此旗標，在此情況下，PoFx 會查詢 PEP，以在元件在閑置狀態之間轉換時判斷目前的效能狀態。

[in] ComponentPerfStateCallback

ComponentPerfStateCallback 例程的指標。 當 PoFx 完成記錄，並通知 PEP 有關驅動程式呼叫 PoFxIssueComponentPerfStateChange 或 PoFxIssueComponentPerfStateChange 或 PoFxIssueComponentPerfStateChangeMultiple 所起始的效能狀態轉換時，就會呼叫此例程。 所有元件和所有裝置的回呼可能相同;PoFx 會在每個完成呼叫中提供裝置句柄和元件索引。

[in] InputStateInfo

如果驅動程式提供效能狀態資訊，此參數會包含配置 PO_FX_COMPONENT_PERF_INFO 結構之驅動程式的指標，可提供PoFx的效能狀態資訊。 如果驅動程式需要 PEP 的效能狀態資訊，此參數必須設定為 NULL。

[out] OutputStateInfo

如果驅動程式需要 PEP 的效能狀態資訊，在成功註冊之後，此參數會包含提供 PEP 所定義效能狀態資訊的 PO_FX_COMPONENT_PERF_INFO 結構的指標。 如果驅動程式提供效能狀態資訊，此參數必須設定為 NULL。

配置給此參數的記憶體是由PoFx管理，而驅動程式在移除裝置時不應釋放此記憶體。 此記憶體的存留期保證超過包含這些效能狀態集之 PoFx 元件的存留期。

傳回值

如果 PoFx 接受裝置的效能狀態註冊，PoFxRegisterComponentPerfStates 會傳回STATUS_SUCCESS。 如果未提供任何必要資訊或不正確，註冊將會失敗，並傳回 STATUS_SUCCESS以外的傳回碼。 可能的錯誤傳回值包括下列狀態代碼。

傳回碼 Description
STATUS_NOT_IMPLEMENTED
 Flags 參數不包含PO_FX_FLAG_PERF_PEP_OPTIONAL旗標，而且 PEP 無法為此裝置提供效能狀態管理。
STATUS_INVALID_PARAMETER
 InputStateInfo 和 OutputStateInfo 都是 NULL，或這兩個參數都不是 NULL，或在指派給 InputStateInfo 參數的 PO_FX_COMPONENT_PERF_INFO 結構中沒有效能狀態集。

備註

請注意，PoFx 會在裝置的記憶體中執行裝置結構的深層複本。

驅動程式或平臺擴充功能外掛程式 (PEP) 可能會提供每個元件所支援效能狀態的相關信息：

  • 如果驅動程式提供效能狀態資訊，驅動程式必須將 InputStateInfo 參數設定為包含效能狀態資訊的 PO_FX_COMPONENT_PERF_INFO 結構指標。 否則，驅動程式必須將此參數設定為 NULL。
  • 如果 PEP 提供效能狀態資訊，驅動程式必須將 OutputStateInfo 參數設定為接收效能狀態資訊的 PO_FX_COMPONENT_PERF_INFO 結構的有效指標。 否則，驅動程式必須將此參數設定為 NULL。
如果 PEP 不支援效能狀態，驅動程式可能會向 PoFx 註冊效能狀態支援，僅供記錄之用。

如果驅動程式只註冊效能狀態支援以進行記錄，或驅動程式可以正確運作，或沒有 PEP 支援效能狀態管理，則驅動程式必須在 Flags 參數中設定PO_FX_FLAG_PERF_PEP_OPTIONAL旗標。 如果設定旗標，即使 PEP 不支援效能狀態，註冊呼叫仍會成功。

如果驅動程式要求 PEP 提供效能狀態資訊，驅動程式就無法在 Flags 參數中設定PO_FX_FLAG_PERF_PEP_OPTIONAL旗標。

規格需求

需求 值
最低支援的用戶端 從 Windows 10 開始提供。
目標平台 Universal
標頭 wdm.h
程式庫 Ntoskrnl.lib
Dll Ntoskrnl.exe
IRQL <= APC_LEVEL

另請參閱

ComponentPerfStateCallback

裝置效能狀態管理

PO_FX_COMPONENT_PERF_INFO

PoFxRegisterDevice