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

Artigo
03/01/2024

A rotina HwStorAdapterControl de um driver de miniport é chamada para executar operações síncronas para controlar o estado ou o comportamento de um adaptador, como parar ou reiniciar o HBA (adaptador de barramento de host) para gerenciamento de energia.

Sintaxe

HW_ADAPTER_CONTROL HwAdapterControl;

SCSI_ADAPTER_CONTROL_STATUS HwAdapterControl(
  [in] PVOID DeviceExtension,
  [in] SCSI_ADAPTER_CONTROL_TYPE ControlType,
  [in] PVOID Parameters
)
{...}

Parâmetros

[in] DeviceExtension

Um ponteiro para a área de armazenamento por HBA do driver de miniport.

[in] ControlType

Um valor SCSI_ADAPTER_CONTROL_TYPE que especifica uma operação de controle de adaptador, em que cada tipo de controle inicia uma ação pelo driver de miniport. Consulte SCSI_ADAPTER_CONTROL_TYPE para obter detalhes.

[in] Parameters

Ponteiro para uma estrutura ou valor que contém informações relacionadas ao ControlType ou NULL se o tipo de controle não usar uma estrutura. Todas as estruturas são alocadas pelo chamador. Consulte SCSI_ADAPTER_CONTROL_TYPE para obter detalhes.

Retornar valor

Dependendo do tipo de controle, HwStorAdapterControl retorna um dos seguintes valores de SCSI_ADAPTER_CONTROL_STATUS:

Código de retorno	Descrição
ScsiAdapterControlSuccess	O driver de miniporte concluiu a operação solicitada com êxito. Atualmente, HwStorAdapterControl deve retornar esse valor para todos os tipos de controle.
ScsiAdapterControlUnsuccessful	A operação de controle do adaptador não foi bem-sucedida.

Comentários

HwStorAdapterControl é uma função necessária.

O Storport chama hwStorAdapterControl de um miniport com um tipo de controle ScsiQuerySupportedControlTypes depois que o HBA foi inicializado, mas antes da primeira E/S. O driver de miniporto preenche a estrutura SCSI_SUPPORTED_CONTROL_TYPE_LIST em Parâmetros com as operações compatíveis. Depois que HwStorAdapterControl retornar dessa chamada, o driver storport chamará o retorno de chamada HwStorAdapterControl do driver de miniport para operações com suporte no miniporto.

Como os drivers de miniport que funcionam com o driver Storport devem dar suporte a Plug and Play (PnP), os miniportos devem dar suporte aos tipos de controle ScsiStopAdapter e ScsiRestartAdapter.

A tabela a seguir lista o IRQL atual e o spinlock adquiridos quando o tipo de controle é emitido.

Tipo de controle	IRQL	Bloqueio de rotação
ScsiQuerySupportedControlTypes	PASSIVE_LEVEL	Nenhum
ScsiStopAdapter	DIRQL	InterruptLock
ScsiRestartAdapter	DIRQL	InterruptLock
ScsiSetBootConfig	PASSIVE_LEVEL	Nenhum
ScsiSetRunningConfig	PASSIVE_LEVEL	Nenhum
ScsiPowerSettingNotification	PASSIVE_LEVEL	Nenhum
ScsiAdapterPower	<= DISPATCH_LEVEL	Nenhum
ScsiAdapterPoFxPowerRequired	<= DISPATCH_LEVEL	Nenhum
ScsiAdapterPoFxPowerActive	<= DISPATCH_LEVEL	Nenhum
ScsiAdapterPoFxPowerSetFState	<= DISPATCH_LEVEL	Nenhum
ScsiAdapterPoFxPowerControl	<= DISPATCH_LEVEL	Nenhum
ScsiAdapterPrepareForBusReScan	PASSIVE_LEVEL	Nenhum
ScsiAdapterSystemPowerHints	PASSIVE_LEVEL	Nenhum
ScsiAdapterFilterResourceRequirements	< DISPATCH_LEVEL	Nenhum
ScsiAdapterPoFxMaxOperationalPower	PASSIVE_LEVEL	Nenhum
ScsiAdapterPoFxSetPerfState	<= DISPATCH_LEVEL	Nenhum
ScsiAdapterSurpriseRemoval	< DISPATCH_LEVEL	Nenhum
ScsiAdapterSerialNumber	< DISPATCH_LEVEL	Nenhum
ScsiAdapterCryptoOperation	PASSIVE_LEVEL	Nenhum
ScsiAdapterQueryFruId	PASSIVE_LEVEL	Nenhum
ScsiAdapterSetEventLogging	PASSIVE_LEVEL	Nenhum

O nome HwStorAdapterControl é apenas um espaço reservado. O protótipo real dessa rotina é definido em storport.h da seguinte maneira:

typedef
SCSI_ADAPTER_CONTROL_STATUS
HW_ADAPTER_CONTROL (
  _In_ PVOID  DeviceExtension,
  _In_ SCSI_ADAPTER_CONTROL_TYPE  ControlType,
  _In_ PVOID  Parameters
  );

Exemplos

Para definir uma função de retorno de chamada HwStorAdapterControl , 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 gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma rotina de retorno de chamada HwStorAdapterControl chamada MyHwAdapterControl, use o tipo HW_ADAPTER_CONTROL conforme mostrado neste exemplo de código:

HW_ADAPTER_CONTROL MyHwAdapterControl;

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

_Use_decl_annotations_
SCSI_ADAPTER_CONTROL_STATUS
MyHwAdapterControl (
  _In_ PVOID  DeviceExtension,
  _In_ SCSI_ADAPTER_CONTROL_TYPE  ControlType,
  _In_ PVOID  Parameters
  );
  {
      ...
  }

O tipo de função HW_ADAPTER_CONTROL é 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_ADAPTER_CONTROL 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.