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

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

Подпрограмма 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 , если подпрограмма успешно регистрирует устройство. Возможные значения возвращаемых ошибок включают следующие коды состояния.

Код возврата Description
СТАТУС_НЕДЕЙСТВИТЕЛЬНЫЙ_ПАРАМЕТР
 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 , чтобы уведомить PoFxFx, когда драйвер больше не требует доступа к компоненту.

После вызова драйвера 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.
целевая платформа Всеобщий
Header wdm.h
Library Ntoskrnl.lib
DLL Ntoskrnl.exe
IRQL PASSIVE_LEVEL

См. также

DEVICE_OBJECT

EvtDeviceWdmPostPoFxRegisterDevice

IRP_MN_START_DEVICE

PO_FX_DEVICE

PoFxActivateComponent

PoFxIdleComponent

PoFxStartDevicePowerManagement

  • Last updated on