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

Artigo
02/26/2024

O miniporto virtual Storport usa informações de configuração fornecidas para a rotina VIRTUAL_HW_FIND_ADAPTER para se inicializar ainda mais.

Sintaxe

VIRTUAL_HW_FIND_ADAPTER VirtualHwFindAdapter;

ULONG VirtualHwFindAdapter(
  PVOID DeviceExtension,
  PVOID HwContext,
  PVOID BusInformation,
  PVOID LowerDevice,
  PCHAR ArgumentString,
  PPORT_CONFIGURATION_INFORMATION ConfigInfo,
  PBOOLEAN Again
)
{...}

Parâmetros

DeviceExtension

Um ponteiro para a área de armazenamento não paginado por adaptador do driver de miniport. O driver de porta específico do sistema operacional aloca memória para e inicializa essa extensão com zeros antes de chamar a rotina de VIRTUAL_HW_FIND_ADAPTER do miniporto.

HwContext

Um ponteiro para o PDO na pilha do dispositivo. O HBA em si é o FDO. O PDO poderá pertencer ao driver de Pci.sys se o driver de miniporta controlar o hardware físico. Mas, no caso de um driver de miniporta virtual, o PDO pertence ao gerenciador PnP.

BusInformation

Um ponteiro para o FDO (objeto de dispositivo funcional) do miniport.

LowerDevice

Um ponteiro para o objeto de dispositivo controlado pelo FDO do miniporto.

ArgumentString

Um ponteiro para uma cadeia de caracteres ASCII terminada em nulo. Essa cadeia de caracteres, se fornecida, contém informações do dispositivo do registro, como um parâmetro base.

ConfigInfo

Um ponteiro para uma estrutura PORT_CONFIGURATION_INFORMATION . O driver de porta inicializa essa estrutura com qualquer informação de configuração conhecida, como valores definidos pelo DriverEntry do driver de miniport no VIRTUAL_HW_INITIALIZATION_DATA. VIRTUAL_HW_FIND_ADAPTER deve usar qualquer informação fornecida para determinar se o HBA virtual descrito é aquele ao qual o driver de miniporto dá suporte. Nesse caso, VIRTUAL_HW_FIND_ADAPTER inicializa e configura esse HBA e preenche as informações de configuração ausentes. Se possível, um driver de miniporto deve ter valores de configuração padrão para cada tipo de HBA compatível, caso o driver de porta dependente do sistema operacional não possa fornecer informações de configuração adicionais que não foram fornecidas pela rotina DriverEntry do driver de miniport.

Again

Não usado.

Retornar valor

VIRTUAL_HW_FIND_ADAPTER deve retornar um dos seguintes valores de status:

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

Comentários

O campo VirtualDevice na estrutura de informações de configuração deve ser definido como TRUE. Outros campos podem ser definidos conforme necessário.

O driver de porta chama a VIRTUAL_HW_FIND_ADAPTER do miniporto virtual storport em PASSIVE_LEVEL.

O nome VirtualHwStorFindAdapter é um texto de espaço reservado para o nome de rotina real. O protótipo real dessa rotina é definido em Srb.h da seguinte maneira:

typedef
ULONG
VIRTUAL_HW_FIND_ADAPTER (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_ PVOID  LowerDevice,
  _In_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _Out_ PBOOLEAN Again
  );

Exemplos

Para definir um VIRTUAL_HW_FIND_ADAPTER função de retorno de chamada, 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 um VIRTUAL_HW_FIND_ADAPTER rotina de retorno de chamada denominada MyVirtualHwFindAdapter, use o tipo VIRTUAL_HW_FIND_ADAPTER conforme mostrado neste exemplo de código:

VIRTUAL_HW_FIND_ADAPTER MyVirtualHwFindAdapter;

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

_Use_decl_annotations_
ULONG
MyVirtualHwFindAdapter (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_ PVOID  LowerDevice,
  _In_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _Out_ PBOOLEAN Again
  );
  {
      ...
  }

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