DXGKDDI_GETDISPLAYSTATENONINTRUSIVE fungsi panggilan balik (dispmprt.h)

Artikel
03/10/2023

Sistem operasi memanggil rutinitas DxgkDdiGetDisplayStateNonIntrusive driver miniport tampilan untuk mengumpulkan informasi status tampilan secara tidak jelas dari driver.

Sintaks

DXGKDDI_GETDISPLAYSTATENONINTRUSIVE DxgkddiGetdisplaystatenonintrusive;

NTSTATUS DxgkddiGetdisplaystatenonintrusive(
  [in]     HANDLE Context,
  [in/out] PDXGKARG_GETDISPLAYSTATENONINTRUSIVE pArgs
)
{...}

Parameter

[in] Context

Penunjuk ke konteks privat yang dikembalikan oleh DxgkDdiQueryInterface.

[in/out] pArgs

Arahkan ke struktur DXGKARG_GETDISPLAYSTATENONINTRUSIVE .

Nilai kembali

DxgkDdiGetDisplayStateNonIntrusive mengembalikan STATUS_SUCCESS jika berhasil. Jika tidak, kode kesalahan akan dikembalikan seperti salah satu hal berikut ini.

Kode Kesalahan	Makna
STATUS_DRIVER_INTERNAL_ERROR	Terjadi kesalahan perangkat lunak generik di dalam driver.
STATUS_ACCESS_DENIED	Perangkat keras saat ini sedang digunakan oleh utas lain dan DDI ini tidak bisa mendapatkan akses ke dalamnya.
STATUS_DEVICE_HARDWARE_ERROR	Terjadi kesalahan HW generik.
STATUS_DEVICE_POWERED_OFF	Perangkat dimatikan.

Keterangan

OS memanggil DxgkDdiGetDisplayStateNonIntrusive untuk mengumpulkan informasi status tampilan dari driver. Tidak seperti DxgkDdiGetDisplayStateIntrusive, rutinitas DxgkDdiGetDisplayStateNonIntrusive driver tidak boleh melakukan operasi apa pun yang menyebabkan efek samping yang terlihat bagi pengguna, dan proses pengumpulan harus relatif cepat (idealnya dalam beberapa milidetik). Frekuensi panggilan rutin ini akan relatif tinggi. Selain dipanggil untuk mendiagnosis status pengguna yang buruk, OS mungkin juga menggunakan rutinitas ini untuk merekam informasi status historis dari driver untuk tujuan penelusuran kesalahan.

Dalam kasus yang jarang terjadi ketika implementasi khusus platform mengharuskan driver untuk melakukan operasi yang mengganggu sebagai bagian dari panggilan ke DxgkDdiGetDisplayStateNonIntrusive, driver harus melakukan operasi tetapi harus mengatur pArgs-ReturnSubStatus> ke DXGK_DIAG_GETDISPLAYSTATE_CAUSED_GLITCH atau DXGK_DIAG_GETDISPLAYSTATE_CHANGED_DISPLAY_STATE yang sesuai. Berdasarkan nilai ReturnSubStatus , sistem operasi (OS) mungkin hanya memanggil rutinitas ini untuk skenario kesalahan pada sistem tertentu.

OS akan sering memanggil DxgkDdiGetDisplayStateNonIntrusive (baik secara berkala atau pada peristiwa lain yang umum terjadi) untuk mengumpulkan data status driver untuk tujuan penelusuran kesalahan dan melihat garis waktu historis. OS juga akan memanggil rutinitas ini dalam skenario kesalahan tertentu (seperti layar hitam) sebelum mengumpulkan informasi yang lebih rinci dengan memanggil DxgkDdiGetDisplayStateIntrusive. Mengingat kemungkinan frekuensi panggilan ini, driver harus menyelesaikannya secepat mungkin. OS akan memanggil DDI ini dengan NumOfTargets diatur ke jumlah maksimum target yang didukung oleh adaptor grafis yang diberikan dan VidPnTargetId yang diisi. Driver miniport hanya boleh mengisi informasi status tampilan untuk target di mana sebenarnya ada monitor yang terhubung. Untuk vidpntarget di mana tidak ada monitor yang terhubung, miniport hanya boleh mengisi DXGK_DIAG_DISPLAY_CONNECTIVITY dan OS akan mengabaikan semua bidang lain untuk target tersebut.

Catatan

Driver hanya boleh menggunakan ReturnSubStatus untuk melaporkan kondisi kesalahan dan tidak menggunakan DXGK_DIAG_GETDISPLAYSTATE_MONITOR_NOT_CONNECTED untuk melaporkan status konektivitas monitor. Tujuan utama DXGK_DIAG_GETDISPLAYSTATE_MONITOR_NOT_CONNECTED adalah untuk panggilan intrusif di mana OS tidak bertanya tentang konektivitas monitor.

Jika driver mengalami kegagalan pada vidpntarget tertentu saat mengumpulkan informasi, driver harus menggunakan ReturnSubStatus untuk mengatur status kesalahan dan melanjutkan ke vidpntarget berikutnya dan tidak gagal dalam panggilan keseluruhan kecuali semua jalur mengalami kegagalan. Driver idealnya harus merekam kesalahan yang terjadi selama panggilan ini dalam beberapa log kesalahan internal sehingga ketika OS memanggil DxgkDdiCollectDiagnosticInfo untuk mengumpulkan informasi kotak hitam, kesalahan ini ditangkap sebagai bagian dari koleksi log internal untuk membantu IHV selama debug.

Tingkat sinkronisasi untuk DDI ini adalah sinkronisasi tingkat nol.