estrutura VIDEO_ACCESS_RANGE (video.h)

Artigo
08/08/2023

A estrutura VIDEO_ACCESS_RANGE define uma porta de E/S do dispositivo ou um intervalo de memória para o adaptador de vídeo. A função HwVidFindAdapter de cada driver de miniporte deve configurar uma matriz de elementos do tipo VIDEO_ACCESS_RANGE, chamada matriz de intervalos de acesso, para cada adaptador de vídeo compatível com o driver de miniport.

Para drivers de miniporto compatíveis com VGA, VIDEO_ACCESS_RANGE também define um elemento em uma matriz passada para VideoPortSetTrappedEmulatorPorts para habilitar ou desabilitar o acesso direto às portas de E/S por aplicativos MS-DOS de tela inteira.

Sintaxe

typedef struct _VIDEO_ACCESS_RANGE {
  PHYSICAL_ADDRESS RangeStart;
  ULONG            RangeLength;
  UCHAR            RangeInIoSpace;
  UCHAR            RangeVisible;
  UCHAR            RangeShareable;
  UCHAR            RangePassive;
} VIDEO_ACCESS_RANGE, *PVIDEO_ACCESS_RANGE;

Membros

RangeStart

Especifica o endereço base relativo ao barramento de uma memória ou intervalo de portas de E/S para um elemento na matriz de intervalos de acesso passado para VideoPortVerifyAccessRanges ou retornado por VideoPortGetAccessRanges.

Especifica o endereço base relativo ao barramento de um intervalo de portas de E/S para uma matriz a ser passada para VideoPortSetTrappedEmulatorPorts.

RangeLength

Especifica o número de portas de E/S ou tamanho em bytes para o intervalo.

RangeInIoSpace

Especifica se o intervalo está no espaço de E/S ou no espaço de memória. Um valor true ( 1) indica que o intervalo está no espaço de E/S; um valor de FALSE (0) indica que o intervalo está no espaço de memória.

RangeVisible

Será ignorado se a função HwVidFindAdapter do driver de miniport estiver configurando a matriz de intervalos de acesso.

É definido como TRUE por drivers de miniporte compatíveis com VGA e passado para VideoPortSetTrappedEmulatorPorts para habilitar o acesso direto ao intervalo de portas de E/S por um aplicativo MS-DOS de tela inteira. Se definido como FALSE, as instruções emitidas pelo aplicativo continuarão a ser interceptadas e encaminhadas para a função SvgaHwIoXxx do driver de miniport para validação.

RangeShareable

Será definido como TRUE se o intervalo de acesso descrito por esse elemento puder ser compartilhado com outro driver e/ou dispositivo ou com FALSE se o intervalo não puder ser compartilhado.

É ignorado por VideoPortSetTrappedEmulatorPorts.

RangePassive

Indica se o dispositivo realmente usa a porta. Os valores desse membro são mostrados na tabela a seguir.

Valor	Significado
VIDEO_RANGE_PASSIVE_DECODE	O dispositivo decodifica a porta, mas o driver não a usa.
VIDEO_RANGE_10_BIT_DECODE	O dispositivo decodifica dez bits do endereço da porta.

Comentários

O driver de miniporte deve reivindicar recursos herdados em sua função DriverEntry ou HwVidLegacyResources .

Caso contrário, a função HwVidFindAdapter de um driver de miniporte configura a matriz de intervalos de acesso para os recursos de PCI de um adaptador. Ele pode usar informações retornadas por VideoPortGetAccessRanges. Como alternativa, ele pode usar informações recuperadas do registro chamando VideoPortGetDeviceData com uma função HwVidQueryDeviceCallback fornecida pelo driver de miniport ou VideoPortGetRegistryParameters com uma função HwVidQueryNamedValueCallback fornecida pelo miniport driver. Se chamar esses VideoPortXxx não fornecer os valores de intervalo de acesso relativos ao barramento, HwVidFindAdapter poderá configurar elementos de intervalos de acesso usando valores padrão relativos ao barramento fornecidos pelo motorista.

Reivindicando intervalos de acesso no Registro

O driver de miniporte deve chamar VideoPortVerifyAccessRanges com quaisquer intervalos de acesso obtidos de VideoPortGetDeviceData, VideoPortGetAccessRanges ou fornecidos como padrão pelo driver de miniport. Se VideoPortVerifyAccessRanges retornar NO_ERROR para essa matriz de intervalos de acesso, a função HwVidFindAdapter ou HwVidQueryDeviceCallback poderá mapear os intervalos com VideoPortGetDeviceBase e usar os endereços lógicos mapeados retornados para acessar o adaptador.

Uma chamada bem-sucedida para VideoPortGetAccessRanges também declara os intervalos de acesso relativos ao barramento retornados no registro do chamador. Se o driver de miniporte modificar qualquer um dos valores retornados, ele deverá chamar VideoPortVerifyAccessRanges com o intervalo de acesso completo, incluindo quaisquer elementos não modificados. Cada chamada para VideoPortGetAccessRanges ou VideoPortVerifyAccessRanges para um adaptador de vídeo específico substitui os recursos de hardware reivindicados pelo chamador no registro.

Um driver de miniporte não deve tentar usar um intervalo para o qual VideoPortVerifyAccessRanges ou VideoPortGetAccessRanges não retorna NO_ERROR.

Mapeando intervalos de acesso para se comunicar com o adaptador

Depois que um driver de miniporto tiver reivindicado recursos no registro de um adaptador, ele não poderá usar endereços relativos ao barramento para acessar ou configurar o adaptador, pois o HAL pode remapear todos os endereços de dispositivo relativos ao barramento para o espaço do sistema.

A função HwVidFindAdapter do driver de miniport deve chamar VideoPortGetDeviceBase para obter endereços lógicos mapeados para seus intervalos de acesso. Somente então o driver de miniporto pode se comunicar com o adaptador de vídeo passando os endereços de intervalo lógico mapeados retornados para VideoPortRead/WritePortXxx para acessar a memória do dispositivo no espaço de E/S e/ou VideoPortRead/WriteRegisterXxx para acessar a memória do dispositivo no espaço de memória.

Determinando se um intervalo de acesso é fragmentável

Siga estas diretrizes para determinar se um intervalo de acesso pode ser compartilhado:

Se o intervalo de portas de memória ou E/S deve ser "propriedade" desse driver e/ou o acesso a esse intervalo por qualquer outro driver pode causar um problema, defina RangeSharable como FALSE.
Se o intervalo puder ser compartilhado com um driver de dispositivo que coopera, defina RangeSharable como TRUE.

Os drivers de miniporto SVGA que implementam todas as funcionalidades de VGA (declaradas no registro como VgaCompatible definida como um) devem declarar seus intervalos de acesso como inválidos para que o driver VGA do sistema não seja carregado. Por outro lado, os drivers de miniporto para adaptadores como o S3 ou o XGA, que definem VgaCompatible como zero no registro, devem reivindicar todos os recursos que compartilham com o driver VGA do sistema como fragmentáveis.

No entanto, os drivers de miniport para cartões que funcionam com um IOCTL de passagem e que podem ser conectados a qualquer VGA ou SVGA cartão não devem estar usando nenhuma porta VGA do sistema ou intervalos de memória. Se o fizerem, esse driver não deverá tentar reivindicar nenhum dos intervalos de acesso da VGA no Registro. As tentativas de reivindicar recursos de VGA por esse driver de miniporto provavelmente causarão um conflito de recursos porque o driver de qualquer cartão SVGA no computador terá reivindicado esses intervalos de acesso como inválidos.

Passando elementos de intervalo de porta de E/S para VideoPortSetTrappedEmulatorPorts

Todos os elementos de matriz do tipo VIDEO_ACCESS_RANGE que descrevem intervalos de portas de E/S são considerados invisíveis, a menos que um driver de miniporto compatível com VGA em um computador baseado em x86 redefina explicitamente os membros rangeVisible para TRUE e chame VideoPortSetTrappedEmulatorPorts para habilitar um ou mais intervalos de portas de E/S. VideoPortSetTrappedEmulatorPorts ignora os membros RangeSharable da matriz de entrada.

Em uma matriz de elementos do tipo VIDEO_ACCESS_RANGE passados para VideoPortSetTrappedEmulatorPorts, o valor do membro RangeVisible de cada elemento determina se as portas de E/S fornecidas podem ser acessadas diretamente pela VDM (aplicativo MS-DOS em execução em tela inteira em um computador baseado em x86) ou se esse fluxo de E/S emitido pelo aplicativo está preso e encaminhado para uma função SvgaHwIoPortXxx fornecida pelo miniportor para validação primeiro.