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

Artigo
08/07/2023

A rotina HwStorBuildIo processa o SRB com acesso não sincronizado a estruturas de dados do sistema compartilhado antes de passá-lo para hwStorStartIo.

Sintaxe

HW_BUILDIO HwBuildio;

BOOLEAN HwBuildio(
  PVOID DeviceExtension,
  PSCSI_REQUEST_BLOCK Srb
)
{...}

Parâmetros

DeviceExtension

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

Srb

Um ponteiro para o SRB (bloco de solicitação SCSI) a ser processado.

Retornar valor

HwStorBuildIo retorna TRUE para informar ao chamador que StorPort deve chamar a rotina HwStorStartIo se StorPort considerar o LUN pronto para receber E/S. HwStorBuildIo retorna FALSE para informar ao chamador que o SRB não deve ser passado para HwStorStartIo. Nesses casos, o driver de miniporto deve concluir o SRB chamando StorPortNotification com um tipo de notificação requestComplete. Isso pode ser feito no HwStorBuildIo ou em outro lugar no driver de miniporto, desde que o SRB seja concluído antes do tempo limite especificado no campo TimeOutValue da estrutura SRB.

Comentários

O nome HwStorBuildIo é apenas um espaço reservado para a função miniport que é apontada pelo membro HwBuildIo na estrutura HW_INITIALIZATION_DATA . O protótipo real dessa rotina é definido em Storport.h da seguinte maneira:

typedef
BOOLEAN
HW_BUILDIO (
  _In_ PVOID DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

O driver de porta chama a rotina HwStorBuildIo em DISPATCH IRQL sem manter nenhum bloqueio de rotação. Por isso, a alocação de memória usando StorPortAllocatePool e a exclusão mútua via StorPortAcquireSpinLock são permitidas no HwStorBuildIo. Em um ambiente multiprocessador, mais de um HwStorBuildIo pode estar ativo por vez, portanto, o driver de miniporto é necessário para sincronizar o acesso aos recursos do sistema, que podem estar em contenção se mais de uma instância do HwStorBuildIo estiver ativa a qualquer momento.

Ao concluir atividades de instalação de E/S demoradas no HwStorBuildIo em vez de no HwStorStartIo, o driver de miniporta permite maior simultaneidade de E/S e, portanto, melhora a taxa de transferência de E/S. Para maior desempenho, espera-se que os drivers de miniporto façam o máximo de pré-processamento possível no HwStorBuildIo para que ele possa enviar solicitações para o HBA via HwStorStartIo no menor tempo possível. Os dados pré-processados e o estado podem ser armazenados nas estruturas DeviceExtension ou SrbExtension . Somente modificações em partes exclusivas do DeviceExtension devem ocorrer, pois nenhum bloqueio é mantido. HwStorBuildIo e HwStorStartIo recebem os seguintes tipos de função Srb:

SRB_FUNCTION_EXECUTE_SCSI: envia um CDB para o barramento/destino/lun especificado.
- Srb-DataTransferLength> é válido para todos os Cdbs.
- Srb-DataBuffer> é NULL para solicitações de leitura e gravação. Para acessar os dados associados, use StorPortGetScatterGatherList (para transferências de Dma) ou StorPortGetSystemAddress (para E/S controlada pelo programa ) para obter a lista de Coleta de Dispersão ou o endereço virtual do buffer. Para outras solicitações, Srb-Databuffer> aponta para os dados associados ao Srb.
- Srb-PathId> é válido e representa o pathid fornecido ao Storport em StorPortNotification (BusChange). Os gravadores de drivers de miniporto precisam usar pathid como um índice em uma tabela de ônibus dentro do miniporto.
- Srb-TargetId> e Srb-Lun> são válidos.
SRB_FUNCTION_IO_CONTROL: Miniport definido.
- Srb-DataTransferLength> e Srb-DataBuffer> são válidos se definidos pelo solicitante.
- Srb-PathId>, Srb-TargetId> e Srb-Lun> são todos válidos.
SRB_FUNCTION_RESET_LOGICAL_UNIT: redefina a unidade lógica especificada (se o dispositivo for capaz).
- Srb-DataTransferLength> e Srb-DataBuffer> são inválidos.
- Srb-PathId>, Srb-TargetId> e Srb-Lun> são todos válidos.
SRB_FUNCTION_RESET_DEVICE: redefina o destino Scsi especificado.
- Srb-DataTransferLength> e Srb-DataBuffer>, Srb-Lun> são inválidos.
- Srb-PathId> e Srb-TargetId> são válidos.
SRB_FUNCTION_RESET_BUS: redefina todos os destinos no barramento SCSI especificado.
- Somente Srb-PathId> é válido.
SRB_FUNCTION_FLUSH: instrui o driver de miniporto a liberar todos os dados armazenados em cache.
- Executado apenas pelo driver de miniporta se ele definir CachesData == TRUE na estrutura PORT_CONFIGURATION_INFORMATION .
- Srb-PathId>, Srb-TargetId> e Srb-Lun> são todos válidos.
SRB_FUNCTION_SHUTDOWN: instrui o driver de miniporto a liberar todos os dados em cache preparatórios para desligar.
- Executado apenas pelo driver de miniporta se ele definir CachesData == TRUE na estrutura PORT_CONFIGURATION_INFORMATION .
- Srb-PathId>, Srb-TargetId> e Srb-Lun> são todos válidos.
SRB_FUNCTION_DUMP_POINTERS: fornece informações necessárias para que o driver de miniporto dê suporte ao despejo de memória e à hibernação.
- Essa solicitação é enviada para um driver de miniporto virtual do Storport que é usado para controlar o disco que contém os dados de despejo de memória. Começando com Windows 8, os drivers de miniporto não virtuais podem, opcionalmente, receber essa solicitação.
- Srb-PathId>, Srb-TargetId> e Srb-Lun> são todos válidos.
SRB_FUNCTION_FREE_DUMP_POINTERS: a partir do Windows 8, essa solicitação é enviada ao miniporto para liberar recursos alocados durante a solicitação de SRB_FUNCTION_DUMP_POINTERS.
- Srb-PathId>, Srb-TargetId> e Srb-Lun> são todos válidos.

Começando no Windows 8, o parâmetro Srb pode apontar para SCSI_REQUEST_BLOCK ou STORAGE_REQUEST_BLOCK. Se o identificador de função no campo Função de Srb for SRB_FUNCTION_STORAGE_REQUEST_BLOCK, o SRB será uma estrutura de solicitação STORAGE_REQUEST_BLOCK .

Para obter mais informações sobre o que você pode ou não fazer com segurança nesta rotina de driver de miniporta, consulte Rotina HwStorBuildIo não sincronizada.

Exemplos

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

HW_BUILDIO MyHwBuildIo;

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

_Use_decl_annotations_
BOOLEAN
MyHwBuildIo (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );
  {
      ...
  }

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