HwVidFindAdapter

VP_STATUS HwVidFindAdapter(

PVOID  HwDeviceExtension,
PVOID  HwContext,
PWSTR  ArgumentString,
PVIDEO_PORT_CONFIG_INFO  ConfigInfo,
PUCHAR  Again
);

Every video miniport driver must have a HwVidFindAdapter function. The system video port driver calls HwVidFindAdapter when the miniport’s DriverEntry function has called VideoPortInitialize.

Parameters

HwDeviceExtension

Points to the miniport driver’s per-adapter storage area. The video port driver allocates memory for and initializes this extension with zeros before it calls the miniport’s HwVidFindAdapter function.

HwContext

Points to the optional context value passed to VideoPortInitialize by DriverEntry. This pointer can be NULL.

ArgumentString

Points to a zero-terminated ASCII string. This string originates with the user, and this pointer can be NULL.

ConfigInfo

Points to a VIDEO_PORT_CONFIG_INFO structure. The port driver allocates memory for and initializes this structure with any known configuration information, such as values the miniport set in the VIDEO_HW_INITIALIZATION_DATA and the SystemIoBusNumber.

Again

Points to a variable that HwVidFindAdapter sets to TRUE if it should be called again with a new DeviceExtension and ConfigInfo. Set this to FALSE if the miniport can support only a single video adapter on a given I/O bus.

Return Value

HwVidFindAdapter must return one of the following status codes:

Value	Meaning
NO_ERROR	Indicates a supported adapter was found and that the adapter-relevant configuration information was successfully determined, set up, and supplied in the VIDEO_PORT_CONFIG_INFO structure.
ERROR_DEV_NOT_EXIST	Indicates the miniport driver found no adapter it supports on the given I/O bus.
ERROR_INVALID_PARAMETER	Indicates the miniport driver does not support the adapter described by the input VIDEO_PORT_CONFIG_INFO or that it could not configure or initialize the adapter successfully.

Comments

VideoPortInitialize calls the HwVidFindAdapter function after allocating storage for the HwDeviceExtension according to the HwDeviceExtensionSize that the miniport’s DriverEntry function specified in the VIDEO_HW_INITIALIZATION_DATA structure.

VideoPortInitialize also allocates the storage for the configuration information buffer. It fills in all available VIDEO_PORT_CONFIG_INFO information, based on miniport-supplied information in the VIDEO_HW_INITIALIZATION_DATA, before calling HwVidFindAdapter.

HwVidFindAdapter must use any supplied configuration information to determine if the video adapter that the input VIDEO_PORT_CONFIG_INFO describes is one that the miniport supports. HwVidFindAdapter cannot access an adapter described by VIDEO_PORT_CONFIG_INFO without setting up and claiming access ranges for device memory, possibly getting and claiming interrupt configuration information for its adapter, and mapping bus-relative access range values to system logical addresses.

Depending on the adapter and the AdapterInterfaceType value in VIDEO_PORT_CONFIG_INFO, HwFindAdapter can call some of the following VideoPortXxx to get the necessary bus-relative configuration data and mapped access ranges to communicate with the adapter:

• VideoPortGetBusData

• VideoPortGetDeviceData

• VideoPortGetRegistryParameters

• VideoPortGetAccessRanges

• VideoPortVerifyAccessRanges

• VideoPortGetDeviceBase

The hardware configuration information returned by VideoPortGetBusData can be more complete than that stored in the registry by the system loader and retrieved by VideoPortGetDeviceData. If possible, a miniport driver should have a set of default bus-relative configuration information, if it cannot get sufficient configuration information from the port driver and/or the registry.

Every HwVidFindAdapter function must successfully call either VideoPortVerifyAccessRanges or VideoPortGetAccessRanges before it can call VideoPortGetDeviceBase to map bus-relative device access ranges to system-assigned logical addresses.

A miniport driver can communicate with an adapter only by passing a mapped logical address to the VideoPortRead/WriteXxx functions. If HwVidFindAdapter determines that an adapter is not one that the miniport supports, it must call VideoPortFreeDeviceBase to release the mapped access ranges before it returns control. It also must release the bus-relative ranges it has claimed in the registry for such an adapter by calling VideoPortVerifyAccessRanges.

Note that HwVidFindAdapter must not leave such an unsupported adapter with its state changed. For VGA/SVGA adapters, the miniport must leave the adapter in a VGA state and must restore any extended registers it might have modified to their original condition.

HwVidFindAdapter must fill in any relevant but missing configuration information for an adapter it supports in the ConfigInfo buffer and set the value of Again before it returns control. Setting Again to FALSE does not prevent VideoPortInitialize from calling HwVidFindAdapter again for another I/O bus (with a different SystemIoBusNumber) of the same AdapterInterfaceType.

If a miniport driver’s HwVidFindAdapter function finds that the video adapter does not generate interrupts or that it cannot determine a valid interrupt vector/level for the adapter, HwVidFindAdapter should set both InterruptLevel and InterruptVector in the VIDEO_PORT_CONFIG_INFO structure to zero.

When HwVidFindAdapter returns control, the video port driver checks the interrupt configuration members of VIDEO_PORT_CONFIG_INFO and if both are zero, does not connect the interrupt for the miniport driver. Explicitly setting both InterruptLevel and InterruptVector to zero in HwVidFindAdapter disables the HwVidInterrupt entry point, if any, that was set up by the miniport driver’s DriverEntry routine.

See Also

DriverEntry, HwVidQueryDeviceCallback, HwVidQueryNamedValueCallback, VIDEO_HW_INITIALIZATION_DATA, VIDEO_PORT_CONFIG_INFO, VideoPortFreeDeviceBase, VideoPortGetAccessRanges, VideoPortGetBusData, VideoPortGetDeviceBase, VideoPortGetDeviceData, VideoPortGetRegistryParameters, VideoPortVerifyAccessRanges