PVIDEO_HW_FIND_ADAPTER Rückruffunktion (video.h)

Artikel
08/07/2023

HwVidFindAdapter führt die Initialisierung von Daten durch, die spezifisch für den Miniporttreiber und die vom Miniporttreiber unterstützten Geräte sind.

Syntax

PVIDEO_HW_FIND_ADAPTER PvideoHwFindAdapter;

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

Parameter

HwDeviceExtension

Zeiger auf den Speicherbereich des Treibers pro Gerät. Weitere Informationen finden Sie unter Geräteerweiterungen.

HwContext

Ist NULL und sollte vom Miniporttreiber ignoriert werden.

ArgumentString

Zeiger auf eine MIT NULL endende ASCII-Zeichenfolge, die vom Benutzer stammt. Dieser Zeiger kann NULL sein.

ConfigInfo

Zeiger auf eine VIDEO_PORT_CONFIG_INFO-Struktur . Der Videoporttreiber weist Arbeitsspeicher für diese Struktur zu und initialisiert diese Struktur mit allen bekannten Konfigurationsinformationen, z. B. der System-E/A-Busnummer und den Werten, die der Miniporttreiber in der VIDEO_HW_INITIALIZATION_DATA-Struktur festgelegt hat.

Again

Sollte vom Miniporttreiber ignoriert werden.

Rückgabewert

HwVidFindAdapter muss einen der folgenden status-Codes zurückgeben:

Rückgabecode	Beschreibung
ERROR_DEV_NOT_EXIST	Gibt für einen wieder aufzählbaren Bus an, dass der Miniporttreiber das Gerät nicht finden konnte.
ERROR_INVALID_PARAMETER	Gibt an, dass der Miniporttreiber den Adapter nicht erfolgreich konfigurieren oder initialisieren konnte.
NO_ERROR	Gibt die erfolgreiche Ausführung an.

Hinweise

Jeder Video-Miniporttreiber muss über eine HwVidFindAdapter-Funktion verfügen.

Der Videoporttreiber führt die folgenden Schritte aus, bevor er HwVidFindAdapter aufruft:

Reserviert Speicher für den Speicherbereich des Miniporttreibers pro Adapter gemäß dem Wert von HwDeviceExtensionSize , den die DriverEntry-Funktion des Miniporttreibers in der VIDEO_HW_INITIALIZATION_DATA-Struktur angegeben hat, und initialisiert den zugeordneten Speicher null.
Reserviert Speicher für eine VIDEO_PORT_CONFIG_INFO-Struktur und füllt alle verfügbaren Informationen basierend auf den vom Miniport-Treiber bereitgestellten Informationen in VIDEO_HW_INITIALIZATION_DATA aus.

Der Videoporttreiber ruft dann die HwVidFindAdapter-Funktion des Miniporttreibers mit Zeigern auf den initialisierten Speicherbereich pro Adapter und Konfigurationsinformationen in den Parametern HwDeviceExtension bzw . ConfigInfo auf.

Die HwVidFindAdapter-Funktion für Geräte in einem enumerierbaren Bus muss die folgenden Aktionen ausführen:

Überprüfen Sie die Größe der VIDEO_PORT_CONFIG_INFO Struktur, auf die ConfigInfo verweist, um eine ordnungsgemäße Versionsverwaltung sicherzustellen.
Rufen Sie VideoPortGetAccessRanges auf, um die busrelativen physischen Adressen abzurufen, auf die das Gerät antwortet. Diese Adressen werden vom PnP-Manager zugewiesen. Der Miniporttreiber sollte NULL in den Parametern VendorId, DeviceId und Slot von VideoPortGetAccessRanges übergeben.
Ermitteln Sie für Miniporttreiber, die mehrere Gerätetypen unterstützen, den Typ des Geräts, das der PnP-Manager erkannt hat. Der Miniporttreiber kann VideoPortGetBusData aufrufen, um PCI-Konfigurationsinformationen zu erhalten.
Geben Sie alle relevanten, aber fehlenden Konfigurationsinformationen in den entsprechenden Membern der VIDEO_PORT_CONFIG_INFO-Struktur mit adapterspezifischen Daten ein.

HwVidFindAdapter sollte nicht versuchen, das Gerät zu initialisieren.

HwVidFindAdapter kann Ressourcen wie Arbeitsspeicher und Sperren zur Verwendung durch den Miniporttreiber zuordnen. Diese Ressourcen können gerätespezifisch sein oder von mehreren Geräten gemeinsam genutzt werden, die vom Miniporttreiber unterstützt werden. Wenn HwVidFindAdapter einen anderen Wert als NO_ERROR zurückgibt, müssen vor der Rückgabe alle gerätespezifischen Ressourcen freigegeben werden. Für Ressourcen, die von mehreren Geräten gemeinsam genutzt werden, sollte HwVidFindAdapter eine Verweisanzahl beibehalten. Beispielsweise könnte die Verweisanzahl die Anzahl der vorherigen Erfolgreichen Aufrufe von HwVidFindAdapter angeben. Wenn HwVidFindAdapter fehlschlägt und festgestellt wird, dass alle vorherigen Aufrufe von HwVidFindAdapter fehlgeschlagen sind, können die freigegebenen Ressourcen freigegeben werden.

Wenn HwVidFindAdapter jedes Mal fehlschlägt, wenn es vom Videoporttreiber aufgerufen wird, kann das Betriebssystem den Miniporttreiber später entladen. In einem solchen Fall werden alle Ressourcen, die HwVidFindAdapter zugeordnet, aber nicht freigegeben haben, verloren gehen.

Für ein Gerät in einem reenumerierbaren Bus wie ISA versucht PnP weiterhin, das Gerät zu starten, obwohl es in der Verantwortung von HwVidFindAdapter liegt, zu bestimmen, ob das Gerät tatsächlich vorhanden ist. Wenn das Gerät nicht gefunden wird, sollte HwVidFindAdapter ERROR_DEV_NOT_EXIST zurückgeben.

HwVidFindAdapter sollte auch VideoPortSetRegistryParameters aufrufen, um adapterspezifische Informationen im HardwareInformation-Schlüssel zu speichern. Diese Informationen werden vom Display-Programm in Systemsteuerung verwendet. Weitere Informationen finden Sie unter Festlegen von Hardwareinformationen in der Registrierung .

Abhängig vom Adapter und dem AdapterInterfaceType-Wert in VIDEO_PORT_CONFIG_INFO kann HwVidFindAdapter einige der folgenden VideoPortXxx-Funktionen aufrufen, um die erforderlichen busrelativen Konfigurationsdaten und zugeordneten Zugriffsbereiche für die Kommunikation mit dem Adapter abzurufen:

VideoPortGetBusData , um bustypspezifische Konfigurationsinformationen zu einem Adapter auf einem bestimmten E/A-Bus abzurufen.
VideoPortGetDeviceData , um VIDEO_DEVICE_DATA_TYPE spezifischen Informationen aus der Registrierung abzurufen, und rufen Sie HwVidQueryDeviceCallback auf, um diese Informationen zu verarbeiten.
VideoPortGetRegistryParameters zum Abrufen von Konfigurationsinformationen aus der Registrierung.
VideoPortGetAccessRanges , um Adressen für busrelative Zugriffsbereiche und möglicherweise andere Hardwarekonfigurationswerte abzurufen und sie in der Registrierung für die Verwendung durch den Treiber eines Adapters zu beanspruchen.
VideoPortVerifyAccessRanges , um zu bestimmen, ob busrelativer Videospeicher und/oder E/A-Ports für den Adapter vom Miniporttreiber beansprucht werden können; Andernfalls hat ein zuvor geladener Treiber die Ressource in der Registrierung bereits in Anspruch genommen, und HwVidFindAdapter muss versuchen, nach Möglichkeit andere Zugriffsbereiche in Anspruch zu nehmen, oder schlägt fehl.
VideoPortGetDeviceBase , um jede erfolgreich beanspruchte busrelative Basisadresse und Bereichsgröße, wie in einer VIDEO_ACCESS_RANGE-Struktur beschrieben, logischen Systemraumadressen zuzuordnen. HwVidFindAdapter muss VideoPortVerifyAccessRanges oder VideoPortGetAccessRanges erfolgreich aufrufen, bevor VideoPortGetDeviceBase aufgerufen werden kann.

Wenn der Treiber keine Interrupts verarbeitet, sollte HwVidFindAdapter nach dem Aufruf von VideoPortGetAccessRanges sowohl BusInterruptLevel als auch BusInterruptVector in der VIDEO_PORT_CONFIG_INFO-Struktur auf Null festlegen. Wenn beide Member null sind, verbindet der Videoporttreiber den Interrupt für den Miniporttreiber nicht. Durch das explizite Festlegen von BusInterruptLevel und BusInterruptVector auf 0 in HwVidFindAdapter wird ggf. der Einstiegspunkt HwVidInterrupt deaktiviert, der von der DriverEntry-Routine des Miniporttreibers eingerichtet wurde.

HwVidFindAdapter darf den Status eines nicht unterstützten Adapters nicht ändern. Bei VGA-/SVGA-Adaptern muss HwVidFindAdapter den Adapter in einem VGA-Zustand belassen und alle erweiterten Register wiederherstellen, die er möglicherweise in den ursprünglichen Zustand geändert hat.

HwVidFindAdapter sollte ausgelagert werden.