PVIDEO_HW_FIND_ADAPTER回调函数 (video.h)

项目
08/07/2023

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 之前执行以下操作：

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

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

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

检查 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 密钥中。此信息由控制面板中的 Display 程序使用。有关详细信息，请参阅在注册表中设置硬件信息。

根据适配器和 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 可分页。