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

Статья
08/08/2023

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

Синтаксис

GET_IDLE_WAKE_INFO GetIdleWakeInfo;

NTSTATUS GetIdleWakeInfo(
  [in, optional] PVOID Context,
  [in]           SYSTEM_POWER_STATE SystemPowerState,
  [out]          PDEVICE_WAKE_DEPTH DeepestWakeableDstate
)
{...}

Параметры

[in, optional] Context

Указатель на сведения о контексте для конкретного интерфейса. Вызывающий объект задает этому параметру значение члена Contextструктуры D3COLD_SUPPORT_INTERFACE для интерфейса.

[in] SystemPowerState

Состояние питания системы. Задайте для этого параметра одно из следующих SYSTEM_POWER_STATE значений перечисления:

PowerSystemWorking
PowerSystemSleeping1
PowerSystemSleeping2
PowerSystemSleeping3
PowerSystemHibernate

Эти значения представляют состояния питания системы от S0 (рабочее состояние системы) до S4. Для значения SystemPowerState , предоставленного вызывающим абонентом, подпрограмма определяет самое глубокое состояние питания устройства, из которого устройство может выдавать сигнал пробуждения.

[out] DeepestWakeableDstate

Самое глубокое состояние Dx с пробуждением. Этот параметр является указателем на переменную DEVICE_WAKE_DEPTH . Если вызов выполнен успешно, подпрограмма записывает одно из следующих значений перечисления в эту переменную:

DeviceWakeDepthNotWakeable
DeviceWakeDepthD0
DeviceWakeDepthD1
DeviceWakeDepthD2
DeviceWakeDepthD3hot
DeviceWakeDepthD3cold

Значение в диапазоне DeviceWakeDepthD0 до DeviceWakeDepthD3cold указывает на состояние Dx с наименьшей мощностью, из которого устройство может отправлять сигнал пробуждения, когда компьютер находится в состоянии питания системы, заданном параметром SystemPowerState . DeviceWakeDepthNotWakeable указывает, что нет состояния питания устройства, из которого устройство может отправлять сигнал пробуждения, когда компьютер находится в состоянии питания системы, указанном в SystemPowerState.

Если подпрограмме не удается определить самое глубокое состояние устройства с пробуждением (возможно, из-за того, что встроенное ПО платформы не содержит этих сведений), вызов завершается ошибкой, и подпрограмма возвращает код состояния ошибки. Если вызов GetIdleWakeInfo завершается ошибкой для любого значения параметра SystemPowerState в диапазоне PowerSystemWorking до PowerSystemHibernate, он завершится ошибкой для всех таких значений.

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

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

Для состояния питания системы, заданного вызывающим объектом, эта подпрограмма пытается определить состояние питания устройства с наименьшим питанием, из которого устройство может сообщить процессору о событии пробуждения. В случае успешного выполнения подпрограмма записывает состояние питания устройства в расположение, на которое указывает параметр DeepestWakeableDstate , и возвращает STATUS_SUCCESS. Или, если подпрограмма определяет, что устройство не может сообщить о событии пробуждения из любого состояния питания устройства, подпрограмма записывает значение DeviceWakeDepthNotWakeable в это расположение и возвращает STATUS_SUCCESS.

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

Например, если карта вставляется в слот карта PCI Express, а устройство контроллера горячей замены PCI Express для слота находится в состоянии питания устройства D0, это устройство сигнализирует процессору о прерывании. Однако если устройство контроллера находится в маломощном состоянии Dx при вставке карта, состояние питания системы компьютера может определить, должно ли это устройство сигнализировать процессору о событии пробуждения. В идеале устройство контроллера должно вести себя следующим образом:

Если компьютер находится в состоянии питания системы S0 (рабочий), устройство должно сообщить процессору о событии пробуждения.
Если компьютер находится в спящем режиме (в маломощном состоянии Sx), устройство не должно сигнализировать о событии пробуждения.

Некоторые старые устройства могут не поддерживать такое идеальное поведение. Если устройство контроллера pci Express с горячей заменой в этом примере может сигнализировать о событии пробуждения только в том случае, если компьютер находится в состоянии S3, драйвер (который в данном случае является драйвером папки "Входящие" Pci.sys) должен держать контроллер в D0, когда компьютер находится в S0 (и не готовится к переходу в спящий режим).

Драйвер в этом примере может вызвать подпрограмму GetIdleWakeInfo , чтобы определить, должно ли устройство контроллера с горячей заменой покидать состояние D0, пока компьютер находится в S0. Для этого вызова драйвер задает SystemPowerState = PowerSystemWorking. Это устройство не должно покидать состояние D0 (если компьютер находится в S0) в любом из следующих случаев:

Вызов GetIdleWakeInfo задает для выходного параметра значение DeviceWakeDepthNotWakeable или DeviceWakeDepthD0 и возвращает STATUS_SUCCESS.
Вызов GetIdleWakeInfo завершается сбоем и возвращает код состояния ошибки.

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

Драйверы для большинства устройств могут обрабатывать выходное значение DeviceWakeDepthD0 так же, как DeviceWakeDepthNotWakeable. Только у некоторых водителей может быть причина для передачи сигнала пробуждения, когда их устройства находятся в D0. Это драйверы для простых устройств, которые отслеживают внешние события, которые активируют сигналы пробуждения независимо от того, находятся ли устройства в состоянии D0 или с низким энергопотреблением Dx. Примером такого устройства является кнопка питания или кнопка спящего режима на компьютере.

Подпрограмма GetIdleWakeInfo запрашивает базовый драйвер шины и встроенное ПО системы ACPI, чтобы определить наименьшее состояние питания устройства, из которого устройство может сигнализировать о событии пробуждения. Если драйвер шины и встроенное ПО не могут предоставить эти сведения, подпрограмма завершается сбоем и возвращает код состояния ошибки.

Структура DEVICE_CAPABILITIES включает элемент DeviceWake , который предоставляет сведения, аналогичные той, которая доступна из процедуры GetIdleWakeInfo . Однако сведения в элементе DeviceWake относятся только к состояниям системы с низким энергопотреблением от S1 до S4. Для некоторых устройств сведения в элементе DeviceWake могут также относиться к состоянию питания системы S0, но драйверы не должны полагаться на такое поведение. Только подпрограмма GetIdleWakeInfo надежно сообщает о возможности устройства сигнализировать о событии пробуждения, если компьютер находится в S0.

Встроенная вспомогательная функция MapWakeDepthToDstate предоставляется для преобразования выходного значения DEVICE_WAKE_DEPTH из подпрограммы GetIdleWakeInfo в DEVICE_POWER_STATE значение, которое может использоваться в качестве входного параметра подпрограммой PoRequestPowerIrp .

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 8.
Целевая платформа	Персональный компьютер
Верхняя часть	wdm.h (включая Wdm.h)
IRQL	PASSIVE_LEVEL