estrutura WDF_INTERRUPT_CONFIG (wdfinterrupt.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

A estrutura WDF_INTERRUPT_CONFIG contém informações de configuração para uma interrupção de dispositivo.

Sintaxe

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;

Membros

Size

O tamanho, em bytes, dessa estrutura.

SpinLock

O identificador para um objeto de spin-lock de estrutura, obtido por uma chamada anterior para WdfSpinLockCreate ou NULL. Se esse parâmetro for NULL, a estrutura usará um objeto de bloqueio de rotação interno. A estrutura adquire o bloqueio de rotação antes de chamar a função de retorno de chamada de evento EvtInterruptSynchronize do driver e quando o driver chama WdfInterruptAcquireLock. Para tratamento de interrupção de nível passivo, defina como NULL.

A partir do UMDF versão 2.0, o UMDF sempre usa o tratamento de interrupção de nível passivo. Nesse caso, defina esse membro como NULL.

ShareVector

Um valor do tipo WDF_TRI_STATE. Se esse valor for WdfTrue, o vetor de interrupção poderá ser compartilhado. Se o valor for WdfFalse, o vetor de interrupção não poderá ser compartilhado. Se o valor for WdfDefault, o gerenciador PnP usará o valor do driver de barramento.

FloatingSave

Um valor booliano que, se TRUE, indica que o sistema salvará o ponto flutuante e o estado MMX do processador quando o dispositivo for interrompido. Se FALSE, o sistema não salvará o ponto flutuante e o estado MMX. Um driver deve definir esse valor como TRUE somente se sua função de retorno de chamada EvtInterruptIsr precisar usar registros de ponto flutuante ou MMX. Para obter mais informações sobre como salvar o ponto flutuante e o estado MMX, consulte Usando Ponto Flutuante ou MMX em um Driver WDM.

Esse membro é ignorado a partir do UMDF versão 2.0.

AutomaticSerialization

Um valor booliano que, se TRUE, indica que a estrutura sincronizará a execução da função de retorno de chamada EvtInterruptDpc ou EvtInterruptWorkItem do objeto de interrupção com funções de retorno de chamada de outros objetos que estão sob o objeto pai da interrupção. Para obter mais informações, consulte a seção Comentários a seguir.

EvtInterruptIsr

Um ponteiro para a função de retorno de chamada EvtInterruptIsr do driver. Esse ponteiro não pode ser NULL.

EvtInterruptDpc

Um ponteiro para a função de retorno de chamada EvtInterruptDpc do driver ou NULL. O driver pode fornecer EvtInterruptWorkItem ou EvtInterruptDpc, mas não ambos.

EvtInterruptEnable

Um ponteiro para a função de retorno de chamada EvtInterruptEnable do driver ou NULL.

EvtInterruptDisable

Um ponteiro para a função de retorno de chamada EvtInterruptDisable do driver ou NULL.

EvtInterruptWorkItem

Um ponteiro para a função de retorno de chamada EvtInterruptWorkItem do driver ou NULL. O driver pode fornecer EvtInterruptWorkItem ou EvtInterruptDpc, mas não ambos. O membro EvtInterruptWorkItem está disponível na versão 1.11 e versões posteriores do KMDF.

InterruptRaw

Um ponteiro para a estrutura CM_PARTIAL_RESOURCE_DESCRIPTOR que descreve os recursos brutos atribuídos pelo sistema à interrupção. Esse membro só será usado se a interrupção for criada no retorno de chamada EvtDevicePrepareHardware . O membro InterruptRaw está disponível na versão 1.11 e versões posteriores do KMDF.

InterruptTranslated

Um ponteiro para a estrutura CM_PARTIAL_RESOURCE_DESCRIPTOR que descreve os recursos traduzidos que o sistema atribuiu à interrupção. Esse membro só será usado se a interrupção for criada no retorno de chamada EvtDevicePrepareHardware . O membro InterruptTranslated está disponível na versão 1.11 e versões posteriores do KMDF.

WaitLock

Um identificador para um objeto de bloqueio de espera da estrutura, obtido por uma chamada anterior para WdfWaitLockCreate ou NULL. Se WaitLock não for NULL, PassiveHandling deverá ser definido como TRUE. O membro WaitLock está disponível na versão 1.11 e versões posteriores do KMDF. Para obter mais informações sobre WaitLock, consulte Comentários.

PassiveHandling

Defina como FALSE para tratamento de interrupção no DIRQL (IRQL) do dispositivo. Defina como TRUE para tratamento de interrupção de nível passivo. O membro PassiveHandling está disponível na versão 1.11 e versões posteriores do KMDF. A partir do UMDF versão 2.0, WDF_INTERRUPT_CONFIG_INIT sempre define esse membro como TRUE.

ReportInactiveOnPowerDown

Esse membro se aplica somente ao KMDF.

Um valor do tipo WDF_TRI_STATE que se aplica somente se o driver não tiver chamado WdfDeviceInitSetPowerNotPageable. Esse membro pode ter um dos seguintes valores:

WdfTrue – KMDF relata a interrupção inativa quando o dispositivo faz a transição para um estado Dx (baixa potência). Em sistemas operacionais antes de Windows 8, o comportamento da estrutura corresponde ao descrito para WdfFalse.

Nota Se CanWakeDevice estiver definido como TRUE e ReportInactiveOnPowerDown estiver definido como WdfTrue, a estrutura não relatará a interrupção inativa quando o dispositivo fizer a transição para um estado de baixa potência.

WdfFalse – KMDF desconecta a interrupção quando o dispositivo faz a transição para um estado Dx (baixa potência).

WdfDefault - Em plataformas baseadas em ARM, o comportamento da estrutura corresponde ao descrito para WdfTrue. Em outras plataformas, o comportamento da estrutura corresponde ao descrito para WdfFalse.

O membro ReportInactiveOnPowerDown está disponível na versão 1.11 e versões posteriores do KMDF. Ele não está disponível na UMDF versão 2.0.

Para obter mais informações sobre como relatar uma interrupção inativa, consulte Tornando um ISR ativo ou inativo.

CanWakeDevice

Um valor booliano que indica se a interrupção é usada para ativar o dispositivo de um estado de baixa potência. Se FALSE, a interrupção não será usada para ativar o dispositivo. Se TRUE, a interrupção será usada para ativar o dispositivo. O membro CanWakeDevice está disponível a partir do KMDF versão 1.13 e UMDF versão 2.0.

Comentários

A estrutura WDF_INTERRUPT_CONFIG é usada como entrada para WdfInterruptCreate.

Para inicializar uma estrutura de WDF_INTERRUPT_CONFIG , o driver deve primeiro chamar WDF_INTERRUPT_CONFIG_INIT e, em seguida, preencher os membros da estrutura que WDF_INTERRUPT_CONFIG_INIT não inicializa.

Se AutomaticSerialization for TRUE, as seguintes regras se aplicarão:

Se o nível de execução do objeto pai da interrupção for WdfExecutionLevelPassive, o driver poderá fornecer EvtInterruptWorkItem, mas não deverá fornecer EvtInterruptDpc nessa estrutura de configuração.
Se o nível de execução do objeto pai da interrupção for WdfExecutionLevelDispatch, o driver poderá fornecer EvtInterruptDpc, mas não deverá fornecer EvtInterruptWorkItem nessa estrutura de configuração. Nesse segundo caso, o próprio objeto de interrupção ainda pode ser passivo.

O driver pode usar o membro WaitLock dessa estrutura para fornecer seu próprio bloqueio de interrupção para tratamento de interrupção de nível passivo. Se o driver definir PassiveHandling como TRUE, mas não fornecer um WaitLock, a estrutura criará um bloqueio de interrupção internamente. A estrutura adquire o bloqueio de interrupção de nível passivo antes de chamar as seguintes funções de retorno de chamada:

EvtInterruptEnable

EvtInterruptDisable

EvtInterruptSynchronize

EvtInterruptIsr

Para obter mais informações sobre a AutomaticSerialization e a sincronização de funções de retorno de chamada do driver, consulte Técnicas de sincronização para drivers de Framework-Based.

Por padrão, os drivers de função KMDF são pagináveis por energia. Um driver chama WdfDeviceInitSetPowerNotPageable para especificar que ele não é pageable de energia.

Em versões kmdf anteriores à 1.11, a estrutura sempre desconecta interrupções de drivers pagináveis de energia quando o dispositivo faz a transição para um estado Dx (baixa potência). A partir do KMDF versão 1.11, você pode alterar esse comportamento definindo o membro ReportInactiveOnPowerDown dessa estrutura. Para drivers pagináveis não ligados à energia, as interrupções permanecem conectadas quando ocorrem transições de estado Dx, independentemente do valor definido em ReportInactiveOnPowerDown.

Se um driver UMDF definir ReportInactiveOnPowerDown, o valor será ignorado.

Para obter mais informações sobre como lidar com interrupções em drivers baseados em estrutura, consulte Tratamento de interrupções de hardware.

O driver pode usar o membro CanWakeDevice dessa estrutura para criar uma interrupção que pode ser usada para trazer o dispositivo de um estado Dx de baixa potência de volta para D0. A rotina de retorno de chamada EvtInterruptIsr do driver está agendada para ser executada em IRQL = PASSIVE_LEVEL após o dispositivo entrar em D0.

Para obter mais informações, consulte Usando uma interrupção para ativar um dispositivo.