PVIDEO_HW_FIND_ADAPTER função de retorno de chamada (video.h)

Artigo
08/07/2023

HwVidFindAdapter executa a inicialização de dados específicos para o driver de miniporto e dispositivos com suporte do driver de miniport.

Sintaxe

PVIDEO_HW_FIND_ADAPTER PvideoHwFindAdapter;

VP_STATUS PvideoHwFindAdapter(
  PVOID HwDeviceExtension,
  PVOID HwContext,
  PWSTR ArgumentString,
  PVIDEO_PORT_CONFIG_INFO ConfigInfo,
  PUCHAR Again
)
{...}

Parâmetros

HwDeviceExtension

Ponteiro para a área de armazenamento por dispositivo do driver. Para obter mais informações, consulte Extensões de dispositivo.

HwContext

É NULL e deve ser ignorado pelo driver de miniport.

ArgumentString

Ponteiro para uma cadeia de caracteres ASCII terminada em nulo que se origina com o usuário. Esse ponteiro pode ser NULL.

ConfigInfo

Ponteiro para uma estrutura VIDEO_PORT_CONFIG_INFO . O driver da porta de vídeo aloca memória para e inicializa essa estrutura com qualquer informação de configuração conhecida, como o número do barramento de E/S do sistema e os valores que o driver de miniporto definiu na estrutura VIDEO_HW_INITIALIZATION_DATA .

Again

Deve ser ignorado pelo driver de miniporto.

Retornar valor

HwVidFindAdapter deve retornar um dos seguintes códigos de status:

Código de retorno	Descrição
ERROR_DEV_NOT_EXIST	Indica, para um barramento reenumerável, que o motorista do miniporte não pôde encontrar o dispositivo.
ERROR_INVALID_PARAMETER	Indica que o driver de miniporte não pôde configurar ou inicializar o adaptador com êxito.
NO_ERROR	Indica êxito.

Comentários

Cada driver de miniporto de vídeo deve ter uma função HwVidFindAdapter .

O driver de porta de vídeo faz o seguinte antes de chamar HwVidFindAdapter:

Aloca armazenamento para a área de armazenamento por adaptador do driver de miniporto de acordo com o valor de HwDeviceExtensionSize que a função DriverEntry do driver de miniporto especificada na estrutura VIDEO_HW_INITIALIZATION_DATA e inicializa zero o armazenamento alocado.
Aloca armazenamento para uma estrutura de VIDEO_PORT_CONFIG_INFO e preenche todas as informações disponíveis com base nas informações fornecidas pelo driver de miniporto em VIDEO_HW_INITIALIZATION_DATA.

Em seguida, o driver de porta de vídeo chama a função HwVidFindAdapter do driver de miniport com ponteiros para a área de armazenamento por adaptador inicializada e informações de configuração nos parâmetros HwDeviceExtension e ConfigInfo , respectivamente.

A função HwVidFindAdapter para dispositivos em um barramento enumerável deve fazer o seguinte:

Verifique o tamanho da estrutura de VIDEO_PORT_CONFIG_INFO para a qual o ConfigInfo aponta para garantir o controle de versão adequado.
Chame VideoPortGetAccessRanges para obter os endereços físicos relativos ao barramento aos quais o dispositivo responderá. Esses endereços são atribuídos pelo gerenciador PnP. O driver de miniporte deve passar NULL nos parâmetros VendorId, DeviceId e Slot de VideoPortGetAccessRanges.
Para drivers de miniporte que dão suporte a vários tipos de dispositivo, determine o tipo de dispositivo detectado pelo gerenciador PnP. O driver de miniporto pode chamar VideoPortGetBusData para obter informações de configuração de PCI.
Preencha todas as informações de configuração relevantes, mas ausentes, nos membros apropriados da estrutura VIDEO_PORT_CONFIG_INFO com dados específicos do adaptador.

HwVidFindAdapter não deve tentar inicializar o dispositivo.

HwVidFindAdapter pode alocar recursos, como memória e bloqueios, para uso pelo driver de miniport. Esses recursos podem ser específicos do dispositivo ou podem ser compartilhados por vários dispositivos aos quais o driver de miniporto dá suporte. Se HwVidFindAdapter retornar qualquer valor diferente de NO_ERROR, ele deverá liberar todos os recursos específicos do dispositivo antes de retornar. Para recursos compartilhados entre vários dispositivos, HwVidFindAdapter deve manter uma contagem de referência. Por exemplo, a contagem de referência pode indicar o número de chamadas anteriores para HwVidFindAdapter que foram bem-sucedidas. Dessa forma, se hwVidFindAdapter precisar falhar e determinar que todas as chamadas anteriores para HwVidFindAdapter falharam, isso poderá liberar os recursos compartilhados.

Se HwVidFindAdapter falhar sempre que for chamado pelo driver de porta de vídeo, o sistema operacional poderá descarregar o driver de miniporto mais tarde. Nesse caso, todos os recursos que HwVidFindAdapter alocaram, mas não foram livres, vazarão.

Para um dispositivo em um barramento reenumerável como ISA, o PnP ainda tenta iniciar o dispositivo, embora seja responsabilidade de HwVidFindAdapter determinar se o dispositivo está realmente presente. Se o dispositivo não for encontrado, HwVidFindAdapter deverá retornar ERROR_DEV_NOT_EXIST.

HwVidFindAdapter também deve chamar VideoPortSetRegistryParameters para armazenar informações específicas do adaptador na chave HardwareInformation . Essas informações são usadas pelo programa Display no Painel de Controle. Consulte Configurando informações de hardware no Registro para obter detalhes.

Dependendo do adaptador e do valor AdapterInterfaceType em VIDEO_PORT_CONFIG_INFO, HwVidFindAdapter pode chamar algumas das seguintes funções VideoPortXxx para obter os dados de configuração relativos ao barramento necessários e intervalos de acesso mapeados para se comunicar com o adaptador:

VideoPortGetBusData para obter informações de configuração específicas do tipo de barramento sobre um adaptador em um ônibus de E/S específico.
VideoPortGetDeviceData para obter informações específicas VIDEO_DEVICE_DATA_TYPE do registro e chamar HwVidQueryDeviceCallback para processar essas informações.
VideoPortGetRegistryParameters para obter informações de configuração do registro.
VideoPortGetAccessRanges para obter endereços de intervalos de acesso relativos ao barramento e possivelmente outros valores de configuração de hardware e para reivindicá-los no registro para uso pelo driver de um adaptador.
VideoPortVerifyAccessRanges para determinar se as portas de memória de vídeo relativas ao barramento e/ou de E/S para o adaptador podem ser reivindicadas pelo driver de miniporte; caso contrário, um driver carregado anteriormente já reivindicou o recurso no registro e HwVidFindAdapter deve tentar reivindicar outros intervalos de acesso, se possível ou falhar.
VideoPortGetDeviceBase para mapear cada endereço base relativo ao barramento e o tamanho do intervalo, conforme descrito em uma estrutura VIDEO_ACCESS_RANGE , para endereços lógicos de espaço do sistema . HwVidFindAdapter deve chamar VideoPortVerifyAccessRanges ou VideoPortGetAccessRanges com êxito antes de chamar VideoPortGetDeviceBase.

Se o driver não lidar com interrupções, HwVidFindAdapter deverá definir BusInterruptLevel e BusInterruptVector na estrutura VIDEO_PORT_CONFIG_INFO como zero após sua chamada para VideoPortGetAccessRanges. Se ambos os membros forem zero, o driver da porta de vídeo não conectará a interrupção para o driver de miniporto. Definir explicitamente BusInterruptLevel e BusInterruptVector como zero em HwVidFindAdapter desabilita o ponto de entrada HwVidInterrupt , se houver, que foi configurado pela rotina driverEntry do miniport.

HwVidFindAdapter não deve deixar um adaptador sem suporte com seu estado alterado. Para adaptadores VGA/SVGA, HwVidFindAdapter deve deixar o adaptador em um estado de VGA e restaurar todos os registros estendidos que ele possa ter modificado para sua condição original.

HwVidFindAdapter deve se tornar paginável.