Funzione PoFxActivateComponent (wdm.h)

Articolo
08/08/2023

La routine PoFxActivateComponent incrementa il conteggio dei riferimenti di attivazione nel componente specificato.

Sintassi

void PoFxActivateComponent(
  [in] POHANDLE Handle,
  [in] ULONG    Component,
  [in] ULONG    Flags
);

Parametri

[in] Handle

Handle che rappresenta la registrazione del dispositivo con il framework di risparmio energia (PoFx). Il driver di dispositivo ha ricevuto in precedenza questo handle dalla routine PoFxRegisterDevice .

[in] Component

Indice che identifica il componente. Questo parametro è un indice nella matrice Components nella struttura PO_FX_DEVICE usata dal driver di dispositivo per registrare il dispositivo con PoFx. Se la matrice Components contiene N elementi, gli indici dei componenti sono compresi tra 0 e N-1.

[in] Flags

Flag per l'operazione di attivazione. Impostare questo membro su zero o su uno dei flag seguenti PO_FX_FLAG_XXX bit:

Questi due bit di flag si escludono a vicenda. Per altre informazioni, vedere la sezione Osservazioni.

Valore	Significato
PO_FX_FLAG_BLOCKING 0x1	Apportare la modifica sincrona della condizione. Se questo flag è impostato, la routine che richiede la modifica della condizione non restituisce il controllo al driver chiamante finché l'hardware del componente non completa la transizione alla nuova condizione. Questo flag può essere usato solo se il chiamante è in esecuzione in IRQL < DISPATCH_LEVEL.
PO_FX_FLAG_ASYNC_ONLY 0x2	Apportare la modifica della condizione completamente asincrona. Se questo flag è impostato, la routine di callback del driver chiamante viene chiamata da un thread diverso dal thread in cui viene chiamata la routine che richiede la modifica della condizione. Pertanto, la routine che richiede la modifica della condizione restituisce sempre in modo asincrono senza attendere il completamento del callback.

Valore

Significato

PO_FX_FLAG_BLOCKING
0x1

Apportare la modifica sincrona della condizione. Se questo flag è impostato, la routine che richiede la modifica della condizione non restituisce il controllo al driver chiamante finché l'hardware del componente non completa la transizione alla nuova condizione. Questo flag può essere usato solo se il chiamante è in esecuzione in IRQL < DISPATCH_LEVEL.

PO_FX_FLAG_ASYNC_ONLY
0x2

Apportare la modifica della condizione completamente asincrona. Se questo flag è impostato, la routine di callback del driver chiamante viene chiamata da un thread diverso dal thread in cui viene chiamata la routine che richiede la modifica della condizione. Pertanto, la routine che richiede la modifica della condizione restituisce sempre in modo asincrono senza attendere il completamento del callback.

Valore restituito

nessuno

Osservazioni

Prima che un driver di dispositivo possa accedere a un componente in un dispositivo, il driver deve prima chiamare PoFxActivateComponent per ottenere un riferimento di attivazione al componente. Se il componente non è già presente nella condizione attiva, questa chiamata avvia una transizione dalla condizione di inattività alla condizione attiva. Al termine di questa transizione, PoFx chiama la routine ComponentActiveConditionCallback del driver per notificare al driver. Il driver può accedere ai registri hardware in un componente solo quando il componente si trova nella condizione attiva.

Se il componente si trova già nella condizione attiva quando viene chiamato PoFxActivateComponent , non è necessaria alcuna transizione e la routine ComponentActiveConditionCallback non viene chiamata.

Dopo che un componente entra nella condizione attiva, rimane nella condizione attiva finché il driver contiene uno o più riferimenti di attivazione nel componente. Per rilasciare un riferimento di attivazione, il driver chiama la routine PoFxIdleComponent . Quando il driver rilascia l'ultimo riferimento di attivazione in un componente, PoFxIdleComponent avvia una transizione dalla condizione attiva alla condizione di inattività. Un componente che si trova nella condizione di inattività può potenzialmente entrare in uno stato fx a basso consumo.

Se Flags = PO_FX_FLAG_BLOCKING, la chiamata PoFxActivateComponent è sincrona. Se il componente è già presente nella condizione attiva, la chiamata incrementa il conteggio dei riferimenti di attivazione e restituisce senza attendere. In caso contrario, PoFxActivateComponent attende il ritorno fino al completamento della transizione alla condizione attiva. In questo caso, se il componente non è già nello stato F0 quando si verifica la chiamata, PoFxActivateComponent chiama la routine ComponentIdleStateCallback del driver per avviare la transizione a F0. Dopo che il componente entra nello stato F0, PoFxActivateComponent chiama la routine ComponentActiveConditionCallback del driver per informare il driver che il componente si trova nella condizione attiva. Questi callback si verificano nello stesso thread della chiamata a PoFxActivateComponent e PoFxActivateComponent restituisce solo dopo la restituzione del callback ComponentActiveConditionCallback .

Se Flags = PO_FX_FLAG_ASYNC_ONLY, la chiamata PoFxActivateComponent è asincrona. Se il componente è già presente nella condizione attiva, la chiamata incrementa il conteggio dei riferimenti di attivazione e restituisce. In caso contrario, PoFxActivateComponent pianifica i callback ComponentIdleStateCallback (se necessario) e ComponentActiveConditionCallback in un altro thread e quindi restituisce senza attendere che si verifichi alcun callback. I callback possono verificarsi prima o dopo la restituzione di PoFxActivateComponent . Il driver si basa sul callback ComponentActiveConditionCallback per determinare quando il componente completa la transizione alla condizione attiva.

Il driver può impostare Flags = 0 per indicare che non è importante se la chiamata PoFxActivateComponent è sincrona o asincrona. In questo caso, PoFx decide se effettuare la chiamata sincrona o asincrona.

Due o più percorsi di codice nello stesso driver potrebbero dover accedere simultaneamente a un determinato componente. Le routine PoFxActivateComponent e PoFxIdleComponent usano i conteggi dei riferimenti di attivazione per consentire alle varie parti del driver di mantenere in modo indipendente l'accesso al componente senza richiedere al driver di gestire centralmente l'accesso al componente.

PoFx gestisce un conteggio dei riferimenti di attivazione per ogni componente in un dispositivo. Una chiamata PoFxActivateComponent incrementa il conteggio di uno e una chiamata PoFxIdleComponent decrementa il conteggio di uno. Quando il conteggio è diverso da zero, il componente si trova nella condizione attiva o si trova nel processo di passaggio alla condizione attiva. Un componente con un conteggio pari a zero si trova nella condizione di inattività o è in fase di passaggio alla condizione di inattività.

Quando una chiamata PoFxActivateComponent fa aumentare il conteggio dei riferimenti di attivazione da 0 a 1, PoFxActivateComponent avvia una transizione dalla condizione di inattività alla condizione attiva. Quando una chiamata PoFxIdleComponent determina il decremento del conteggio da 1 a 0, PoFxIdleComponent avvia una transizione dalla condizione attiva alla condizione inattiva.

PoFx notifica al driver quando si verifica una transizione tra la condizione attiva e la condizione di inattività. Un callback ComponentActiveConditionCallback notifica al driver di una transizione alla condizione attiva e un callback ComponentIdleConditionCallback notifica al driver di una transizione alla condizione di inattività. Quando una chiamata PoFxActivateComponent o PoFxIdleComponent semplicemente incrementa o decrementa il conteggio dei riferimenti di attivazione senza causare tale transizione, il driver non riceve alcuna notifica.

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	<= DISPATCH_LEVEL