GET_IDLE_WAKE_INFO funzione di callback (wdm.h)

Articolo
02/27/2024

La routine GetIdleWakeInfo consente al driver di individuare gli stati di alimentazione del dispositivo da cui il dispositivo può segnalare un evento di riattivazione.

Sintassi

GET_IDLE_WAKE_INFO GetIdleWakeInfo;

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

Parametri

[in, optional] Context

Puntatore a informazioni di contesto specifiche dell'interfaccia. Il chiamante imposta questo parametro sul valore del membro Context della struttura D3COLD_SUPPORT_INTERFACE per l'interfaccia.

[in] SystemPowerState

Stato di alimentazione del sistema. Impostare questo parametro su uno dei valori di enumerazione seguenti SYSTEM_POWER_STATE :

PowerSystemWorking
PowerSystemSleeping1
PowerSystemSleeping2
PowerSystemSleeping3
PowerSystemHibernate

Questi valori rappresentano gli stati di alimentazione del sistema S0 (stato di lavoro del sistema) tramite S4. Per il valore SystemPowerState fornito dal chiamante, la routine determina lo stato di alimentazione del dispositivo più profondo da cui il dispositivo può emettere un segnale di riattivazione.

[out] DeepestWakeableDstate

Stato dx riattivabile più profondo. Questo parametro è un puntatore a una variabile DEVICE_WAKE_DEPTH . Se la chiamata ha esito positivo, la routine scrive uno dei valori di enumerazione seguenti in questa variabile:

DeviceWakeDepthNotWakeable
DeviceWakeDepthD0
DeviceWakeDepthD1
DeviceWakeDepthD2
DeviceWakeDepthD3hot
DeviceWakeDepthD3cold

Un valore nell'intervallo DeviceWakeDepthD0 su DeviceWakeDepthD3cold indica lo stato Dx con potenza più bassa da cui il dispositivo può inviare un segnale di riattivazione quando il computer si trova nello stato di alimentazione del sistema specificato dal parametro SystemPowerState . DeviceWakeDepthNotWakeable indica che non esiste alcun stato di alimentazione del dispositivo da cui il dispositivo può inviare un segnale di riattivazione quando il computer si trova nello stato di alimentazione del sistema specificato da SystemPowerState.

Se la routine non riesce a determinare lo stato del dispositivo riattivabile più profondo (forse perché il firmware della piattaforma non contiene queste informazioni), la chiamata ha esito negativo e la routine restituisce un codice di stato di errore. Se una chiamata GetIdleWakeInfo ha esito negativo per qualsiasi valore di parametro SystemPowerState nell'intervallo PowerSystemWorking in PowerSystemHibernate, avrà esito negativo per tutti questi valori.

Valore restituito

La routine GetIdleWakeInfo restituisce STATUS_SUCCESS se recupera correttamente lo stato del dispositivo riattivabile più profondo. In caso contrario, restituisce un codice di stato di errore appropriato.

Commenti

Per lo stato di alimentazione del sistema specificato dal chiamante, questa routine tenta di determinare lo stato di alimentazione del dispositivo più basso da cui il dispositivo può segnalare un evento di riattivazione al processore. In caso di esito positivo, la routine scrive lo stato di alimentazione del dispositivo nella posizione a cui punta il parametro DeepestWakeableDstate e restituisce STATUS_SUCCESS. In alternativa, se la routine determina che il dispositivo non può segnalare un evento di riattivazione da qualsiasi stato di alimentazione del dispositivo, la routine scrive il valore DeviceWakeDepthNotWakeable in questa posizione e restituisce STATUS_SUCCESS.

Il driver per un dispositivo usa le informazioni fornite dalla routine GetIdleWakeInfo per determinare le condizioni in cui il dispositivo può segnalare un evento di riattivazione. Un dispositivo che deve essere in grado di segnalare determinati eventi di riattivazione non deve immettere uno stato di alimentazione del dispositivo da cui non può segnalare questi eventi. Per alcuni tipi di dispositivi, il segnale di riattivazione indica che il dispositivo deve inviare quando il computer si trova nello stato di alimentazione del sistema S0 (funzionante) differisce da quelli che il dispositivo deve inviare quando il computer sembra essere disattivato.

Ad esempio, quando una scheda viene inserita in uno slot della scheda PCI Express e il dispositivo controller di plug-plug pci Express per lo slot si trova nello stato di alimentazione del dispositivo D0, questo dispositivo segnala un interruzione al processore. Tuttavia, se il dispositivo controller è in uno stato Dx a bassa potenza quando la scheda viene inserita, lo stato di alimentazione del sistema del computer potrebbe determinare se questo dispositivo deve segnalare un evento di riattivazione al processore. Idealmente, il dispositivo controller deve comportarsi come segue:

Se il computer si trova nello stato di alimentazione del sistema S0 (funzionante), il dispositivo deve segnalare un evento di riattivazione al processore.
Se il computer è inattiva (in uno stato Sx a bassa potenza), il dispositivo non deve segnalare un evento di riattivazione.

Alcuni dispositivi meno recenti potrebbero non supportare questo comportamento ideale. Se in questo esempio il dispositivo controller con plug-hot-plug PCI Express può segnalare un evento di riattivazione solo quando il computer si trova nello stato S3, il driver (che, in questo caso, è la casella di posta in arrivo Pci.sys driver) per il controller deve mantenere il controller in D0 quando il computer è in S0 (e non si prepara a immettere uno stato di sospensione).

Il driver in questo esempio può chiamare la routine GetIdleWakeInfo per determinare se il dispositivo controller plug-hot deve lasciare lo stato D0 mentre il computer è in S0. Per questa chiamata, il driver imposta SystemPowerState = PowerSystemWorking. Questo dispositivo non deve lasciare lo stato D0 (quando il computer è in S0) in uno dei casi seguenti:

La chiamata GetIdleWakeInfo imposta il parametro di output su DeviceWakeDepthNotWakeable o DeviceWakeDepthD0 e restituisce STATUS_SUCCESS.
La chiamata GetIdleWakeInfo ha esito negativo e restituisce un codice di stato di errore.

Il driver deve interpretare uno di questi risultati per indicare che il dispositivo non può segnalare un evento di riattivazione quando il computer è in S0. In base a queste informazioni, il driver deve mantenere il dispositivo in D0 finché il computer non prepara l'uscita da S0.

I driver per la maggior parte dei dispositivi possono trattare un valore di output di DeviceWakeDepthD0 uguale a DeviceWakeDepthNotWakeable. Solo alcuni driver potrebbero avere un motivo per armere un segnale di riattivazione quando i loro dispositivi sono in D0. Questi sono i driver per i dispositivi semplici che monitorano gli eventi esterni che attivano segnali di riattivazione indipendentemente dal fatto che i dispositivi si trovino in stati D0 o dx a bassa potenza. Un esempio di tale dispositivo è un pulsante di alimentazione o un pulsante di sospensione in un computer.

La routine GetIdleWakeInfo esegue una query sul firmware del driver del bus sottostante e del firmware del sistema ACPI per determinare lo stato di alimentazione del dispositivo più basso da cui il dispositivo può segnalare un evento di riattivazione. Se il driver del bus e il firmware non possono fornire queste informazioni, la routine ha esito negativo e restituisce un codice di stato di errore.

La struttura DEVICE_CAPABILITIES include un membro DeviceWake che fornisce informazioni simili a quella disponibile dalla routine GetIdleWakeInfo . Tuttavia, le informazioni nel membro DeviceWake si applicano solo agli stati di bassa potenza del sistema S1 a S4. Per alcuni dispositivi, le informazioni nel membro DeviceWake potrebbero essere applicate anche allo stato di alimentazione del sistema S0, ma i driver non devono basarsi su tale comportamento. Solo la routine GetIdleWakeInfo segnala in modo affidabile la possibilità di un dispositivo di segnalare un evento di riattivazione se il computer è in S0.

Viene fornita una funzione helper inline , MapWakeDepthToDstate, per convertire il valore di output DEVICE_WAKE_DEPTH dalla routine GetIdleWakeInfo a un valore DEVICE_POWER_STATE che può essere usato come parametro di input dalla routine PoRequestPowerIrp .

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows 8.
Piattaforma di destinazione	Desktop
Intestazione	wdm.h (include Wdm.h)
IRQL	PASSIVE_LEVEL