PVIDEO_HW_FIND_ADAPTER fungsi panggilan balik (video.h)

Artikel
08/07/2023

HwVidFindAdapter melakukan inisialisasi data khusus untuk driver miniport dan perangkat yang didukung oleh driver miniport.

Sintaks

PVIDEO_HW_FIND_ADAPTER PvideoHwFindAdapter;

VP_STATUS PvideoHwFindAdapter(
  PVOID HwDeviceExtension,
  PVOID HwContext,
  PWSTR ArgumentString,
  PVIDEO_PORT_CONFIG_INFO ConfigInfo,
  PUCHAR Again
)
{...}

Parameter

HwDeviceExtension

Arahkan ke area penyimpanan per perangkat driver. Untuk informasi selengkapnya, lihat Ekstensi Perangkat.

HwContext

Adalah NULL dan harus diabaikan oleh driver miniport.

ArgumentString

Penunjuk ke string ASCII yang dihentikan null yang berasal dari pengguna. Penunjuk ini bisa NULL.

ConfigInfo

Penunjuk ke struktur VIDEO_PORT_CONFIG_INFO . Driver port video mengalokasikan memori untuk dan menginisialisasi struktur ini dengan informasi konfigurasi apa pun yang diketahui, seperti nomor bus IO sistem dan nilai yang ditetapkan driver miniport dalam struktur VIDEO_HW_INITIALIZATION_DATA .

Again

Harus diabaikan oleh driver miniport.

Nilai kembali

HwVidFindAdapter harus mengembalikan salah satu kode status berikut:

Menampilkan kode	Deskripsi
ERROR_DEV_NOT_EXIST	Menunjukkan, untuk bus yang dapat di-reenumerable, bahwa driver miniport tidak dapat menemukan perangkat.
ERROR_INVALID_PARAMETER	Menunjukkan driver miniport tidak berhasil mengonfigurasi atau menginisialisasi adapter.
NO_ERROR	Menunjukkan keberhasilan.

Keterangan

Setiap driver miniport video harus memiliki fungsi HwVidFindAdapter .

Driver port video melakukan hal berikut sebelum memanggil HwVidFindAdapter:

Mengalokasikan penyimpanan untuk area penyimpanan per adaptor driver miniport sesuai dengan nilai HwDeviceExtensionSize bahwa fungsi DriverEntry driver miniport yang ditentukan dalam struktur VIDEO_HW_INITIALIZATION_DATA , dan nol menginisialisasi penyimpanan yang dialokasikan.
Mengalokasikan penyimpanan untuk struktur VIDEO_PORT_CONFIG_INFO dan mengisi semua informasi yang tersedia berdasarkan informasi yang disediakan pengemudi miniport dalam VIDEO_HW_INITIALIZATION_DATA.

Driver port video kemudian memanggil fungsi HwVidFindAdapter driver miniport dengan pointer ke area penyimpanan per adaptor yang diinisialisasi dan informasi konfigurasi dalam parameter HwDeviceExtension dan ConfigInfo .

Fungsi HwVidFindAdapter untuk perangkat pada bus enumerable harus melakukan hal berikut:

Periksa ukuran struktur VIDEO_PORT_CONFIG_INFO yang menunjuk ConfigInfo untuk memastikan penerapan versi yang tepat.
Panggil VideoPortGetAccessRanges untuk mendapatkan alamat fisik relatif bus tempat perangkat akan merespons. Alamat ini ditetapkan oleh manajer PnP. Driver miniport harus melewati NULL di parameter VendorId, DeviceId, dan SlotVideoPortGetAccessRanges.
Untuk driver miniport yang mendukung beberapa jenis perangkat, tentukan jenis perangkat yang telah terdeteksi oleh manajer PnP. Driver miniport dapat memanggil VideoPortGetBusData untuk mendapatkan informasi konfigurasi PCI.
Isi informasi konfigurasi yang relevan tetapi hilang di anggota struktur VIDEO_PORT_CONFIG_INFO yang sesuai dengan data khusus adaptor.

HwVidFindAdapter tidak boleh mencoba menginisialisasi perangkat.

HwVidFindAdapter dapat mengalokasikan sumber daya, seperti memori dan kunci, untuk digunakan oleh driver miniport. Sumber daya tersebut dapat spesifik untuk perangkat atau dapat dibagikan oleh beberapa perangkat yang didukung driver miniport. Jika HwVidFindAdapter mengembalikan nilai apa pun selain NO_ERROR, HwVidFindAdapter harus membebaskan semua sumber daya khusus perangkat sebelum kembali. Untuk sumber daya yang dibagikan di antara beberapa perangkat, HwVidFindAdapter harus menyimpan jumlah referensi. Misalnya, jumlah referensi dapat menunjukkan jumlah panggilan sebelumnya ke HwVidFindAdapter yang berhasil. Dengan begitu, jika HwVidFindAdapter harus gagal, dan menentukan bahwa semua panggilan sebelumnya ke HwVidFindAdapter telah gagal, itu dapat membebaskan sumber daya bersama.

Jika HwVidFindAdapter gagal setiap kali dipanggil oleh driver port video, sistem operasi mungkin membongkar driver miniport nanti. Dalam kasus seperti itu, sumber daya apa pun yang dialokasikan HwVidFindAdapter tetapi tidak gratis akan bocor.

Untuk perangkat pada bus yang dapat dihidupkan kembali seperti ISA, PnP masih mencoba memulai perangkat, meskipun HwVidFindAdapter bertanggung jawab untuk menentukan apakah perangkat benar-benar ada. Jika perangkat tidak ditemukan, HwVidFindAdapter harus mengembalikan ERROR_DEV_NOT_EXIST.

HwVidFindAdapter juga harus memanggil VideoPortSetRegistryParameters untuk menyimpan informasi khusus adaptor di kunci HardwareInformation . Informasi ini digunakan oleh program Tampilan dalam Panel Kontrol. Lihat Mengatur Informasi Perangkat Keras di Registri untuk detailnya.

Bergantung pada adaptor dan nilai AdapterInterfaceType dalam VIDEO_PORT_CONFIG_INFO, HwVidFindAdapter dapat memanggil beberapa fungsi VideoPortXxx berikut untuk mendapatkan data konfigurasi relatif bus yang diperlukan dan rentang akses yang dipetakan untuk berkomunikasi dengan adaptor:

VideoPortGetBusData untuk mendapatkan informasi konfigurasi khusus jenis bus tentang adaptor pada bus I/O tertentu.
VideoPortGetDeviceData untuk mendapatkan informasi khusus VIDEO_DEVICE_DATA_TYPE dari registri dan memanggil HwVidQueryDeviceCallback untuk memproses informasi ini.
VideoPortGetRegistryParameters untuk mendapatkan informasi konfigurasi dari registri.
VideoPortGetAccessRanges untuk mendapatkan alamat rentang akses relatif bus dan mungkin nilai konfigurasi perangkat keras lainnya, dan untuk mengklaimnya di registri untuk digunakan oleh driver adaptor.
VideoPortVerifyAccessRanges untuk menentukan apakah memori video relatif bus dan/atau port I/O untuk adaptor dapat diklaim oleh driver miniport; jika tidak, driver yang dimuat sebelumnya telah mengklaim sumber daya dalam registri dan HwVidFindAdapter harus mencoba mengklaim rentang akses lain jika memungkinkan atau gagal.
VideoPortGetDeviceBase untuk memetakan setiap alamat dasar dan ukuran rentang relatif bus yang berhasil diklaim, seperti yang dijelaskan dalam struktur VIDEO_ACCESS_RANGE , ke alamat logis ruang sistem . HwVidFindAdapter harus berhasil memanggil VideoPortVerifyAccessRanges atau VideoPortGetAccessRanges sebelum dapat memanggil VideoPortGetDeviceBase.

Jika driver tidak menangani gangguan, HwVidFindAdapter harus mengatur BusInterruptLevel dan BusInterruptVector dalam struktur VIDEO_PORT_CONFIG_INFO ke nol setelah panggilannya ke VideoPortGetAccessRanges. Jika kedua anggota nol, driver port video tidak menghubungkan gangguan untuk driver miniport. Secara eksplisit mengatur BusInterruptLevel dan BusInterruptVector ke nol di HwVidFindAdapter menonaktifkan titik masuk HwVidInterrupt , jika ada, yang disiapkan oleh rutinitas DriverEntry driver miniport.

HwVidFindAdapter tidak boleh meninggalkan adaptor yang tidak didukung dengan statusnya berubah. Untuk adaptor VGA/SVGA, HwVidFindAdapter harus meninggalkan adaptor dalam status VGA dan memulihkan register yang diperluas yang mungkin telah dimodifikasi ke kondisi aslinya.

HwVidFindAdapter harus dibuat dapat di-pageable.