Поделиться через

Функция 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

Индекс, определяющий компонент, состояниями производительности которого будет управляться. Этот параметр представляет собой индекс массива 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 , отсутствуют наборы состояний производительности.

Комментарии

Обратите внимание, что PoFx выполняет глубокое копирование структур устройства в его память.

Драйвер или подключаемый модуль расширения платформы (PEP) может предоставлять сведения о состояниях производительности, поддерживаемых каждым компонентом:

  • Если драйвер предоставляет сведения о состоянии производительности, драйвер должен задать для параметра 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