HW_MESSAGE_SIGNALED_INTERRUPT_ROUTINE função de retorno de chamada (storport.h)

Artigo
08/07/2023

A rotina HwMSInterruptRoutine manipula uma MSI (interrupção sinalizada por mensagem).

Sintaxe

HW_MESSAGE_SIGNALED_INTERRUPT_ROUTINE HwMessageSignaledInterruptRoutine;

BOOLEAN HwMessageSignaledInterruptRoutine(
  IN PVOID HwDeviceExtension,
  IN ULONG MessageId
)
{...}

Parâmetros

HwDeviceExtension

Um ponteiro para a extensão do dispositivo de hardware para o HBA (adaptador de barramento de host).

MessageId

O identificador da mensagem.

Retornar valor

HwMSInterruptRoutine retornará TRUE se determinar que o HBA gerou o MSI. Se o HBA não tiver gerado o MSI, HwMSInterruptRoutine retornará FALSE.

Comentários

A rotina HwMSInterruptRoutine de um driver de miniporta processa MSIs (interrupções sinalizadas por mensagem) geradas pelo HBA. Um driver de miniporta indica que seu HBA gera MSIs definindo o membro HwMSInterruptRoutine da estrutura PORT_CONFIGURATION_INFORMATION para apontar para a rotina HwMSInterruptRoutine . Se o HBA não gerar MSIs, um driver de miniporto deverá definir HwMSInterruptRoutine como NULL.

Se o membro InterruptSynchronizationMode da estrutura PORT_CONFIGURATION_INFORMATION estiver definido como InterruptSynchronizeAll, o driver storport sincronizará todas as MSIs originadas com o adaptador que gerencia ou os dispositivos conectados ao adaptador. Quando ocorre uma interrupção, o driver storport chama a rotina HwMSInterruptRoutine do driver de miniport no DIRQL depois de adquirir o bloqueio de rotação de interrupção.

Se o membro InterruptSynchronizationMode da estrutura PORT_CONFIGURATION_INFORMATION estiver definido como InterruptSynchronizePerMessage, o driver storport chamará a rotina HwMSInterruptRoutine do driver de miniporto em IRQL = DIRQL, mantendo o bloqueio de rotação de interrupção que corresponde ao identificador de mensagem (ID) indicado no parâmetro MessageID . O HBA pode interromper a rotina HwMSInterruptRoutine para interrupções para outras IDs de mensagem, portanto, o driver storport pode fazer chamadas aninhadas para HwMSInterruptRoutine ou executar instâncias diferentes de HwMSInterruptRoutine simultaneamente em processadores diferentes. Para sincronizar o acesso a dados confidenciais por diferentes instâncias do HwMSInterruptRoutine, o miniporto deve chamar as rotinas StorPortAcquireMSISpinLock e StorPortReleaseMSISpinLock para adquirir e liberar os bloqueios de rotação para IDs de mensagem diferentes da ID em MessageID.

Um driver de miniporto pode recuperar informações adicionais sobre a mensagem chamando a rotina StorPortGetMSIInfo .

Ele não deve chamar a rotina StorPortGetMSIInfo de dentro da rotina HwMSInterruptRoutine .

O nome HwMSInterruptRoutine é apenas um espaço reservado. O protótipo real para essa rotina é definido em Storport.h da seguinte maneira:

typedef
BOOLEAN
  HW_MESSAGE_SIGNALED_INTERRUPT_ROUTINE (
    _In_ PVOID  HwDeviceExtension,
    _In_ ULONG  MessageId
    );

Exemplos

Para definir uma função de retorno de chamada HwMSInterruptRoutine , primeiro você deve fornecer uma declaração de função que identifique o tipo de função de retorno de chamada que você está definindo. O Windows fornece um conjunto de tipos de função de retorno de chamada para drivers. Declarar uma função usando os tipos de função de retorno de chamada ajuda a Análise de Código para Drivers, SDV ( Verificador de Driver Estático ) e outras ferramentas de verificação a encontrar erros e é um requisito para escrever drivers para o sistema operacional Windows.

Por exemplo, para definir uma rotina de retorno de chamada HwMSInterruptRoutine chamada MyHwMSIRoutine, use o tipo HW_MESSAGE_SIGNALED_INTERRUPT_ROUTINE conforme mostrado neste exemplo de código:

HW_MESSAGE_SIGNALED_INTERRUPT_ROUTINE MyHwMSIRoutine;

Em seguida, implemente sua rotina de retorno de chamada da seguinte maneira:

_Use_decl_annotations_
BOOLEAN
MyHwMSIRoutine (
  _In_ PVOID  DeviceExtension,
  _In_ ULONG  MessageId
  );
  {
      ...
  }

O tipo de função HW_MESSAGE_SIGNALED_INTERRUPT_ROUTINE é definido no arquivo de cabeçalho Storport.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação Use_decl_annotations à sua definição de função. A anotação Use_decl_annotations garante que as anotações aplicadas ao tipo de função HW_MESSAGE_SIGNALED_INTERRUPT_ROUTINE no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função para drivers storport. Para obter informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.