Макрос WdfDeviceStopIdle (wdfdevice.h)

Статья
03/22/2025

[Применимо к KMDF и UMDF]

Метод WdfDeviceStopIdle сообщает платформе, что указанное устройство должно быть помещено в рабочее состояние питания (D0).

Синтаксис

NTSTATUS WdfDeviceStopIdle(
   _In_ WDFDEVICE Device,
   _In_ BOOLEAN WaitForD0
);

Параметры

[in] Device

Дескриптор объекта устройства платформы.

[in] WaitForD0

Логическое значение, указывающее, когда WdfDeviceStopIdle возвращается. Если TRUE, он возвращается только после того, как указанное устройство ввело состояние питания устройства D0. Если FALSE, метод возвращается немедленно.

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

Нет

Замечания

Этот макрос может возвращать следующие значения:

Возвращаемое значение	Значение
STATUS_PENDING	Устройство работает асинхронно.
STATUS_INVALID_DEVICE_STATE	Драйвер не является владельцем политики питания для устройства.
STATUS_POWER_STATE_INVALID	Произошел сбой устройства, и устройство не может ввести состояние питания D0.

Метод может возвращать другие значения NTSTATUS.

Примечание.

Для устройств, указывающих SystemManagedIdleTimeout или SystemManagedIdleTimeoutWithHint в перечислении WDF_POWER_POLICY_IDLE_TIMEOUT_TYPE, при вызове WdfDeviceStopIdle с WaitForD0 задано значение FALSE, если устройство по-прежнему находится в D0 и период простоя еще не истек, начиная с WDF версий 1.33/2.33, WdfDeviceStopIdle возвращает STATUS_SUCCESS (в предыдущих версиях это привело к возврату значения STATUS_PENDING).

Ошибка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

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

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

Предупреждение

Не вызывайте WdfDeviceStopIdle с WaitForD0 = TRUE во время отключения питания напрямую или косвенно. Например, если EvtDeviceArmWakeFromS0 ожидание обратного вызова в другом потоке, который вызывает WdfDeviceStopIdle(TRUE), переход питания блокируется и система завершает работу.

Драйвер не вызывать WdfDeviceStopIdle при простое устройства, а платформа помещает запрос ввода-вывода в очередь ввода-вывода устройства, управляемого питанием. Кроме того, драйверу не нужно вызывать WdfDeviceStopIdle при простое устройства и обнаруживает сигнал пробуждения. В обоих случаях платформа запрашивает драйвер шины восстановить состояние питания устройства до D0.

Хотя драйверам обычно не нужно вызывать WdfDeviceStopIdle при обработке запросов ввода-вывода, получаемых из очереди ввода-вывода, управляемого питанием, разрешен вызов. Однако драйверы не должны задавать параметру WaitForD0 значение TRUE при обработке запросов ввода-вывода из очереди ввода-вывода, управляемого питанием.

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

Вызов WdfDeviceStopIdle заставляет устройство работать (D0), если система находится в состоянии работы (S0). Устройство остается в рабочем состоянии, пока драйвер не вызовет WdfDeviceResumeIdle, в то время как платформа может поместить устройство в состояние низкой мощности, если оно остается бездействующей.

Не вызывайте WdfDeviceStopIdle, прежде чем платформа впервые вызвала функцию обратного вызова драйвера EvtDeviceDeviceD0Entry обратного вызова.

Вызов WdfDeviceStopIdle может восстановить неактивное устройство до рабочего состояния, только если система находится в состоянии работы (S0). Если система переходит в состояние низкой мощности или устройство уже подключено в ответ на Sx (где x > 0), когда драйвер вызывает WdfDeviceStopIdle с параметром WaitForD0 значение TRUE, функция не возвращается, пока система не возвращает состояние S0. Аналогичным образом, если устройство поддерживает управление питанием, а подсистема питания инициировала перенаправленное питание, вызов WdfDeviceStopIdle с параметром WaitForD0, равным TRUE, не возвращается, пока подсистема питания не направила устройство на резервное копирование.

Каждый успешный вызов WdfDeviceStopIdle должен в конечном итоге следовать вызову WdfDeviceResumeIdle, или другое устройство никогда не вернется в состояние низкой мощности, если он снова становится бездействуемым. Вызовы WdfDeviceStopIdle могут быть вложены, поэтому количество вызовов для WdfDeviceResumeIdle должно равно количеству вызовов WdfDeviceStopIdle. Не вызывайте WdfDeviceResumeIdle, если вызов WdfDeviceStopIdle завершается ошибкой.

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

Дополнительные сведения см. в поддержкебездействия.

Если WaitForD0TRUE, необходимо вызвать WdfDeviceStopIdle в IRQL = PASSIVE_LEVEL. Если WaitForD0FALSE, этот метод должен вызываться в IRQL <= DISPATCH_LEVEL.

Вызов WdfDeviceStopIdleWithTag вместо WdfDeviceStopIdle предоставляет дополнительные сведения (значение тега, номер строки и имя файла), которые можно просмотреть в отладчиках Майкрософт.

Примеры

В следующем примере кода WdfDeviceStopIdle возвращается после ввода состояния питания устройства D0.

NTSTATUS  status;

status = WdfDeviceStopIdle(Device, TRUE);

Требования

Требование	Ценность
целевая платформа	универсальный
минимальная версия KMDF	1.0
минимальная версия UMDF	2.0
Заголовок	wdfdevice.h (include Wdf.h)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	См. раздел "Примечания".
правил соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

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