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

Статья
02/29/2024

[Относится к KMDF и UMDF]

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

Синтаксис

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

Параметры

[in] Device

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

[in] WaitForD0

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

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

None

Remarks

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

Возвращаемое значение	Значение
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 до того, как платформа впервые вызовет функцию обратного вызова EvtDeviceD0Entry драйвера.

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

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

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

Дополнительные сведения см. в разделе Поддержка выключения в режиме простоя.

Если параметр WaitForD0 имеет значение TRUE, необходимо вызвать WdfDeviceStopIdle по адресу IRQL = PASSIVE_LEVEL. Если waitForD0 имеет значение FALSE, этот метод должен вызываться по адресу IRQL <= DISPATCH_LEVEL.

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

Примеры

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

NTSTATUS  status;

status = WdfDeviceStopIdle(Device, TRUE);

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Минимальная версия UMDF	2,0
Верхняя часть	wdfdevice.h (включая Wdf.h)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	См. раздел "Примечания".
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

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