(video.h) PVIDEO_HW_FIND_ADAPTER 回呼函式

發行項
03/01/2024

HwVidFindAdapter 會執行迷你埠驅動程式所支援之迷你埠驅動程式和裝置的特定數據初始化。

語法

PVIDEO_HW_FIND_ADAPTER PvideoHwFindAdapter;

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

參數

HwDeviceExtension

驅動程式個別裝置儲存區域的指標。如需詳細資訊，請參閱裝置擴充功能。

HwContext

為 NULL ，而且應該由迷你埠驅動程式忽略。

ArgumentString

以 Null 結尾的 ASCII 字串指標，該字串源自使用者。此指標可以是 NULL。

ConfigInfo

VIDEO_PORT_CONFIG_INFO 結構的指標。視訊埠驅動程式會配置記憶體，並使用任何已知的組態資訊來初始化此結構，例如 VIDEO_HW_INITIALIZATION_DATA結構中所設定迷你埠驅動程序的系統 IO 總線號碼和值。

Again

迷你埠驅動程序應該忽略。

傳回值

HwVidFindAdapter 必須傳回下列其中一個狀態代碼：

傳回碼	Description
ERROR_DEV_NOT_EXIST	表示對於可繼續的總線，迷你埠驅動程式找不到裝置。
ERROR_INVALID_PARAMETER	表示迷你埠驅動程式無法成功設定或初始化配接器。
NO_ERROR	表示成功。

備註

每個視訊迷你埠驅動程式都必須有 HwVidFindAdapter 函 式。

視訊埠驅動程式會在呼叫 HwVidFindAdapter 之前執行下列動作：

根據 HwDeviceExtensionSize 的值，配置迷你埠驅動程式的 DriverEntry 函式在 VIDEO_HW_INITIALIZATION_DATA 結構中指定的每張適配卡儲存區儲存區，並以零初始化已配置的記憶體。
根據VIDEO_HW_INITIALIZATION_DATA中迷你埠驅動程式提供的資訊，配置 VIDEO_PORT_CONFIG_INFO 結構的記憶體，並填入所有可用的資訊。

然後，視訊埠驅動程式會分別呼叫迷你埠驅動程式的 HwVidFindAdapter 函式，以及 HwDeviceExtension 和 ConfigInfo 參數中初始化的個別適配卡儲存區域和組態資訊。

可列舉總線上裝置的 HwVidFindFindAdapter 函式必須執行下列動作：

檢查 ConfigInfo 指向的VIDEO_PORT_CONFIG_INFO結構大小，以確保版本設定正確。
呼叫 VideoPortGetAccessRanges 以取得裝置將回應的總線相對實體位址。這些位址是由 PnP 管理員指派。迷你埠驅動程序應該在 VideoPortGetAccessRanges 的 VendorId、DeviceId 和 Slot 參數中傳遞 NULL。
對於支援數種裝置類型的迷你埠驅動程式，請判斷 PnP 管理員偵測到的裝置類型。迷你埠驅動程式可以呼叫 VideoPortGetBusData 來取得 PCI 組態資訊。
使用配接器特定數據，在VIDEO_PORT_CONFIG_INFO結構的適當成員中填入任何相關但遺漏的組態資訊。

HwVidFindAdapter 不應該嘗試初始化裝置。

HwVidFindAdapter 可以配置記憶體和鎖定等資源，以供迷你埠驅動程式使用。這些資源可以是裝置專屬的，也可以由迷你埠驅動程式支援的數個裝置共用。如果 HwVidFindAdapter 傳回NO_ERROR以外的任何值，則必須先釋放所有裝置特定資源，才能傳回。對於在數個裝置之間共用的資源， HwVidFindAdapter 應該保留參考計數。例如，參考計數可能表示先前呼叫 成功 HwVidFindAdapter 的數目。如此一來，如果 HwVidFindAdapter 必須失敗，並判斷 HwVidFindAdapter 的所有先前呼叫都失敗，它可能會釋放共享資源。

如果 HwVidFindAdapter 每次由視訊埠驅動程式呼叫時失敗，操作系統稍後可能會卸除迷你埠驅動程式。在這種情況下， HwVidFindAdapter 配置但未釋放的任何資源都會流失。

對於 ISA 等可繼續總線上的裝置，PnP 仍會嘗試啟動裝置，雖然 HwVidFindAdapter 負責判斷裝置是否確實存在。如果找不到裝置， HwVidFindAdapter 應該會傳回ERROR_DEV_NOT_EXIST。

HwVidFindAdapter 也應該呼叫 VideoPortSetRegistryParameters ，將適配卡特定資訊儲存在 HardwareInformation 機碼中。這項資訊是由控制台中的顯示程式使用。如需詳細資訊，請參閱在登錄中設定硬體資訊。

根據VIDEO_PORT_CONFIG_INFO中的配接器和 AdapterInterfaceType 值，HwVidFindAdapter 可以呼叫下列一些 VideoPortXxx 函式，以取得必要的總線相對設定數據和對應的存取範圍，以與配接器通訊：

VideoPortGetBusData 可取得特定 I/O 總線上適配卡的總線類型特定組態資訊。
VideoPortGetDeviceData 可從登錄取得VIDEO_DEVICE_DATA_TYPE特定資訊，並呼叫 HwVidQueryDeviceCallback 來處理此資訊。
VideoPortGetRegistryParameters 可從登錄取得組態資訊。
VideoPortGetAccessRanges 可取得總線相對存取範圍位址和其他硬體組態值，並在登錄中宣告它們以供適配卡驅動程式使用。
VideoPortVerifyAccessRanges ，以判斷適配卡的總線相對視訊記憶體和/或 I/O 埠是否可以由迷你埠驅動程式宣告;否則，先前載入的驅動程式已在登錄中宣告資源，而且 HwVidFindAdapter 必須盡可能嘗試宣告其他存取範圍或失敗。
VideoPortGetDeviceBase，將每個成功宣告的總線相對基位址和範圍大小對應至系統空間邏輯位址，如VIDEO_ACCESS_RANGE結構中所述。 HwVidFindAdapter 必須先成功呼叫 VideoPortVerifyAccessRanges 或 VideoPortGetAccessRanges ，才能呼叫 VideoPortGetDeviceBase。

如果驅動程式未處理中斷，HwVidFindAdapter 應該在呼叫 VideoPortGetAccessRanges 之後，將VIDEO_PORT_CONFIG_INFO結構中的 BusInterruptLevel 和 BusInterruptVector 設定為零。如果兩個成員都是零，視訊埠驅動程式不會連接迷你埠驅動程式的中斷。在 HwVidFindAdapter 中明確將 BusInterruptLevel 和 BusInterruptVector 設定為零，會停用迷你埠驅動程式 DriverEntry 例程所設定的 HwVidInterrupt 進入點。

HwVidFindAdapter 不得讓不支援的適配卡變更其狀態。針對 VGA/SVGA 配接器， HwVidFindAdapter 必須讓適配卡保持 VGA 狀態，並還原任何可能已修改為原始條件的擴充緩存器。

HwVidFindAdapter 應設為可分頁。