функция обратного вызова 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

Указатель на строку ASCII, завершающуюся пустым значением, которая исходит от пользователя. Этот указатель может иметь значение NULL.

ConfigInfo

Указатель на структуру VIDEO_PORT_CONFIG_INFO . Драйвер видеопорта выделяет память и инициализирует эту структуру с помощью всех известных сведений о конфигурации, таких как номер системной шины ввода-вывода и значения, заданные драйвером мини-порта в структуре VIDEO_HW_INITIALIZATION_DATA .

Again

Должен игнорироваться драйвером мини-порта.

Возвращаемое значение

HwVidFindAdapter должен возвращать один из следующих кодов состояния:

Код возврата	Описание
ERROR_DEV_NOT_EXIST	Указывает, что для повторной шины драйверу мини-порта не удалось найти устройство.
ERROR_INVALID_PARAMETER	Указывает, что драйверу мини-порта не удалось успешно настроить или инициализировать адаптер.
NO_ERROR	Указывает на успешное завершение.

Выделяет хранилище для каждого адаптера драйвера мини-порта в соответствии со значением HwDeviceExtensionSize , указанной функцией DriverEntry драйвера мини-порта, указанной в структуре VIDEO_HW_INITIALIZATION_DATA , и ноль инициализирует выделенное хранилище.
Выделяет хранилище для структуры VIDEO_PORT_CONFIG_INFO и заполняет все доступные сведения на основе сведений о драйвере мини-порта в VIDEO_HW_INITIALIZATION_DATA.

Затем драйвер видеопорта вызывает функцию HwVidFindAdapter драйвера мини-порта с указателями на инициализированную область хранения адаптера и сведения о конфигурации в параметрах HwDeviceExtension и ConfigInfo соответственно.

Функция HwVidFindAdapter для устройств в перечисляемой шине должна выполнять следующие действия.

Проверьте размер структуры VIDEO_PORT_CONFIG_INFO, на которую указывает ConfigInfo , чтобы обеспечить правильное управление версиями.
Вызовите VideoPortGetAccessRanges , чтобы получить физические адреса относительно шины, на которые будет отвечать устройство. Эти адреса назначаются диспетчером PnP. Драйвер мини-порта должен передать значение NULL в параметрах VendorId, DeviceId и Slot в 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 . Эти сведения используются программой Display в панель управления. Дополнительные сведения см. в разделе Настройка сведений об оборудовании в реестре .

В зависимости от адаптера и значения AdapterInterfaceType в VIDEO_PORT_CONFIG_INFOHwVidFindAdapter может вызывать некоторые из следующих функций VideoPortXxx , чтобы получить необходимые данные конфигурации относительно шины и сопоставленные диапазоны доступа для взаимодействия с адаптером:

VideoPortGetBusData для получения сведений о конфигурации конкретного типа шины для адаптера на определенной шине ввода-вывода.
VideoPortGetDeviceData для получения VIDEO_DEVICE_DATA_TYPE сведений из реестра и вызова HwVidQueryDeviceCallback для обработки этих сведений.
VideoPortGetRegistryParameters для получения сведений о конфигурации из реестра.
VideoPortGetAccessRanges для получения адресов диапазонов доступа относительно шины и, возможно, других значений конфигурации оборудования, а также для их утверждения в реестре для использования драйвером адаптера.
VideoPortVerifyAccessRanges , чтобы определить, могут ли порты видеопамяти и (или) ввода-вывода для адаптера быть запрошены драйвером мини-порта; В противном случае ранее загруженный драйвер уже утверждал ресурс в реестре, и HwVidFindAdapter должен попытаться запросить другие диапазоны доступа, если это возможно или сбой.
VideoPortGetDeviceBase для сопоставления каждого успешно запрошенного базового адреса и размера диапазона относительно шины, как описано в структуре VIDEO_ACCESS_RANGE , с логическими адресами системного пространства . HwVidFindAdapter должен успешно вызвать VideoPortVerifyAccessRanges или VideoPortGetAccessRanges , прежде чем он сможет вызвать VideoPortGetDeviceBase.

Если драйвер не обрабатывает прерывания, HwVidFindAdapter должен задать для busInterruptLevel и BusInterruptVector в структуре VIDEO_PORT_CONFIG_INFO нулевое значение после вызова VideoPortGetAccessRanges. Если оба члена равны нулю, драйвер видеопорта не подключает прерывание для драйвера мини-порта. Если явно задать для busInterruptLevel и BusInterruptVector значение 0 в HwVidFindAdapter , точка входа HwVidInterrupt (если она есть) была настроена подпрограммой DriverEntry драйвера мини-порта.

HwVidFindAdapter не должен оставлять неподдерживаемый адаптер с измененным состоянием. Для адаптеров VGA/SVGA HwVidFindAdapter должен оставить адаптер в состоянии VGA и восстановить все расширенные регистры, которые он мог изменить до исходного состояния.

HwVidFindAdapter должен быть доступным для страниц.