PVIDEO_HW_FIND_ADAPTER funzione di callback (video.h)

Articolo
08/07/2023

HwVidFindAdapter esegue l'inizializzazione dei dati specifici per il driver e i dispositivi miniport supportati dal driver miniport.

Sintassi

PVIDEO_HW_FIND_ADAPTER PvideoHwFindAdapter;

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

Parametri

HwDeviceExtension

Puntatore all'area di archiviazione per dispositivo del driver. Per altre informazioni, vedere Estensioni del dispositivo.

HwContext

È NULL e deve essere ignorato dal driver miniport.

ArgumentString

Puntatore a una stringa ASCII con terminazione Null che ha origine con l'utente. Questo puntatore può essere NULL.

ConfigInfo

Puntatore a una struttura VIDEO_PORT_CONFIG_INFO . Il driver della porta video alloca la memoria per e inizializza questa struttura con qualsiasi informazione di configurazione nota, ad esempio il numero e i valori del bus di I/O di sistema impostati dal driver miniport nella struttura VIDEO_HW_INITIALIZATION_DATA .

Again

Deve essere ignorato dal driver miniport.

Valore restituito

HwVidFindAdapter deve restituire uno dei codici di stato seguenti:

Codice restituito	Descrizione
ERROR_DEV_NOT_EXIST	Indica, per un bus reenumerabile, che il driver miniport non è riuscito a trovare il dispositivo.
ERROR_INVALID_PARAMETER	Indica che il driver miniport non è riuscito a configurare o inizializzare correttamente l'adattatore.
NO_ERROR	Indica l'esito positivo dell'operazione.

Commenti

Ogni driver miniport video deve avere una funzione HwVidFindAdapter .

Il driver della porta video esegue le operazioni seguenti prima di chiamare HwVidFindAdapter:

Alloca l'archiviazione per l'area di archiviazione per adattatore del driver miniport in base al valore di HwDeviceExtensionSize specificato dalla funzione DriverEntry del driver miniport nella struttura VIDEO_HW_INITIALIZATION_DATA e zero-inizializza lo spazio di archiviazione allocato.
Alloca lo spazio di archiviazione per una struttura VIDEO_PORT_CONFIG_INFO e inserisce tutte le informazioni disponibili in base alle informazioni fornite dal driver miniport in VIDEO_HW_INITIALIZATION_DATA.

Il driver della porta video chiama quindi la funzione HwVidFindAdapter del driver miniport con puntatori all'area di archiviazione e alle informazioni di configurazione inizializzate per scheda nei parametri HwDeviceExtension e ConfigInfo rispettivamente.

La funzione HwVidFindAdapter per i dispositivi in un bus enumerabile deve eseguire le operazioni seguenti:

Controllare le dimensioni della struttura VIDEO_PORT_CONFIG_INFO a cui ConfigInfo punta per garantire il controllo delle versioni appropriato.
Chiama VideoPortGetAccessRanges per ottenere gli indirizzi fisici relativi al bus a cui risponderà il dispositivo. Questi indirizzi vengono assegnati dal gestore PnP. Il driver miniport deve passare NULL nei parametri VendorId, DeviceId e Slot di VideoPortGetAccessRanges.
Per i driver miniport che supportano diversi tipi di dispositivo, determinare il tipo di dispositivo rilevato dal gestore PnP. Il driver miniport può chiamare VideoPortGetBusData per ottenere informazioni di configurazione PCI.
Immettere le informazioni di configurazione pertinenti ma mancanti nei membri appropriati della struttura VIDEO_PORT_CONFIG_INFO con dati specifici dell'adattatore.

HwVidFindAdapter non deve tentare di inizializzare il dispositivo.

HwVidFindAdapter può allocare risorse, ad esempio memoria e blocchi, per l'uso da parte del driver miniport. Queste risorse possono essere specifiche del dispositivo o possono essere condivise da diversi dispositivi supportati dal driver miniport. Se HwVidFindAdapter restituisce qualsiasi valore diverso da NO_ERROR, deve liberare tutte le risorse specifiche del dispositivo prima della restituzione. Per le risorse condivise tra più dispositivi, HwVidFindAdapter deve mantenere un conteggio dei riferimenti. Ad esempio, il conteggio dei riferimenti potrebbe indicare il numero di chiamate precedenti a HwVidFindAdapter riuscito. In questo modo, se HwVidFindAdapter deve avere esito negativo e determina che tutte le chiamate precedenti a HwVidFindAdapter hanno avuto esito negativo, potrebbe liberare le risorse condivise.

Se HwVidFindAdapter ha esito negativo ogni volta che viene chiamato dal driver della porta video, il sistema operativo potrebbe scaricare il driver miniport in un secondo momento. In tal caso, tutte le risorse allocate da HwVidFindAdapter ma non liberate perderanno.

Per un dispositivo su un bus reenumerabile, ad esempio ISA, PnP tenta comunque di avviare il dispositivo, anche se è responsabilità di HwVidFindAdapter determinare se il dispositivo è effettivamente presente. Se il dispositivo non viene trovato, HwVidFindAdapter deve restituire ERROR_DEV_NOT_EXIST.

HwVidFindAdapter deve anche chiamare VideoPortSetRegistryParameters per archiviare informazioni specifiche dell'adattatore nella chiave HardwareInformation . Queste informazioni vengono utilizzate dal programma Display in Pannello di controllo. Per informazioni dettagliate, vedere Impostazione delle informazioni hardware nel Registro di sistema .

A seconda della scheda e del valore AdapterInterfaceType in VIDEO_PORT_CONFIG_INFO, HwVidFindAdapter può chiamare alcune delle funzioni VideoPortXxx seguenti per ottenere i dati di configurazione relativi al bus necessari e gli intervalli di accesso mappati per comunicare con la scheda:

VideoPortGetBusData per ottenere informazioni di configurazione specifiche del tipo di bus su una scheda in un determinato bus di I/O.
VideoPortGetDeviceData per ottenere informazioni specifiche VIDEO_DEVICE_DATA_TYPE dal Registro di sistema e chiamare HwVidQueryDeviceCallback per elaborare queste informazioni.
VideoPortGetRegistryParameters per ottenere informazioni di configurazione dal Registro di sistema.
VideoPortGetAccessRanges per ottenere gli indirizzi degli intervalli di accesso relativi al bus e possibilmente altri valori di configurazione hardware e richiederli nel Registro di sistema per l'uso da parte del driver di una scheda.
VideoPortVerifyAccessRanges per determinare se la memoria video relativa al bus e/o le porte di I/O per la scheda possono essere richieste dal driver miniport; in caso contrario, un driver caricato in precedenza ha già richiesto la risorsa nel Registro di sistema e HwVidFindAdapter deve tentare di richiedere altri intervalli di accesso, se possibile o negativo.
VideoPortGetDeviceBase per eseguire il mapping di ogni indirizzo di base relativo al bus e alle dimensioni dell'intervallo, come descritto in una struttura di VIDEO_ACCESS_RANGE , agli indirizzi logici dello spazio di sistema . HwVidFindAdapter deve chiamare correttamente VideoPortVerifyAccessRanges o VideoPortGetAccessRanges prima di poter chiamare VideoPortGetDeviceBase.

Se il driver non gestisce gli interrupt, HwVidFindAdapter deve impostare sia BusInterruptLevel che BusInterruptVector nella struttura VIDEO_PORT_CONFIG_INFO su zero dopo la chiamata a VideoPortGetAccessRanges. Se entrambi i membri sono zero, il driver della porta video non connette l'interrupt per il driver miniport. L'impostazione esplicita di BusInterruptLevel e BusInterruptVector su zero in HwVidFindAdapter disabilita il punto di ingresso HwVidInterrupt , se presente, configurato dalla routine DriverEntry del driver del miniport.

HwVidFindAdapter non deve lasciare un adattatore non supportato con lo stato modificato. Per gli adattatori VGA/SVGA, HwVidFindAdapter deve lasciare l'adattatore in uno stato VGA e ripristinare eventuali registri estesi che potrebbero essere stati modificati nella condizione originale.

HwVidFindAdapter deve essere reso pageable.