struktur VIDEO_ACCESS_RANGE (video.h)

Artikel
08/08/2023

Struktur VIDEO_ACCESS_RANGE mendefinisikan port I/O perangkat atau rentang memori untuk adaptor video. Setiap fungsi HwVidFindAdapter driver miniport harus menyiapkan array elemen jenis VIDEO_ACCESS_RANGE, yang disebut array rentang akses, untuk setiap adaptor video yang didukung driver miniport.

Untuk driver miniport yang kompatibel dengan VGA, VIDEO_ACCESS_RANGE juga mendefinisikan elemen dalam array yang diteruskan ke VideoPortSetTrappedEmulatorPorts untuk mengaktifkan atau menonaktifkan akses langsung ke port I/O oleh aplikasi MS-DOS layar penuh.

Sintaks

typedef struct _VIDEO_ACCESS_RANGE {
  PHYSICAL_ADDRESS RangeStart;
  ULONG            RangeLength;
  UCHAR            RangeInIoSpace;
  UCHAR            RangeVisible;
  UCHAR            RangeShareable;
  UCHAR            RangePassive;
} VIDEO_ACCESS_RANGE, *PVIDEO_ACCESS_RANGE;

Anggota

RangeStart

Menentukan alamat dasar relatif bus dari memori atau rentang port I/O untuk elemen dalam array rentang akses yang diteruskan ke VideoPortVerifyAccessRanges atau dikembalikan oleh VideoPortGetAccessRanges.

Menentukan alamat dasar relatif bus dari rentang port I/O untuk array yang akan diteruskan ke VideoPortSetTrappedEmulatorPorts.

RangeLength

Menentukan jumlah port atau ukuran I/O dalam byte untuk rentang tersebut.

RangeInIoSpace

Menentukan apakah rentang berada dalam ruang I/O atau di ruang memori. Nilai TRUE (1) menunjukkan bahwa rentang berada dalam spasi I/O; nilai FALSE (0) menunjukkan rentang berada di ruang memori.

RangeVisible

Diabaikan jika fungsi HwVidFindAdapter driver miniport menyiapkan array rentang akses.

Diatur ke TRUE oleh driver miniport yang kompatibel dengan VGA dan diteruskan ke VideoPortSetTrappedEmulatorPorts untuk mengaktifkan akses langsung ke rentang port I/O oleh aplikasi MS-DOS layar penuh. Jika diatur ke FALSE, instruksi yang dikeluarkan aplikasi terus terjebak dan diteruskan ke fungsi SvgaHwIoXxx driver miniport untuk validasi.

RangeShareable

Diatur ke TRUE jika rentang akses yang dijelaskan oleh elemen ini dapat dibagikan dengan driver dan/atau perangkat lain atau ke FALSE jika rentang tidak dapat dibagikan.

Diabaikan oleh VideoPortSetTrappedEmulatorPorts.

RangePassive

Menunjukkan apakah perangkat benar-benar menggunakan port. Nilai untuk anggota ini diperlihatkan dalam tabel berikut ini.

Nilai	Makna
VIDEO_RANGE_PASSIVE_DECODE	Perangkat mendekode porta tetapi driver tidak menggunakannya.
VIDEO_RANGE_10_BIT_DECODE	Perangkat mendekode sepuluh bit alamat port.

Keterangan

Driver miniport harus mengklaim sumber daya warisan dalam fungsi DriverEntry atau HwVidLegacyResources .

Jika tidak, fungsi HwVidFindAdapter driver miniport menyiapkan array rentang akses untuk sumber daya PCI adaptor. Ini dapat menggunakan informasi yang dikembalikan oleh VideoPortGetAccessRanges. Sebagai alternatif, ia dapat menggunakan informasi yang diambil dari registri dengan memanggil VideoPortGetDeviceData dengan fungsi HwVidQueryDeviceCallback yang disediakan driver miniport atau VideoPortGetRegistryParameters dengan fungsi HwVidQueryNamedValueCallback yang disediakan driver miniport. Jika memanggil VideoPortXxx ini tidak menyediakan nilai rentang akses relatif bus, HwVidFindAdapter dapat mengatur elemen rentang akses menggunakan nilai default relatif bus yang disediakan driver.

Mengklaim Rentang Akses di Registri

Driver miniport harus memanggil VideoPortVerifyAccessRanges dengan rentang akses apa pun yang diperoleh dari VideoPortGetDeviceData, VideoPortGetAccessRanges, atau disediakan sebagai default oleh driver miniport. Jika VideoPortVerifyAccessRanges mengembalikan NO_ERROR untuk array rentang akses seperti itu, fungsi HwVidFindAdapter atau HwVidQueryDeviceCallback kemudian dapat memetakan rentang dengan VideoPortGetDeviceBase dan menggunakan alamat logika yang dipetakan yang dikembalikan untuk mengakses adaptor.

Panggilan yang berhasil ke VideoPortGetAccessRanges juga mengklaim rentang akses relatif bus yang dikembalikan dalam registri untuk pemanggil. Jika driver miniport memodifikasi salah satu nilai yang dikembalikan, driver miniport harus memanggil VideoPortVerifyAccessRanges dengan rentang akses penuh, termasuk elemen yang tidak dimodifikasi. Setiap panggilan ke VideoPortGetAccessRanges atau VideoPortVerifyAccessRanges untuk adaptor video tertentu menimpa sumber daya perangkat keras pemanggil yang diklaim di registri.

Driver miniport tidak boleh mencoba menggunakan rentang di mana VideoPortVerifyAccessRanges atau VideoPortGetAccessRanges tidak mengembalikan NO_ERROR.

Memetakan Rentang Akses untuk Berkomunikasi dengan Adapter

Setelah driver miniport mengklaim sumber daya dalam registri untuk adaptor, driver tersebut tidak dapat menggunakan alamat relatif bus untuk mengakses atau mengonfigurasi adaptor, karena HAL dapat memetakan ulang semua alamat perangkat relatif bus ke ruang sistem.

Fungsi HwVidFindAdapter driver miniport harus memanggil VideoPortGetDeviceBase untuk mendapatkan alamat logis yang dipetakan untuk rentang aksesnya. Hanya dengan begitu driver miniport dapat berkomunikasi dengan adaptor video dengan meneruskan alamat rentang logis yang dipetakan yang dikembalikan ke VideoPortRead/WritePortXxx untuk mengakses memori perangkat di ruang I/O dan/atau VideoPortRead/WriteRegisterXxx untuk mengakses memori perangkat di ruang memori.

Menentukan apakah Rentang Akses Dapat Dibagi

Ikuti panduan ini untuk menentukan apakah rentang akses dapat dibagikan:

Jika rentang memori atau port I/O harus "dimiliki" oleh driver ini, dan/atau akses ke rentang ini oleh driver lain dapat menyebabkan masalah, atur RangeSharable ke FALSE.
Jika rentang dapat dibagikan dengan driver perangkat yang bekerja sama, atur RangeSharable ke TRUE.

Driver miniport SVGA yang mengimplementasikan semua fungsi VGA (dinyatakan dalam registri sebagai VgaCompatible diatur ke satu) harus mengklaim rentang akses mereka sebagai tidak dapat dibagikan sehingga driver VGA sistem tidak akan dimuat. Di sisi lain, driver miniport untuk adaptor seperti S3 atau XGA, yang mengatur VgaCompatible ke nol di registri, harus mengklaim semua sumber daya yang mereka bagikan dengan driver VGA sistem sebagai dapat dibagikan.

Namun, driver miniport untuk kartu yang bekerja dengan IOCTL pass-through dan yang dapat dihubungkan ke kartu VGA atau SVGA apa pun tidak boleh menggunakan port VGA sistem atau rentang memori apa pun. Jika mereka melakukannya, driver seperti itu tidak boleh mencoba untuk mengklaim rentang akses VGA apa pun di registri. Upaya untuk mengklaim sumber daya VGA oleh driver miniport seperti itu kemungkinan menyebabkan konflik sumber daya karena driver kartu SVGA apa pun di komputer akan mengklaim rentang akses ini sebagai tidak dapat dibagikan.

Meneruskan Elemen Rentang Port I/O ke VideoPortSetTrappedEmulatorPorts

Semua elemen array jenis VIDEO_ACCESS_RANGE yang menjelaskan rentang port I/O diasumsikan tidak terlihat, kecuali driver miniport yang kompatibel dengan VGA di komputer berbasis x86 secara eksplisit mengatur ulang anggota RangeVisible ke TRUE dan memanggil VideoPortSetTrappedEmulatorPorts untuk mengaktifkan satu atau beberapa rentang port I/O. VideoPortSetTrappedEmulatorPorts mengabaikan anggota RangeSharable dari array input.

Dalam array elemen jenis VIDEO_ACCESS_RANGE yang diteruskan ke VideoPortSetTrappedEmulatorPorts, nilai dari setiap anggota RangeVisible elemen menentukan apakah port I/O yang diberikan dapat diakses langsung oleh VDM (aplikasi MS-DOS yang berjalan di layar penuh pada mesin berbasis x86) atau apakah aliran I/O yang dikeluarkan aplikasi tersebut terjebak dan diteruskan ke fungsi SvgaHwIoPortXxx yang disediakan driver miniport untuk validasi terlebih dahulu.