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 マネージャーが検出したデバイスの種類を決定します。ミニポートドライバーは、PCI 構成情報を取得する VideoPortGetBusData を呼び出すことができます。
アダプター固有のデータを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 は、VideoPortGetDeviceBase を呼び出す前に、VideoPortVerifyAccessRanges または VideoPortGetAccessRanges を正常に呼び出す必要があります。

ドライバーが割り込みを処理しない場合、HwVidFindAdapterは、VideoPortGetAccessRanges の呼び出し後に、VIDEO_PORT_CONFIG_INFO構造体の BusInterruptLevel と BusInterruptVector の両方をゼロに設定する必要があります。両方のメンバーが 0 の場合、ビデオポートドライバーはミニポートドライバーの割り込みを接続しません。 HwVidFindAdapter で BusInterruptLevel と BusInterruptVector の両方を明示的にゼロに設定すると、ミニポートドライバーの DriverEntry ルーチンによって設定された HwVidInterrupt エントリポイント (存在する場合) が無効になります。

HwVidFindAdapter は、状態が変更された状態でサポートされていないアダプターを残してはなりません。 VGA/SVGA アダプターの場合、 HwVidFindAdapter はアダプターを VGA 状態のままにし、変更された可能性のある拡張レジスタを元の状態に復元する必要があります。

HwVidFindAdapter をページング可能にする必要があります。