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

O driver 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 miniporto por área de armazenamento do HBA.

Srb

Um ponteiro para o bloco de solicitação SCSI a ser iniciado.

Valor retornado

HwStorStartIo retornaráTRUE se a solicitação tiver sido iniciada com êxito. Caso contrário, ele 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.

Storport chama HwStorStartIo das seguintes maneiras:

  • Para drivers de miniporte 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 meio 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 pelo 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 deve 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 miniporte virtual de armazenamento.

Espera-se que o SRB seja concluído quando o status SCSI for recebido. Quando o driver Storport conclui o SRB chamando StorPortNotification com um NotificationType of 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 o status SCSI (possivelmente com dados) foi retornado.
    • O Storport retorna os dados e o status para o chamador.
    • A ação miniporte não é nenhuma, exceto para concluir a solicitação usando StorPortNotification para RequestComplete, provavelmente da HwStorDpcRoutine.
  • SRB_STATUS_BUSY

    • Indica que há um problema temporário com o envio do Srb (por exemplo, os registros de adaptador ou buffers estão ocupados).
    • 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 ocupados de hardware durante a transação devem ser tratados pelo driver de miniporto.

O nome HwStorStartIo é um espaço reservado para descrever a rotina de miniporto definida no membro HwStartIo da estrutura de 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
  );

A partir de 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 do 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 a _Use_decl_annotations_ annotation definição de função. Garante _Use_decl_annotations_ annotation 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 Declaring Functions Using Function Role Types for Storport Drivers. Para obter informações sobre _Use_decl_annotations_, consulte Anotando o comportamento da função.

Requisitos

   
Plataforma de Destino Universal
Cabeçalho storport.h (inclua Storport.h)
IRQL DISPATCH_LEVEL (seção Ver Comentários.)

Confira também

HwStorBuildIo

SCSI_REQUEST_BLOCK

STORAGE_REQUEST_BLOCK

StorPortInitialize