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 de 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.
Valor de retorno
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 as chamadas de rotina de retorno de chamada EVT_WDF_DEVICE_PREPARE_HARDWARE do driver WdfInterruptCreate com o InterruptRaw e membros 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 deNULL não 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 ParentObject membro 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 ao Windows 8. |
Para obter uma lista de outros valores retornados que o método WdfInterruptCreate pode retornar, consulte Framework Object Creation Errors.
Esse método também pode retornar outros valores NTSTATUS .
Uma verificação de bug ocorre se o driver fornece um identificador de objeto inválido.
Observações
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, ambos deverão ser válidos.
Se você estiver criando um objeto de interrupção capaz de ativar, conforme descrito em Usando uma interrupção para ativar um dispositivo, você deverá chamar WdfInterruptCreate de EvtDevicePrepareHardware.
O 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 criados pelo driver. (Os drivers que não dão suporte ao 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 versão 1.9 da estrutura e anteriores, o pai de cada objeto de interrupção é o objeto do 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 EvtCleanupCallback ou EvtDestroyCallback funções de retorno de chamada 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 Tratando 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 |
|---|---|
| da 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) |