Função ScsiPortValidateRange (srb.h)

Artigo
02/29/2024

A rotina ScsiPortValidateRange indica se os valores de intervalo de acesso especificados já foram reivindicados no registro por outro driver.

Nota O driver de porta SCSI e os modelos de driver de miniporta SCSI podem ser alterados ou indisponíveis no futuro. Em vez disso, recomendamos usar os modelos de driver storport e driver de miniporto Storport .

Sintaxe

SCSIPORT_API BOOLEAN ScsiPortValidateRange(
  [in] PVOID                 HwDeviceExtension,
  [in] INTERFACE_TYPE        BusType,
  [in] ULONG                 SystemIoBusNumber,
  [in] SCSI_PHYSICAL_ADDRESS IoAddress,
  [in] ULONG                 NumberOfBytes,
  [in] BOOLEAN               InIoSpace
);

Parâmetros

[in] HwDeviceExtension

Ponteiro para a extensão do dispositivo de hardware. Essa é uma área de armazenamento por HBA que o driver de porta aloca e inicializa em nome do driver de miniporto. Os drivers de miniporta geralmente armazenam informações específicas do HBA nessa extensão, como o estado do HBA e os intervalos de acesso mapeados do HBA. Essa área está disponível para o driver de miniporto no membro DeviceExtension-HwDeviceExtension> do objeto de dispositivo do HBA imediatamente após o driver de miniporto chamar ScsiPortInitialize. O driver de porta libera essa memória quando remove o dispositivo.

[in] BusType

Especifica o valor do membro AdapterInterfaceType na estrutura PORT_CONFIGURATION_INFORMATION quando HwScsiFindAdapter é chamado.

[in] SystemIoBusNumber

Especifica o valor do membro SystemIoBusNumber nas informações de configuração quando HwScsiFindAdapter é chamado.

[in] IoAddress

Especifica um endereço base relativo ao barramento para o intervalo de portas ou memória do dispositivo a ser validado antes que a rotina HwScsiFindAdapter do driver de miniporte tente mapear o intervalo de acesso para o adaptador nesse endereço.

[in] NumberOfBytes

Especifica o tamanho em bytes ou o número de elementos no intervalo.

[in] InIoSpace

Indica quando TRUE o intervalo está no espaço de E/S, em vez de na memória. Quando FALSE, o intervalo está no espaço de memória.

Retornar valor

ScsiPortValidateRange retornará TRUE se a rotina HwScsiFindAdapter puder mapear e usar com segurança o intervalo mapeado para acessar o adaptador. ScsiPortValidateRange retornará FALSE se os valores de intervalo de acesso especificados já tiverem sido reivindicados no registro por outro driver.

Comentários

ScsiPortValidateRange só pode ser chamado da rotina HwScsiFindAdapter de um driver de miniport. Chamadas de outras rotinas de driver de miniporta resultarão em falha do sistema ou operação incorreta para o chamador.

Se o driver de porta específico do sistema operacional inicializar qualquer elemento AccessRanges da estrutura PORT_CONFIGURATION_INFORMATION antes de chamar a rotina HwScsiFindAdapter do driver de miniport, o driver de miniporto deverá passar os valores fornecidos para ScsiPortGetDeviceBase e usar os endereços lógicos mapeados para o intervalo para determinar se um HBA é compatível.

O driver de porta preenche um elemento do tipo ACCESS_RANGE com uma descrição completa de um intervalo de endereços relativo ao barramento para um adaptador ou o driver de porta zere todos os membros do elemento.

Para elementos AccessRanges de entrada definidos com zeros padrão, a rotina HwScsiFindAdapter pode tentar localizar um adaptador compatível com o barramento de E/S fornecido. Nessas circunstâncias, um driver de miniporto geralmente tem um conjunto de endereços padrão determinados pelo driver para seus tipos de HBA. No entanto, um driver carregado anteriormente pode já estar usando um adaptador inicializado em um dos intervalos de endereços padrão desse driver de miniporta, especialmente em sistemas somente x86 nos quais alguns dispositivos são inicializados no modo real x86. Para evitar que esse dispositivo seja reprogramado inadvertidamente, a rotina HwScsiFindAdapter de cada driver de miniport deve chamar ScsiPortValidateRange antes de mapear os endereços fornecidos pelo driver com ScsiPortGetDeviceBase e usar os endereços lógicos mapeados para interrogar adaptadores em um barramento de E/S.

Se ScsiPortValidateRange retornar FALSE, HwScsiFindAdapter não deverá tentar mapear os endereços do intervalo de entrada porque outro driver já reivindicou o intervalo no Registro.

Se ScsiPortValidateRange retornar TRUE, HwScsiFindAdapter poderá fazer o seguinte com segurança:

Mapeie os endereços de intervalo relativos ao barramento para endereços de intervalo lógico de espaço do sistema com ScsiPortGetDeviceBase.
Use os endereços lógicos mapeados com o ScsiPortRead/WriteXxx para determinar se o adaptador realmente é um HBA compatível com o driver.

Se um driver de miniporto usar um intervalo passado com êxito para ScsiPortValidateRange para um HBA compatível, esse driver deverá inverter o valor InIoSpace quando definir o membro RangeInMemory de um elemento AccessRanges no PORT_CONFIGURATION_INFORMATION.

ScsiPortValidateRange usa SCSI_PHYSICAL_ADDRESS para representar endereços relativos ao barramento.

typedef PHYSICAL_ADDRESS SCSI_PHYSICAL_ADDRESS, *PSCSI_PHYSICAL_ADDRESS;

O tipo SCSI_PHYSICAL_ADDRESS é um tipo de dados independente do sistema operacional que os drivers de miniporto SCSI usam para representar um endereço físico ou um endereço relativo ao barramento.