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

Статья
08/08/2023

Подпрограмма PoFxRegisterDevice регистрирует устройство с помощью платформы управления питанием (PoFx).

Синтаксис

NTSTATUS PoFxRegisterDevice(
  [in]  PDEVICE_OBJECT Pdo,
  [in]  PPO_FX_DEVICE  Device,
  [out] POHANDLE       *Handle
);

Параметры

[in] Pdo

Указатель на объект физического устройства (PDO). Этот параметр указывает на структуру DEVICE_OBJECT , представляющую регистрируемого физического устройства. Вызывающий объект является владельцем политики питания для устройства, который обычно является драйвером функции устройства.

[in] Device

Указатель на структуру PO_FX_DEVICE , выделенную вызывающим объектом, которая содержит сведения о регистрации устройства. Эта структура содержит указатели на набор процедур обратного вызова, реализованных драйвером устройства. PoFx вызывает эти подпрограммы для взаимодействия с драйвером.

[out] Handle

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

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

PoFxRegisterDevice возвращает STATUS_SUCCESS , если подпрограмма успешно регистрирует устройство. Возможные возвращаемые значения ошибок включают следующие коды состояния.

Код возврата	Описание
STATUS_INVALID_PARAMETER	Pdo имеет значение NULL; или структура PPO_FX_DEVICE имеет недопустимый номер версии или число компонентов, равное нулю; или число состояний простоя, указанное для компонента, равно нулю; или недопустимое описание состояния простоя.
STATUS_DEVICE_NOT_READY	Устройство не готово.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно ресурсов для завершения регистрации.

Драйвер устройства обычно вызывает эту подпрограмму из обработчика запросов IRP_MN_START_DEVICE драйвера. Драйвер не должен вызывать эту подпрограмму до того, как устройство получит запрос IRP_MN_START_DEVICE . Устройство получает первый запрос IRP_MN_START_DEVICE при первом запуске устройства. Устройство получает дополнительный запрос IRP_MN_START_DEVICE каждый раз при перезапуске устройства после остановки для балансировки ресурсов. Вызов PoFxRegisterDevice для регистрации уже зарегистрированного устройства является неустранимой ошибкой и вызывает ошибку проверка. Обратите внимание, что PoFx выполняет глубокое копирование структур устройств в память.

Прежде чем драйвер вызывает PoFxRegisterDevice, устройство должно соответствовать следующим условиям:

Устройство (т. е. PDO) еще не зарегистрировано в PoFx.
Устройство находится в состоянии питания D0 (полностью включено).
Устройство находится в состоянии выполнения.
Каждый компонент на устройстве находится в состоянии питания F0 (полностью включен).
Каждый компонент находится в активном состоянии.

Регистрируя устройство в PoFx, драйвер берет на себя ответственность за информирование PoFx, когда компонент активно используется и когда компонент простаивает. Пока устройство зарегистрировано, драйвер должен вызвать подпрограмму PoFxActivateComponent , чтобы получить доступ к аппаратным регистрам компонента, а драйвер должен вызвать подпрограмму PoFxIdleComponent , чтобы уведомить PoFx, когда драйвер больше не нуждается в доступе к компоненту.

После того как драйвер вызывает PoFxRegisterDevice для регистрации устройства с помощью PoFx, все компоненты на устройстве полностью включены и находятся в активном состоянии, чтобы драйвер смог завершить инициализацию оборудования. Чтобы запустить активное управление питанием, драйвер должен вызвать подпрограмму PoFxStartDevicePowerManagement .

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

Как правило, драйвер Kernel-Mode Driver Framework (KMDF) для однокомпонентного устройства не вызывает PoFxRegisterDevice для регистрации устройства в PoFx. Вместо этого этот драйвер получает дескриптор регистрации PoFx, когда KMDF вызывает функцию обратного вызова EvtDeviceWdmPostPoFxRegisterDevice драйвера. Дополнительные сведения см. в статье Поддержка нескольких функциональных состояний питания для устройств Single-Component.

Сведения о том, как драйвер KMDF для многокомпонентного устройства регистрируется с помощью PoFx, см. в статье Поддержка нескольких функциональных состояний питания для устройств Multiple-Component.

Требования

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