Функция PoFxRegisterComponentPerfStates (wdm.h)

Статья
08/08/2023

Подпрограмма 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

Индекс, определяющий компонент, состояниями производительности которого будет управляться. Этот параметр представляет собой индекс массива Components в структуре PO_FX_DEVICE , используемой драйвером устройства для регистрации устройства в PoFx. Если массив Components содержит N элементов, индексы компонентов варьируются от 0 до N–1.

[in] Flags

Флаги, которые изменяют поведение регистрации состояния производительности. Задайте для этого элемента нулевое значение или один из следующих флагов PO_FX_FLAG_PERF_XXX bits:

Значение	Значение
PO_FX_FLAG_PERF_PEP_OPTIONAL 0x1	Указывает, что драйвер может изменять состояния производительности без помощи подключаемого модуля расширения платформы (PEP) или что драйвер регистрирует состояния производительности в PoFx только для ведения журнала. Если этот флаг установлен, вызов PoFxRegisterComponentPerfStates по-прежнему будет выполнен успешно, если PEP не поддерживает состояния производительности для компонента.
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 или PoFxIssueComponentPerfStateChangeMultiple. Этот обратный вызов может быть одинаковым для всех компонентов и всех устройств; PoFx предоставляет дескриптор устройства и индекс компонента в каждом вызове завершения.

[in] InputStateInfo

Если драйвер предоставляет сведения о состоянии производительности, этот параметр содержит указатель на драйвер, выделенный PO_FX_COMPONENT_PERF_INFO структуре, которая предоставляет сведения о состоянии производительности для PoFx. Если драйверу требуются сведения о состоянии производительности из PEP, этому параметру необходимо задать значение NULL.

[out] OutputStateInfo

Если драйверу требуются сведения о состоянии производительности из PEP, после успешной регистрации этот параметр содержит указатель на PO_FX_COMPONENT_PERF_INFO структуру, которая предоставляет сведения о состоянии производительности, определенные PEP. Если драйвер предоставляет сведения о состоянии производительности, для этого параметра необходимо задать значение NULL.

Память, выделенная для этого параметра, управляется PoFx, и драйвер не должен освобождать эту память при удалении устройства. Время существования этой памяти гарантированно превысит время существования компонента PoFx, содержащего эти наборы состояний производительности.

Возвращаемое значение

PoFxRegisterComponentPerfStates возвращает STATUS_SUCCESS , если PoFx принимает регистрацию устройств состояний производительности. Если какая-либо из необходимых сведений не указана или указана неверно, регистрация завершится ошибкой с кодом возврата, кроме STATUS_SUCCESS. Возможные возвращаемые значения ошибок включают следующие коды состояния.

Код возврата	Описание
STATUS_NOT_IMPLEMENTED	Параметр Flags не содержит флаг PO_FX_FLAG_PERF_PEP_OPTIONAL , а PEP не может обеспечить управление состоянием производительности для этого устройства.
STATUS_INVALID_PARAMETER	Оба параметра InputStateInfo и OutputStateInfo имеют значение NULL, либо оба этих параметра не имеют значения NULL, либо в структуре PO_FX_COMPONENT_PERF_INFO , назначенной параметру InputStateInfo , отсутствуют наборы состояний производительности.

Если драйвер предоставляет сведения о состоянии производительности, драйвер должен задать для параметра InputStateInfo указатель на PO_FX_COMPONENT_PERF_INFO структуру, содержащую сведения о состоянии производительности. В противном случае драйвер должен задать для этого параметра значение NULL.
Если PEP предоставляет сведения о состоянии производительности, драйвер должен задать для параметра OutputStateInfo допустимый указатель на структуру PO_FX_COMPONENT_PERF_INFO , получающую сведения о состоянии производительности. В противном случае драйвер должен задать для этого параметра значение NULL.

Если PEP не поддерживает состояния производительности, драйвер может зарегистрироваться для поддержки состояния производительности в PoFx только для ведения журнала.

Если драйвер регистрирует для поддержки состояния производительности только в целях ведения журнала или если драйвер может правильно работать с поддержкой PEP для управления состоянием производительности или без нее, драйвер должен установить флаг PO_FX_FLAG_PERF_PEP_OPTIONAL в параметре Flags . Если флаг установлен, вызов регистрации будет выполнен успешно, даже если PEP не поддерживает состояния производительности.

Если драйвер требует, чтобы PEP предоставлял сведения о состоянии производительности, драйвер не может задать флаг PO_FX_FLAG_PERF_PEP_OPTIONAL в параметре Flags .

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 10.
Целевая платформа	Универсальное
Верхняя часть	wdm.h
Библиотека	Ntoskrnl.lib
DLL	Ntoskrnl.exe
IRQL	<= APC_LEVEL

См. также раздел

ComponentPerfStateCallback

Управление состоянием производительности устройства

PO_FX_COMPONENT_PERF_INFO

PoFxRegisterDevice