функция обратного вызова PO_FX_COMPONENT_IDLE_STATE_CALLBACK (wdm.h)

Статья
03/08/2023

Подпрограмма обратного вызова ComponentIdleStateCallback уведомляет драйвер об ожидающих изменениях состояния питания Fx указанного компонента.

Синтаксис

PO_FX_COMPONENT_IDLE_STATE_CALLBACK PoFxComponentIdleStateCallback;

void PoFxComponentIdleStateCallback(
  [in] PVOID Context,
  [in] ULONG Component,
  [in] ULONG State
)
{...}

Параметры

[in] Context

Указатель на контекст устройства. Драйвер устройства использует этот контекст для хранения сведений о текущем состоянии питания устройства. Драйвер устройства указал этот указатель в элементе DeviceContextструктуры PO_FX_DEVICE , которую драйвер использовал для регистрации устройства с помощью платформы управления питанием (PoFx). Этот контекст непрозрачн для PoFx.

[in] Component

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

[in] State

Указывает новое состояние питания Fx, на которое изменится компонент. Если этот параметр равен нулю, новое состояние — F0; Если этот параметр равен одному, новое состояние — F1; и так далее.

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

None

Remarks

Когда PoFx вызывает подпрограмму ComponentIdleStateCallback драйвера, драйверу может потребоваться подготовиться к ожидающим изменению состояния Fx. После завершения всех необходимых подготовительных действий драйвер должен вызвать подпрограмму PoFxCompleteIdleState , чтобы уведомить PoFx о том, что драйвер завершил ответ на обратный вызов ComponentIdleStateCallback . Вызов PoFxCompleteIdleState может выполняться до или после возврата подпрограммы ComponentIdleStateCallback .

Если компонент должен переключиться с F0 на маломощное состояние Fx, в котором устройство потеряет аппаратное состояние компонента, драйвер должен сохранить аппаратное состояние компонента, прежде чем произойдет переход в новое состояние Fx. Если компонент должен переключиться из состояния Fx с низким энергопотреблением на F0, а состояние оборудования было сохранено ранее, драйвер должен восстановить состояние оборудования после восстановления питания компонента.

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

Если драйвер отвечает за настройку состояния питания компонента, драйвер должен изменить состояние питания в ответ на обратный вызов ComponentIdleStateCallback . Для перехода с F0 в маломощное состояние Fx компонент находится в F0 при входе в подпрограмму ComponentIdleStateCallback , и драйвер должен переключить компонент в новое состояние Fx перед вызовом PoFxCompleteIdleState. Для перехода из маломощного состояния Fx в F0 компонент находится в состоянии низкой мощности Fx при входе в подпрограмму ComponentIdleStateCallback , и драйвер должен переключить компонент на F0 перед вызовом PoFxCompleteIdleState.

Если драйвер не отвечает за настройку состояния питания компонента, драйвер должен предполагать, что компонент всегда находится в состоянии F0 при входе в подпрограмму ComponentIdleStateCallback . При отложенном переходе из F0 в маломощное состояние Fx переход в новое состояние Fx не происходит до тех пор, пока драйвер не вызовет PoFxCompleteIdleState. При переходе из маломощного состояния Fx в F0 переход на F0 происходит до вызова подпрограммы ComponentIdleStateCallback .

PoFx никогда не вызывает подпрограмму ComponentIdleStateCallback для переключения непосредственно из одного состояния Fx с низким энергопотреблением в другое состояние Fx с низким энергопотреблением. Например, PoFx может потребоваться переключить компонент из одного состояния Fx с низким энергопотреблением в другое в ответ на вызов подпрограммы PoFxSetComponentLatency, PoFxSetComponentResidency или PoFxSetComponentWake . В этом случае PoFx сначала вызывает подпрограмму ComponentIdleStateCallback для переключения со старого состояния Fx на F0, а затем вызывает подпрограмму ComponentIdleStateCallback второй раз, чтобы переключиться с F0 на новое состояние Fx.

Примеры

Чтобы определить подпрограмму обратного вызова ComponentIdleStateCallback , необходимо сначала предоставить объявление функции, определяющее тип определяемой процедуры обратного вызова. Windows предоставляет набор типов функций обратного вызова для драйверов. Объявление функции с помощью типов функций обратного вызова помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.

Например, чтобы определить подпрограмму обратного вызова ComponentIdleStateCallback с именем MyComponentIdleStateCallback, используйте тип PO_FX_COMPONENT_IDLE_STATE_CALLBACK, как показано в следующем примере кода:

PO_FX_COMPONENT_IDLE_STATE_CALLBACK MyComponentIdleStateCallback;

Затем реализуйте процедуру обратного вызова следующим образом:

_Use_decl_annotations_
VOID
  MyComponentIdleStateCallback(
    PVOID Context,
    ULONG Component,
    ULONG State
    )
  {
      // Function body
  }

Тип функции PO_FX_COMPONENT_IDLE_STATE_CALLBACK определен в файле заголовка Wdm.h. Чтобы более точно определить ошибки при запуске средств анализа кода, не забудьте добавить заметку _Use_decl_annotations_ в определение функции. Заметка _Use_decl_annotations_ гарантирует, что будут использоваться заметки, которые применяются к типу функции PO_FX_COMPONENT_IDLE_STATE_CALLBACK в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в статье Объявление функций с помощью типов ролей функций для драйверов WDM. Сведения о _Use_decl_annotations_см. в статье Поведение функции с заметками.

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается в Windows 8 и более поздних версиях Windows.
Целевая платформа	Персональный компьютер
Верхняя часть	wdm.h (включая Wudfwdm.h)
IRQL	Вызывается по адресу IRQL <= DISPATCH_LEVEL.