PVIDEO_HW_FIND_ADAPTER回调函数（video.h）

项目
02/07/2025

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 结构的指针。视频端口驱动程序分配内存，并使用任何已知的配置信息（例如系统 IO 总线号和微型端口驱动程序在 VIDEO_HW_INITIALIZATION_DATA 结构中设置的值）来分配内存并初始化此结构。

Again

应被微型端口驱动程序忽略。

返回值

HwVidFindAdapter 必须返回以下状态代码之一：

返回代码	描述
ERROR_DEV_NOT_EXIST	指示对于可恢复的总线，微型端口驱动程序找不到设备。
ERROR_INVALID_PARAMETER	指示微型端口驱动程序无法成功配置或初始化适配器。
NO_ERROR	指示成功。

言论

每个视频微型端口驱动程序都必须具有 HwVidFindAdapter 函数。

视频端口驱动程序在调用 HwVidFindAdapter之前执行以下作：

根据 HwDeviceExtensionSize 微型端口驱动程序的 DriverEntry 函数在 VIDEO_HW_INITIALIZATION_DATA 结构中指定的每个适配器存储区域分配存储，并将零初始化分配的存储。
为 VIDEO_PORT_CONFIG_INFO 结构分配存储，并根据VIDEO_HW_INITIALIZATION_DATA中微型端口驱动程序提供的信息填充所有可用信息。

然后，视频端口驱动程序调用微型端口驱动程序的 HwVidFindAdapter 函数，并分别指向 HwDeviceExtension 和 ConfigInfo 参数中初始化的每个适配器存储区域和配置信息。

可枚举总线上设备的 HwVidFindAdapter 函数必须执行以下作：

检查 ConfigInfo 指向的VIDEO_PORT_CONFIG_INFO结构的大小，以确保正确的版本控制。
调用 VideoPortGetAccessRanges 以获取设备将响应的相对于总线的物理地址。这些地址由 PnP 管理器分配。微型端口驱动程序应在 VendorId、DeviceId中传递 NULL，以及 VideoPortGetAccessRanges的槽参数。
对于支持多种设备类型的微型端口驱动程序，请确定 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 设置为零，则禁用 HwVidInterrupt 入口点（如果有的话）由微型端口驱动程序的 DriverEntry 例程设置。

HwVidFindAdapter 不得将不受支持的适配器保留其状态更改。对于 VGA/SVGA 适配器，HwVidFindAdapter 必须将适配器保留为 VGA 状态，并还原它可能已修改为其原始条件的任何扩展寄存器。

应 HwVidFindAdapter 进行分页。