KBUGCHECK_CALLBACK_ROUTINE fungsi panggilan balik (wdm.h)

Artikel
03/08/2023

Rutinitas BugCheckCallback dijalankan setiap kali sistem mengeluarkan pemeriksaan bug.

Fungsi panggilan balik KBUGCHECK_REASON_CALLBACK_ROUTINE menawarkan lebih banyak fungsionalitas daripada panggilan balik yang lebih lama ini.

Sintaks

KBUGCHECK_CALLBACK_ROUTINE KbugcheckCallbackRoutine;

void KbugcheckCallbackRoutine(
  [in] IN PVOID Buffer,
  [in] IN ULONG Length
)
{...}

Parameter

[in] Buffer

Penunjuk ke buffer yang ditentukan ketika panggilan balik didaftarkan.

[in] Length

Menentukan panjang, dalam byte, dari buffer yang diacu oleh parameter Buffer .

Nilai kembali

Tidak ada

Keterangan

Driver dapat menyediakan BugCheckCallback yang mengatur ulang perangkat ke keadaan yang diketahui jika sistem mengeluarkan pemeriksaan bug.

Gunakan KeRegisterBugCheckCallback untuk mendaftarkan rutinitas BugCheckCallback . Driver kemudian dapat menghapus panggilan balik dengan menggunakan rutinitas KeDeregisterBugCheckCallback . Jika driver dapat dibongkar, driver harus menghapus panggilan balik terdaftar dalam rutinitas Bongkar .

Rutinitas BugCheckCallback sangat dibatasi dalam tindakan yang dapat dilakukannya. Untuk informasi selengkapnya, lihat Menulis Rutinitas Panggilan Balik Pemeriksaan Bug. Rutinitas dapat dengan aman menggunakan rutinitas READ_PORT_XXXX, READ_REGISTER_XXX, WRITE_PORT_XXX, dan WRITE_REGISTER_XXX untuk berinteraksi dengan perangkat.

Driver yang membutuhkan interaksi yang lebih canggih dengan sistem karena mengeluarkan pemeriksaan bug dapat mengimplementasikan rutinitas KbCallbackDumpIo atau KbCallbackSecondaryDumpData.

Perhatikan bahwa dimulai dengan sistem operasi Windows XP SP1 dan Windows Server 2003, rutinitas BugCheckCallback dijalankan setelah file crash dump sistem telah ditulis. (Pada versi Windows yang lebih lama, rutinitas dijalankan sebelum file crash dump ditulis.) Dengan demikian, data apa pun yang disimpan dalam buffer yang ditentukan oleh parameter Buffer tidak akan muncul dalam file crash dump. Driver yang diperlukan untuk menulis data ke file crash dump sebagai gantinya menerapkan rutinitas KbCallbackSecondaryDumpData. (Pada versi Windows yang lebih lama, data yang ditulis ke Buffer memang muncul di file crash dump.)

Contoh

Untuk menentukan rutinitas panggilan balik BugCheckCallback , Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis rutinitas panggilan balik yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi panggilan balik untuk pengandar. Mendeklarasikan fungsi menggunakan jenis fungsi panggilan balik membantu Analisis Kode untuk Driver, Pemverifikasi Driver Statis (SDV), dan alat verifikasi lainnya menemukan kesalahan, dan itu adalah persyaratan untuk menulis driver untuk sistem operasi Windows.

Misalnya, untuk menentukan rutinitas panggilan balik BugCheckCallback yang diberi nama MyBugCheckCallback, gunakan jenis KBUGCHECK_CALLBACK_ROUTINE seperti yang ditunjukkan dalam contoh kode ini:

KBUGCHECK_CALLBACK_ROUTINE MyBugCheckCallback;

Kemudian, terapkan rutinitas panggilan balik Anda sebagai berikut:

_Use_decl_annotations_
VOID
  MyBugCheckCallback(
    PVOID  Buffer,
    ULONG  Length
    )
  {
      // Function body
  }

Jenis fungsi KBUGCHECK_CALLBACK_ROUTINE ditentukan dalam file header Wdm.h. Untuk mengidentifikasi kesalahan secara lebih akurat saat Anda menjalankan alat analisis kode, pastikan untuk menambahkan anotasi Use_decl_annotations ke definisi fungsi Anda. Anotasi Use_decl_annotations memastikan bahwa anotasi yang diterapkan ke jenis fungsi KBUGCHECK_CALLBACK_ROUTINE dalam file header digunakan. Untuk informasi selengkapnya tentang persyaratan untuk deklarasi fungsi, lihat Mendeklarasikan Fungsi dengan Menggunakan Jenis Peran Fungsi untuk Driver WDM. Untuk informasi tentang Use_decl_annotations, lihat Perilaku Fungsi Anotasi.