Função WdfInterruptCreate (wdfinterrupt.h)
[Aplica-se a KMDF e UMDF]
O método WdfInterruptCreate cria um objeto de interrupção de estrutura.
Sintaxe
NTSTATUS WdfInterruptCreate(
[in] WDFDEVICE Device,
[in] PWDF_INTERRUPT_CONFIG Configuration,
[in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
[out] WDFINTERRUPT *Interrupt
);
Parâmetros
[in] Device
Um identificador para um objeto de dispositivo de estrutura.
[in] Configuration
Um ponteiro para uma estrutura WDF_INTERRUPT_CONFIG que foi inicializada por uma chamada para WDF_INTERRUPT_CONFIG_INIT.
[in, optional] Attributes
Um ponteiro para uma estrutura WDF_OBJECT_ATTRIBUTES que especifica atributos de objeto para o objeto de interrupção da estrutura. (Consulte Comentários para obter informações adicionais.) Esse parâmetro é opcional e pode ser WDF_NO_OBJECT_ATTRIBUTES.
[out] Interrupt
Um ponteiro para um local que recebe um identificador para o novo objeto de interrupção.
Retornar valor
WdfInterruptCreate retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método poderá retornar um dos valores a seguir.
| Código de retorno | Descrição |
|---|---|
|
O tamanho da estrutura de WDF_INTERRUPT_CONFIG está incorreto. |
|
Um parâmetro inválido foi especificado. |
|
WdfInterruptCreate foi chamado depois que o dispositivo foi iniciado. WdfInterruptCreate também retornará esse valor se a rotina de retorno de chamada EVT_WDF_DEVICE_PREPARE_HARDWARE do driver chamar WdfInterruptCreate com os membros InterruptRaw e InterruptTranslated da estrutura WDF_INTERRUPT_CONFIG definida como NULL. |
|
Não havia memória suficiente. |
|
No KMDF versão 1.9 ou anterior, o driver especificou um valor não NULL para o membro ParentObject da estrutura WDF_OBJECT_ATTRIBUTES .
No KMDF versão 1.11 ou posterior, o driver especificou um valor diferente de um dispositivo de estrutura ou fila para o membro ParentObject da estrutura WDF_OBJECT_ATTRIBUTES . |
|
O membro AutomaticSerialization da estrutura WDF_INTERRUPT_CONFIG é definido como TRUE e:
|
|
O driver solicitou tratamento de interrupção de nível passivo em uma plataforma anterior a Windows 8. |
Para obter uma lista de outros valores retornados que o método WdfInterruptCreate pode retornar, consulte Erros de criação de objeto da estrutura.
Esse método também pode retornar outros valores NTSTATUS.
Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.
Comentários
Os drivers normalmente chamam o método WdfInterruptCreate de uma função de retorno de chamada EvtDriverDeviceAdd . A partir do KMDF versão 1.11 e UMDF versão 2.0, os drivers podem chamar WdfInterruptCreate de EvtDevicePrepareHardware. Se o driver chamar WdfInterruptCreate de EvtDriverDeviceAdd, os membros InterruptRaw e InterruptTranslated da estrutura WDF_INTERRUPT_CONFIG deverão ser NULL. Se o driver chamar WdfInterruptCreate de EvtDevicePrepareHardware, esses membros deverão ser válidos.
Se você estiver criando um objeto de interrupção com capacidade de ativação, conforme descrito em Usando uma interrupção para ativar um dispositivo, você deverá chamar WdfInterruptCreate de EvtDevicePrepareHardware.
Seu driver deve chamar WdfInterruptCreate uma vez para cada vetor de interrupção exigido pelo dispositivo. Se o dispositivo der suporte a MSI (interrupções sinalizadas por mensagem), o driver deverá criar um objeto de interrupção para cada mensagem que o dispositivo possa dar suporte.
Depois que o gerenciador PnP atribui recursos do sistema ao dispositivo, a estrutura armazena informações sobre os recursos de interrupção atribuídos do dispositivo nos objetos de interrupção que o driver criou. (Drivers que não dão suporte a Plug and Play não podem usar objetos de interrupção.)
O sistema pode não atribuir todos os recursos de interrupção aos quais um dispositivo pode dar suporte. Por exemplo, um driver criaria oito objetos de interrupção para um dispositivo capaz de dar suporte a oito mensagens MSI. No entanto, o sistema pode atribuir apenas uma mensagem ao dispositivo. Nesse caso, sete dos objetos de interrupção não serão utilizados.
Normalmente, o driver deve armazenar informações específicas de interrupção, como o conteúdo copiado dos registros de interrupção do dispositivo, no espaço de contexto do objeto de interrupção. A estrutura WDF_OBJECT_ATTRIBUTES que o driver passa para WdfInterruptCreate deve descrever o espaço de contexto.
Para drivers que usam a estrutura versão 1.9 e anteriores, o pai de cada objeto de interrupção é o objeto de dispositivo ao qual a interrupção pertence. O driver não pode alterar esse pai e o membro ParentObject da estrutura WDF_OBJECT_ATTRIBUTES deve ser NULL. A partir da versão 1.11, ParentObject pode ser um objeto de dispositivo de estrutura ou objeto de fila. Se o driver especificar um pai, o driver deverá definir o membro AutomaticSerialization da estrutura de configuração como TRUE. O driver pode especificar um pai para interrupções em DIRQL e interrupções de nível passivo.
Se o driver fornecer funções de retorno de chamada EvtCleanupCallback ou EvtDestroyCallback para o objeto de interrupção da estrutura, observe que a estrutura chama essas funções de retorno de chamada em IRQL = PASSIVE_LEVEL.
Para obter mais informações sobre como lidar com interrupções em drivers baseados em estrutura, consulte Tratamento de interrupções de hardware.
Exemplos
O exemplo de código a seguir inicializa uma estrutura de WDF_INTERRUPT_CONFIG e uma estrutura WDF_OBJECT_ATTRIBUTES e, em seguida, chama WdfInterruptCreate.
NTSTATUS status;
WDF_INTERRUPT_CONFIG interruptConfig;
WDF_OBJECT_ATTRIBUTES interruptAttributes;
WDF_INTERRUPT_CONFIG_INIT(
&interruptConfig,
MyEvtInterruptIsr,
MyEvtInterruptDpc
);
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
&interruptAttributes,
INTERRUPT_DATA
);
status = WdfInterruptCreate(
device,
&interruptConfig,
&interruptAttributes,
&devExt->WdfInterrupt
);
Requisitos
| Requisito | Valor |
|---|---|
| Plataforma de Destino | Universal |
| Versão mínima do KMDF | 1.0 |
| Versão mínima do UMDF | 2,0 |
| Cabeçalho | wdfinterrupt.h (inclua Wdf.h) |
| Biblioteca | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| Regras de conformidade de DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |