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

Artigo
08/07/2023

A rotina HwStorFindAdapter usa a configuração fornecida para determinar se há suporte para um HBA específico e, se for, para retornar informações de configuração sobre esse adaptador.

Sintaxe

HW_FIND_ADAPTER HwFindAdapter;

ULONG HwFindAdapter(
           PVOID DeviceExtension,
  [in]     PVOID HwContext,
  [in]     PVOID BusInformation,
  [in]     PCHAR ArgumentString,
  [in/out] PPORT_CONFIGURATION_INFORMATION ConfigInfo,
  [in]     PBOOLEAN Reserved3
)
{...}

Parâmetros

DeviceExtension

Fornece uma área de armazenamento por adaptador.

[in] HwContext

Definido como NULL.

[in] BusInformation

Definido como NULL.

[in] ArgumentString

Fornece uma cadeia de caracteres terminada em NULL com informações de contexto sobre o driver.

[in/out] ConfigInfo

Fornece uma estrutura de PORT_CONFIGURATION_INFORMATION inicializada que o driver de miniporto usa durante a inicialização.

[in] Reserved3

Reservado para uso do sistema.

Retornar valor

HwStorFindAdapter deve retornar um dos seguintes valores de status:

Código de retorno	Descrição
SP_RETURN_FOUND	Indica que um HBA com suporte foi encontrado e que as informações de configuração relevantes do HBA foram determinadas e definidas com êxito na estrutura PORT_CONFIGURATION_INFORMATION .
SP_RETURN_ERROR	Indica que um HBA foi encontrado, mas houve um erro ao obter as informações de configuração. Se possível, esse erro deve ser registrado com StorPortLogError.
SP_RETURN_BAD_CONFIG	Indica que as informações de configuração fornecidas eram inválidas para o adaptador.
SP_RETURN_NOT_FOUND	Indica que nenhum HBA com suporte foi encontrado para as informações de configuração fornecidas.

Comentários

Como o driver storport dá suporte apenas a dispositivos PnP (Plug and Play), os parâmetros HwContext e BusInformation para HwStorFindAdapter não são fornecidos a drivers de miniporte não virtuais.

HwStorFindAdapter deve definir os campos MaximumTransferLength e NumberOfPhysicalBreaks na estrutura ConfigInfo . Além desses campos, a estrutura PORT_CONFIGURATION_INFORMATION sempre especificará totalmente todos os recursos do adaptador necessários para iniciar o adaptador.

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

typedef
ULONG
HW_FIND_ADAPTER (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_z_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _In_ PBOOLEAN  Reserved3
  );

Na maioria dos casos, o StorPort chama a rotina HwStorFindAdapter em IRQL == PASSIVE_LEVEL sem adquirir nenhum bloqueio de rotação. O caso de exceção ocorre quando o miniporto não dá suporte à chamada HwStorAdaptorControl com o tipo de controle ScsiRestartAdapter . Nessa situação, o StorPort reinicializará o adaptador chamando HwStorFindAdapter e HwStorInitialize. Quando esse é o caso, HwStorFindAdapter é chamado em IRQL == DISPATCH_LEVEL. Além disso, quando no modo de despejo, HwStorFindAdapter é chamado em IRQL == HIGH_LEVEL.

Exemplos

Para definir uma função de retorno de chamada HwStorFindAdapter , 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 HwStorFindAdapter chamada MyHwFindAdapter, use o tipo HW_FIND_ADAPTER conforme mostrado neste exemplo de código:

HW_FIND_ADAPTER MyHwFindAdapter;

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

_Use_decl_annotations_
ULONG
MyHwFindAdapter (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_z_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _In_ PBOOLEAN  Reserved3
  );
  {
      ...
  }

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