Fungsi KeRegisterProcessorChangeCallback (wdm.h)

Rutinitas KeRegisterProcessorChangeCallback mendaftarkan fungsi panggilan balik dengan sistem operasi sehingga sistem operasi akan memberi tahu driver ketika prosesor baru ditambahkan ke partisi perangkat keras.

Sintaks

PVOID KeRegisterProcessorChangeCallback(
  [in]           PPROCESSOR_CALLBACK_FUNCTION CallbackFunction,
  [in, optional] PVOID                        CallbackContext,
  [in]           ULONG                        Flags
);

Parameter

[in] CallbackFunction

Penunjuk ke fungsi panggilan balik perubahan prosesor yang disediakan driver yang akan dipanggil oleh sistem operasi setiap kali prosesor baru ditambahkan ke partisi perangkat keras. Fungsi panggilan balik perubahan prosesor didefinisikan sebagai berikut:

VOID
  ProcessorCallback(
    __in PVOID CallbackContext,
    __in PKE_PROCESSOR_CHANGE_NOTIFY_CONTEXT ChangeContext,
    __inout PNTSTATUS OperationStatus
    );

CallbackContext

Konteks yang disediakan dalam parameter CallbackContext ke rutinitas KeRegisterProcessorChangeCallback ketika fungsi panggilan balik didaftarkan ke sistem operasi.

ChangeContext

Penunjuk ke struktur KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT yang menjelaskan peristiwa pemberitahuan perubahan prosesor.

OperationStatus

Penunjuk ke variabel yang berisi kode NTSTATUS. Driver perangkat tidak boleh mengubah nilai variabel ini kecuali jika terjadi kesalahan selama pemrosesan fungsi panggilan balik ketika anggota Status dari struktur KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT yang diacu oleh parameter ChangeContext berisi KeProcessorAddStartNotify.

Fungsi panggilan balik perubahan prosesor dipanggil di IRQL = PASSIVE_LEVEL.

[in, optional] CallbackContext

Konteks yang disediakan driver yang diteruskan ke fungsi panggilan balik. Parameter ini bisa NULL.

[in] Flags

Bendera opsional yang memodifikasi perilaku rutinitas KeRegisterProcessorChangeCallback . Berikut ini adalah salah satu bendera yang mungkin:

KE_PROCESSOR_CHANGE_ADD_EXISTING

Jika bendera ini diatur, fungsi panggilan balik terdaftar segera dipanggil untuk setiap prosesor aktif yang saat ini ada di partisi perangkat keras, selain dipanggil setiap kali prosesor baru ditambahkan ke partisi perangkat keras. Jika bendera ini tidak diatur, fungsi panggilan balik terdaftar hanya dipanggil setiap kali prosesor baru ditambahkan ke sistem.

Nilai kembali

KeRegisterProcessorChangeCallback mengembalikan handel pendaftaran panggilan balik non-NULL jika fungsi panggilan balik berhasil didaftarkan ke sistem operasi. Jika tidak, KeRegisterProcessorChangeCallback mengembalikan NULL. Untuk informasi selengkapnya tentang handel ini, lihat bagian Keterangan berikut ini.

Keterangan

Driver perangkat memanggil rutinitas KeRegisterProcessorChangeCallback untuk mendaftarkan fungsi panggilan balik yang akan dipanggil oleh sistem operasi setiap kali prosesor baru ditambahkan ke partisi perangkat keras. Ketika pengguna melakukan hot-plug prosesor baru ke dalam partisi, sistem operasi memanggil fungsi panggilan balik terdaftar untuk menyeimbangkan kembali sumber daya sistem yang dialokasikan di antara prosesor dalam partisi.

Fungsi panggilan balik terdaftar dipanggil dua kali setiap kali prosesor baru ditambahkan ke partisi perangkat keras. Pertama kali fungsi panggilan balik dipanggil, anggota Status dari struktur KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT yang ditujukkan oleh parameter ChangeContext berisi KeProcessorAddStartNotify. Selama panggilan balik inilah driver perangkat harus mengalokasikan sumber daya per prosesor apa pun dan melakukan tugas lain sebagai persiapan bagi prosesor baru untuk menjadi aktif dalam partisi perangkat keras. Jika terjadi kesalahan saat driver perangkat memproses panggilan balik ini yang dapat menyebabkan bugcheck terjadi jika sistem operasi terus menambahkan prosesor baru ke partisi perangkat keras, fungsi panggilan balik mengatur variabel yang diacu oleh parameter OperationStatus ke kode NTSTATUS yang menjelaskan kondisi kesalahan. Misalnya, jika driver perangkat mengalami kegagalan alokasi memori untuk struktur data per prosesor untuk prosesor baru, fungsi panggilan balik mengatur variabel ini ke STATUS_INSUFFICIENT_RESOURCES. Jika panggilan balik berhasil diproses, konten variabel yang ditujukkan oleh parameter OperationStatus tidak boleh diubah.

Kedua kalinya fungsi panggilan balik dipanggil, anggota Status dari struktur KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT yang ditunjukkan oleh parameter ChangeContext berisi KeProcessorAddCompleteNotify, yang menunjukkan bahwa sistem operasi telah menambahkan prosesor baru ke partisi perangkat keras dengan sukses, atau KeProcessorAddFailureNotify, yang menunjukkan bahwa sistem operasi tidak menambahkan prosesor baru ke partisi perangkat keras. Jika sistem operasi berhasil menambahkan prosesor baru ke partisi perangkat keras, fungsi panggilan balik tidak dipanggil untuk kedua kalinya sampai setelah prosesor baru dimulai dan tersedia untuk penjadwalan utas. Jika sistem operasi tidak menambahkan prosesor baru ke partisi perangkat keras, driver perangkat harus membebaskan sumber daya per prosesor selama panggilan balik kedua yang dialokasikan selama panggilan balik pertama.

Jika driver perangkat menentukan bendera KE_PROCESSOR_CHANGE_ADD_EXISTING dalam parameter Bendera saat memanggil rutinitas KeRegisterProcessorChangeCallback , fungsi panggilan balik segera dipanggil satu kali untuk setiap prosesor aktif yang saat ini ada di partisi perangkat keras. Untuk panggilan balik ini, anggota Status struktur KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT yang ditujukkan oleh parameter ChangeContext berisi KeProcessorAddStartNotify. Selama panggilan balik inilah driver perangkat harus mengalokasikan sumber daya per prosesor apa pun dan melakukan tugas lain untuk bersiap menggunakan prosesor yang ada di partisi perangkat keras. Jika driver perangkat berhasil memproses panggilan balik ini untuk semua prosesor aktif yang saat ini ada di partisi perangkat keras, fungsi panggilan balik segera dipanggil lagi untuk setiap prosesor aktif yang saat ini ada di partisi perangkat keras. Untuk panggilan balik ini, anggota Status dari struktur KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT yang ditujukkan oleh parameter ChangeContext berisi KeProcessorAddCompleteNotify. KeRegisterProcessorChangeCallback kembali setelah panggilan balik ini selesai.

Jika terjadi kesalahan saat driver perangkat memproses panggilan balik pertama untuk salah satu prosesor aktif yang ada di partisi perangkat keras yang dapat menyebabkan pemeriksaan bug terjadi jika driver terus dimuat, fungsi panggilan balik mengatur variabel yang ditujukan ke oleh parameter OperationStatus ke kode NTSTATUS yang menjelaskan kondisi kesalahan. Misalnya, jika driver perangkat mengalami kegagalan alokasi memori untuk struktur data per prosesor untuk prosesor aktif yang ada, fungsi panggilan balik mengatur variabel ini ke STATUS_INSUFFICIENT_RESOURCES. Jika panggilan balik berhasil diproses, konten variabel yang ditujukkan oleh parameter OperationStatus tidak boleh diubah.

Jika driver perangkat menunjukkan kesalahan ketika panggilan balik pertama untuk salah satu prosesor aktif yang ada di partisi perangkat keras diproses, fungsi panggilan balik tidak dipanggil untuk prosesor aktif yang ada lagi. Sebaliknya, fungsi panggilan balik segera dipanggil untuk kedua kalinya untuk setiap prosesor aktif yang panggilan baliknya dipanggil untuk pertama kalinya, tidak termasuk prosesor aktif yang panggilan baliknya menunjukkan kesalahan. Untuk panggilan balik ini, anggota Status struktur KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT yang ditujukkan oleh parameter ChangeContext berisi KeProcessorAddFailureNotify.

Driver perangkat biasanya memanggil rutinitas KeRegisterProcessorChangeCallback dari dalam rutinitas DriverEntry-nya . Jika panggilan ke rutinitas KeRegisterProcessorChangeCallback mengembalikan NULL, rutinitas DriverEntry driver perangkat harus mengembalikan kode NTSTATUS yang menjelaskan kondisi kesalahan.

Driver perangkat dapat menggunakan konteks yang diteruskan dalam parameter CallbackContext ke rutinitas KeRegisterProcessorChangeCallback sebagai tempat di mana fungsi panggilan balik dapat menyimpan kode NTSTATUS yang menjelaskan kondisi kesalahan. Kode NTSTATUS ini kemudian dapat digunakan sebagai nilai pengembalian untuk rutinitas DriverEntry driver perangkat.

Nilai status yang dikembalikan oleh KeRegisterProcessorChangeCallback hanya menunjukkan apakah pendaftaran fungsi panggilan balik berhasil atau gagal. Ini tidak menunjukkan keberhasilan atau kegagalan panggilan apa pun ke fungsi panggilan balik yang mungkin terjadi sebelum KeRegisterProcessorChangeCallback kembali.

Fungsi panggilan balik yang telah didaftarkan untuk pemberitahuan perubahan prosesor harus tidak terdaftar sebelum driver perangkat dibongkar dari sistem operasi. Untuk membatalkan pendaftaran fungsi panggilan balik, driver perangkat memanggil rutinitas KeDeregisterProcessorChangeCallback , dan meneruskan, sebagai parameter input ke rutinitas ini, handel pendaftaran yang dikembalikan oleh panggilan ke rutinitas KeRegisterProcessorChangeCallback .

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

Lihat juga

KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT

KeDeregisterProcessorChangeCallback