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

Artigo
08/07/2023

O driver do Storport chama a rotina HwStorStartIo uma vez para cada solicitação de E/S de entrada.

Sintaxe

HW_STARTIO HwStartio;

BOOLEAN HwStartio(
  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 bloco de solicitação SCSI a ser iniciado.

Retornar valor

HwStorStartIo retornará TRUE se a solicitação tiver sido iniciada com êxito. Caso contrário, retornará FALSE.

Comentários

O HwStorStartIo inicia uma operação de E/S. O StorPort foi projetado para usar os dados privados de um miniporto preparados no HwStorBuildIo e armazenados em DeviceExtension ou Srb-SrbExtension>. Como o HwStorBuildIo é chamado sem bloqueios de rotação, o melhor desempenho do driver é obtido preparando o máximo de dados possível no HwStorBuildIo.

O Storport chama HwStorStartIo das seguintes maneiras:

Para drivers de miniporto não virtuais de armazenamento, dependendo do valor de SynchronizationModel definido em PORT_CONFIGURATION_INFORMATION, o Storport sempre chama HwStorStartIo no mesmo IRQL e usa um bloqueio de rotação interno para garantir que as solicitações de E/S sejam iniciadas sequencialmente. O IRQL é DISPATCH_LEVEL (modo full-duplex) ou DIRQL (modo half-duplex).

Ao lidar com E/S no modo meio duplex, a rotina HwStorStartIo não precisa adquirir seu próprio bloqueio de rotação. Além disso, a alocação de memória usando StorPortAllocatePool e a exclusão mútua por meio de StorPortAcquireSpinLock não são permitidas na rotina HwStorStartIo . No modo full-duplex, StorPortAllocatePool e StorPortAcquireSpinLock podem ser usados na rotina HwStorStartIo .

Se um miniporto não virtual der suporte à otimização de canais simultâneos (STOR_PERF_CONCURRENT_CHANNELS definido por StorPortInitializePerfOpts), várias chamadas para HwStorStartIo simultaneamente serão possíveis. Nesse caso, o miniporto precisará garantir que todos os recursos compartilhados sejam protegidos por um bloqueio. Com essa otimização de desempenho, o Storport não adquirirá o bloqueio StartIo antes de chamar HwStorStartIo e o miniporto deverá fornecer seu próprio bloqueio, se necessário.
Para drivers de miniporto virtual de armazenamento, o Storport chama HwStorStartIo em qualquer IRQL <= DISPATCH_LEVEL e não usa um bloqueio de rotação interno. A rotina HwStorStartIo pode adquirir seu próprio bloqueio de rotação chamando StorPortAcquireSpinLock. Além disso, as chamadas para StorPortAllocatePool são permitidas na rotina HwStorStartIo de um driver de miniporto virtual de armazenamento.

Espera-se que o SRB seja concluído quando o SCSI status for recebido. Quando o driver Storport conclui o SRB chamando StorPortNotification com um NotificationType de RequestComplete, espera-se que um SRB retorne um dos seguintes valores no campo SrbStatus do Srb:

SRB_STATUS_SUCCESS
- Indica que o Srb foi enviado e status SCSI (possivelmente com dados) foi retornado.
- O Storport retorna os dados e status ao chamador.
- A ação miniportar não é nenhuma, exceto para concluir a solicitação usando StorPortNotification para RequestComplete, provavelmente do HwStorDpcRoutine.
SRB_STATUS_BUSY
- Indica que há um problema temporário com o envio do Srb (por exemplo, os registros do adaptador ou os buffers estão ocupados).
- O Storport descarta a extensão Srb original para a qual Srb-SrbExtension> aponta e emite uma nova. O Storport envia o Srb original com a extensão Srb recém-emitida em chamadas subsequentes para HwStorBuildIo e HwStorStartIo. Todos os dados na extensão Srb original serão perdidos.
- O miniporto não deve atualizar o DataTransferLength do Srb.
- Como uma nova extensão Srb é emitida, o miniporto deve garantir que ele nunca emita SRB_STATUS_BUSY no meio de uma transação SCSI. Depois que a transação for iniciada, ela deverá ser concluída ou cancelada. Os estados de hardware ocupados durante a transação devem ser tratados pelo driver de miniporta.

O nome HwStorStartIo é um espaço reservado para descrever a rotina de miniporto definida no membro HwStartIo da estrutura HW_INITIALIZATION_DATA . Essa estrutura é passada no parâmetro HwInitializationData de StorPortInitialize. O protótipo real dessa rotina é definido em Storport.h da seguinte maneira:

typedef
BOOLEAN
(*PHW_STARTIO) (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

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 .

Exemplos

Para definir uma rotina de retorno de chamada HwStorStartIo , primeiro você deve fornecer uma declaração de função que o SDV ( Verificador de Driver Estático ) e outras ferramentas de verificação exigem, conforme mostrado no exemplo de código a seguir:

Para definir uma função de retorno de chamada HwStorStartIo , 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 HwStorStartIo chamada MyHwStartIo, use o tipo HW_STARTIO e implemente sua rotina de retorno de chamada da seguinte maneira:

HW_STARTIO MyHwStartIo

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

O tipo de função HW_STARTIO é 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 o _Use_decl_annotations_ annotation à sua definição de função. O _Use_decl_annotations_ annotation garante que as anotações aplicadas ao tipo de função HW_STARTIO 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.