Funzione PoFxRegisterDevice (wdm.h)

Articolo
08/08/2023

La routine PoFxRegisterDevice registra un dispositivo con il framework di risparmio energia (PoFx).

Sintassi

NTSTATUS PoFxRegisterDevice(
  [in]  PDEVICE_OBJECT Pdo,
  [in]  PPO_FX_DEVICE  Device,
  [out] POHANDLE       *Handle
);

Parametri

[in] Pdo

Puntatore a un oggetto dispositivo fisico (PDO). Questo parametro punta a una struttura DEVICE_OBJECT che rappresenta il dispositivo fisico registrato. Il chiamante è il proprietario del criterio di alimentazione per il dispositivo, che è in genere il driver di funzione del dispositivo.

[in] Device

Puntatore a una struttura PO_FX_DEVICE allocata dal chiamante che contiene le informazioni di registrazione per il dispositivo. Questa struttura contiene puntatori a un set di routine di callback implementate dal driver di dispositivo. PoFx chiama queste routine per comunicare con il driver.

[out] Handle

Puntatore a una posizione in cui la routine scrive un handle che rappresenta la registrazione del dispositivo con PoFx. Il driver del dispositivo passa questo handle come parametro di input alle altre routine PoFxXxx chiamate. Il driver deve prima chiamare PoFxRegisterDevice per registrare il dispositivo prima che il driver chiami qualsiasi altra routine PoFxXxx per gestire il dispositivo.

Valore restituito

PoFxRegisterDevice restituisce STATUS_SUCCESS se la routine registra correttamente il dispositivo. I valori restituiti degli errori possibili includono i codici di stato seguenti.

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Pdo è NULL; o la struttura PPO_FX_DEVICE ha un numero di versione non valido o un numero di componenti pari a zero; o il numero di stati inattive specificati per un componente è zero; o la descrizione di uno stato inattiva non è valida.
STATUS_DEVICE_NOT_READY	Il dispositivo non è pronto.
STATUS_INSUFFICIENT_RESOURCES	Sono disponibili risorse insufficienti per completare la registrazione.

Commenti

Un driver di dispositivo chiama in genere questa routine dal gestore della richiesta di IRP_MN_START_DEVICE del driver. Il driver non deve chiamare questa routine prima che il dispositivo riceva una richiesta di IRP_MN_START_DEVICE . Il dispositivo riceve la prima richiesta di IRP_MN_START_DEVICE quando il dispositivo viene avviato per la prima volta. Il dispositivo riceve una richiesta di IRP_MN_START_DEVICE aggiuntiva ogni volta che il dispositivo viene riavviato dopo essere stato arrestato per il bilanciamento delle risorse. Una chiamata PoFxRegisterDevice per registrare un dispositivo già registrato è un errore irreversibile e causa un controllo di bug. Si noti che PoFx esegue una copia approfondita delle strutture del dispositivo nella memoria.

Prima che il driver chiami PoFxRegisterDevice, il dispositivo deve soddisfare le condizioni seguenti:

Il dispositivo (ovvero il PDO) non è già registrato con PoFx.
Il dispositivo si trova nello stato di alimentazione D0 (completamente attivo).
Il dispositivo si trova nella condizione di esecuzione.
Ogni componente del dispositivo si trova nello stato di alimentazione F0 (completamente attivo).
Ogni componente si trova nella condizione attiva.

Registrando il dispositivo con PoFx, il driver presuppone la responsabilità di informare PoFx quando un componente viene usato attivamente e quando il componente è inattiva. Mentre il dispositivo è registrato, il driver deve chiamare la routine PoFxActivateComponent per ottenere l'accesso ai registri hardware di un componente e il driver deve chiamare la routine PoFxIdleComponent per notificare PoFx quando il driver non richiede più l'accesso al componente.

Dopo che un driver chiama PoFxRegisterDevice per registrare un dispositivo con PoFx, tutti i componenti del dispositivo sono completamente attivi e nella condizione attiva in modo che il driver possa completare l'inizializzazione dell'hardware. Per avviare il risparmio energia attivo, il driver deve chiamare la routine PoFxStartDevicePowerManagement .

Per impostazione predefinita, PoFxStartDevicePowerManagement passa tutti i componenti alla condizione inattiva. Se il driver richiede che un componente si trova nella condizione attiva immediatamente dopo l'avvio della gestione energia, il driver deve attivare esplicitamente il componente chiamando la routine PoFxActivateComponent e questa chiamata deve verificarsi dopo la chiamata PoFxRegisterDevice , ma prima della chiamata PoFxStartDevicePowerManagement .

In genere, il driver Kernel-Mode Driver Framework (KMDF) per un dispositivo a componente singolo non chiama PoFxRegisterDevice per registrare il dispositivo con PoFx. Invece, questo driver riceve un handle di registrazione PoFx quando kmDF chiama la funzione di callback del driver EvtDeviceWdmPostPoFxRegisterDevice . Per altre informazioni, vedere Supporto di più stati di alimentazione funzionale per i dispositivi Single-Component.

Per informazioni sul modo in cui il driver kmDF per un dispositivo a più componenti viene registrato con PoFx, vedere Supporto di più stati di alimentazione funzionale per i dispositivi Multiple-Component.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows 8.
Piattaforma di destinazione	Universale
Intestazione	wdm.h
Libreria	Ntoskrnl.lib
DLL	Ntoskrnl.exe
IRQL	PASSIVE_LEVEL