struttura WDF_INTERRUPT_CONFIG (wdfinterrupt.h)

Articolo
02/27/2024

[Si applica a KMDF e UMDF]

La struttura WDF_INTERRUPT_CONFIG contiene informazioni di configurazione per un interrupt del dispositivo.

Sintassi

typedef struct _WDF_INTERRUPT_CONFIG {
  ULONG                           Size;
  WDFSPINLOCK                     SpinLock;
  WDF_TRI_STATE                   ShareVector;
  BOOLEAN                         FloatingSave;
  BOOLEAN                         AutomaticSerialization;
  PFN_WDF_INTERRUPT_ISR           EvtInterruptIsr;
  PFN_WDF_INTERRUPT_DPC           EvtInterruptDpc;
  PFN_WDF_INTERRUPT_ENABLE        EvtInterruptEnable;
  PFN_WDF_INTERRUPT_DISABLE       EvtInterruptDisable;
  PFN_WDF_INTERRUPT_WORKITEM      EvtInterruptWorkItem;
  PCM_PARTIAL_RESOURCE_DESCRIPTOR InterruptRaw;
  PCM_PARTIAL_RESOURCE_DESCRIPTOR InterruptTranslated;
  WDFWAITLOCK                     WaitLock;
  BOOLEAN                         PassiveHandling;
  WDF_TRI_STATE                   ReportInactiveOnPowerDown;
  BOOLEAN                         CanWakeDevice;
} WDF_INTERRUPT_CONFIG, *PWDF_INTERRUPT_CONFIG;

Members

Size

Dimensione, in byte, della struttura.

SpinLock

Handle per un oggetto spin-lock del framework, ottenuto da una chiamata precedente a WdfSpinLockCreate o NULL. Se questo parametro è NULL, il framework usa un oggetto spin-lock interno. Il framework acquisisce il blocco di rotazione prima di chiamare la funzione di callback dell'evento EvtInterruptSynchronize del driver e quando il driver chiama WdfInterruptAcquireLock. Per la gestione degli interrupt a livello passivo, impostare su NULL.

A partire dalla versione 2.0 di UMDF, UMDF usa sempre la gestione degli interrupt a livello passivo. In questo caso, impostare questo membro su NULL.

ShareVector

Valore tipizzato WDF_TRI_STATE. Se questo valore è WdfTrue, il vettore di interrupt può essere condiviso. Se il valore è WdfFalse, il vettore di interrupt non può essere condiviso. Se il valore è WdfDefault, il gestore PnP usa il valore del driver del bus.

FloatingSave

Valore booleano che, se TRUE, indica che il sistema salverà lo stato a virgola mobile e MMX del processore quando il dispositivo viene interrotto. Se FALSE, il sistema non salva lo stato a virgola mobile e MMX. Un driver deve impostare questo valore su TRUE solo se la relativa funzione di callback EvtInterruptIsr deve usare registri MMX o a virgola mobile. Per altre informazioni sul salvataggio dello stato a virgola mobile e MMX, vedere Uso di MMX o a virgola mobile in un driver WDM.

Questo membro viene ignorato a partire dalla versione 2.0 di UMDF.

AutomaticSerialization

Valore booleano che, se TRUE, indica che il framework sincronizza l'esecuzione dell'esecuzione della funzione di callback EvtInterruptDpc o EvtInterruptWorkItem dell'oggetto interrupt con funzioni di callback di altri oggetti sottostanti l'oggetto padre dell'interrupt. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

EvtInterruptIsr

Puntatore alla funzione di callback EvtInterruptIsr del driver. Questo puntatore non può essere NULL.

EvtInterruptDpc

Puntatore alla funzione di callback EvtInterruptDpc del driver o NULL. Il driver può fornire EvtInterruptWorkItem o EvtInterruptDpc, ma non entrambi.

EvtInterruptEnable

Puntatore alla funzione di callback EvtInterruptEnable del driver o NULL.

EvtInterruptDisable

Puntatore alla funzione di callback EvtInterruptDisable del driver o NULL.

EvtInterruptWorkItem

Puntatore alla funzione di callback EvtInterruptWorkItem del driver o NULL. Il driver può fornire EvtInterruptWorkItem o EvtInterruptDpc, ma non entrambi. Il membro EvtInterruptWorkItem è disponibile nella versione 1.11 e versioni successive di KMDF.

InterruptRaw

Puntatore alla struttura CM_PARTIAL_RESOURCE_DESCRIPTOR che descrive le risorse non elaborate assegnate dal sistema all'interrupt. Questo membro viene usato solo se l'interrupt viene creato nel callback EvtDevicePrepareHardware . Il membro InterruptRaw è disponibile nella versione 1.11 e successive di KMDF.

InterruptTranslated

Puntatore alla struttura CM_PARTIAL_RESOURCE_DESCRIPTOR che descrive le risorse tradotte assegnate dal sistema all'interrupt. Questo membro viene usato solo se l'interrupt viene creato nel callback EvtDevicePrepareHardware . Il membro InterruptTranslated è disponibile nella versione 1.11 e successive di KMDF.

WaitLock

Handle per un oggetto wait-lock del framework, ottenuto da una chiamata precedente a WdfWaitLockCreate o NULL. Se WaitLock è diverso da NULL, PassiveHandling deve essere impostato su TRUE. Il membro WaitLock è disponibile nella versione 1.11 e successive di KMDF. Per altre informazioni su WaitLock, vedere Osservazioni.

PassiveHandling

Impostare su FALSE per la gestione degli interrupt in IRQL (DIRQL) del dispositivo. Impostare su TRUE per la gestione degli interrupt a livello passivo. Il membro PassiveHandling è disponibile nella versione 1.11 e successive di KMDF. A partire da UMDF versione 2.0, WDF_INTERRUPT_CONFIG_INIT imposta sempre questo membro su TRUE.

ReportInactiveOnPowerDown

Questo membro si applica solo a KMDF.

Valore tipizzato WDF_TRI_STATE che si applica solo se il driver non ha chiamato WdfDeviceInitSetPowerNotPageable. Questo membro può avere uno dei valori seguenti:

WdfTrue - KMDF segnala l'interruzione inattiva quando il dispositivo passa a uno stato dx (low-power). Nei sistemi operativi precedenti a Windows 8, il comportamento del framework corrisponde a quello descritto per WdfFalse.

Nota Se CanWakeDevice è impostato su TRUE e ReportInactiveOnPowerDown è impostato su WdfTrue, il framework non segnala l'interruzione inattiva quando il dispositivo passa a uno stato a basso consumo.

WdfFalse : KMDF disconnette l'interruzione quando il dispositivo passa a uno stato dx (low-power).

WdfDefault : nelle piattaforme basate su ARM, il comportamento del framework corrisponde a quello descritto per WdfTrue. In altre piattaforme, il comportamento del framework corrisponde a quello descritto per WdfFalse.

Il membro ReportInactiveOnPowerDown è disponibile nella versione 1.11 e successive di KMDF. Non è disponibile in UMDF versione 2.0.

Per altre informazioni sulla segnalazione di un'interruzione inattiva, vedere Impostazione di un isr attivo o inattivo.

CanWakeDevice

Valore booleano che indica se l'interrupt viene usato per riattivare il dispositivo da uno stato a basso consumo. Se FALSE, l'interrupt non viene usato per riattivare il dispositivo. Se TRUE, l'interrupt viene usato per riattivare il dispositivo. Il membro CanWakeDevice è disponibile a partire da KMDF versione 1.13 e UMDF versione 2.0.

Commenti

La struttura WDF_INTERRUPT_CONFIG viene usata come input per WdfInterruptCreate.

Per inizializzare una struttura di WDF_INTERRUPT_CONFIG , il driver deve prima chiamare WDF_INTERRUPT_CONFIG_INIT e quindi compilare i membri della struttura che WDF_INTERRUPT_CONFIG_INIT non inizializza.

Se AutomaticSerialization è TRUE, si applicano le regole seguenti:

Se il livello di esecuzione dell'oggetto padre dell'interrupt è WdfExecutionLevelPassive, il driver può fornire EvtInterruptWorkItem, ma non deve fornire EvtInterruptDpc in questa struttura di configurazione.
Se il livello di esecuzione dell'oggetto padre dell'interrupt è WdfExecutionLevelDispatch, il driver può fornire EvtInterruptDpc, ma non deve fornire EvtInterruptWorkItem in questa struttura di configurazione. In questo secondo caso, l'oggetto interrupt stesso può comunque essere passivo.

Il driver può usare il membro WaitLock di questa struttura per fornire il proprio blocco di interrupt per la gestione degli interrupt a livello passivo. Se il driver imposta PassiveHandling su TRUE ma non fornisce waitLock, il framework crea internamente un blocco di interrupt. Il framework acquisisce il blocco di interrupt a livello passivo prima di chiamare le funzioni di callback seguenti:

EvtInterruptEnable

EvtInterruptDisable

EvtInterruptSynchronize

EvtInterruptIsr

Per altre informazioni su AutomaticSerialization e la sincronizzazione delle funzioni di callback dei driver, vedere Tecniche di sincronizzazione per i driver Framework-Based.

Per impostazione predefinita, i driver di funzione KMDF sono impaginabili. Un driver chiama WdfDeviceInitSetPowerNotPageable per specificare che è non power pageable.

Nelle versioni kmDF precedenti alla 1.11, il framework disconnette sempre le interruzioni dei driver di alimentazione impaginabili quando il dispositivo passa a uno stato dx (low-power). A partire da KMDF versione 1.11, è possibile modificare questo comportamento impostando il membro ReportInactiveOnPowerDown di questa struttura. Per i driver non impaginabili, le interruzioni rimangono connesse quando si verificano transizioni di stato Dx, indipendentemente dal valore impostato in ReportInactiveOnPowerDown.

Se un driver UMDF imposta ReportInactiveOnPowerDown, il valore viene ignorato.

Per altre informazioni sulla gestione degli interrupt nei driver basati su framework, vedere Gestione degli interrupt hardware.

Il driver può usare il membro CanWakeDevice di questa struttura per creare un interrupt che può essere usato per riportare il dispositivo da uno stato Dx a basso consumo a D0. La routine di callback EvtInterruptIsr del driver è pianificata per l'esecuzione in IRQL = PASSIVE_LEVEL dopo che il dispositivo entra in D0.

Per altre informazioni, vedere Uso di un'interruzione per riattivare un dispositivo.