GET_IDLE_WAKE_INFO fungsi panggilan balik (wdm.h)

Artikel
03/08/2023

Rutinitas GetIdleWakeInfo memungkinkan driver untuk perangkat menemukan status daya perangkat tempat perangkat dapat memberi sinyal peristiwa bangun.

Sintaks

GET_IDLE_WAKE_INFO GetIdleWakeInfo;

NTSTATUS GetIdleWakeInfo(
  [in, optional] PVOID Context,
  [in]           SYSTEM_POWER_STATE SystemPowerState,
  [out]          PDEVICE_WAKE_DEPTH DeepestWakeableDstate
)
{...}

Parameter

[in, optional] Context

Penunjuk ke informasi konteks khusus antarmuka. Pemanggil mengatur parameter ini ke nilai anggota Konteks dari struktur D3COLD_SUPPORT_INTERFACE untuk antarmuka.

[in] SystemPowerState

Status daya sistem. Atur parameter ini ke salah satu nilai enumerasi SYSTEM_POWER_STATE berikut:

PowerSystemWorking
PowerSystemSleeping1
PowerSystemSleeping2
PowerSystemSleeping3
PowerSystemHibernate

Nilai-nilai ini mewakili status daya sistem S0 (status kerja sistem) melalui S4. Untuk nilai SystemPowerState yang disediakan oleh pemanggil, rutinitas menentukan status daya perangkat terdalam dari mana perangkat dapat mengeluarkan sinyal bangun.

[out] DeepestWakeableDstate

Status Dx terjaga terdalam. Parameter ini adalah penunjuk ke variabel DEVICE_WAKE_DEPTH . Jika panggilan berhasil, rutin menulis salah satu nilai enumerasi berikut ke variabel ini:

DeviceWakeDepthNotWakeable
DeviceWakeDepthD0
DeviceWakeDepthD1
DeviceWakeDepthD2
DeviceWakeDepthD3hot
DeviceWakeDepthD3cold

Nilai dalam rentang DeviceWakeDepthD0 ke DeviceWakeDepthD3cold menunjukkan status Dx bertenaga terendah tempat perangkat dapat mengirim sinyal bangun ketika komputer berada dalam status daya sistem yang ditentukan oleh parameter SystemPowerState . DeviceWakeDepthNotWakeable menunjukkan bahwa tidak ada status daya perangkat tempat perangkat dapat mengirim sinyal bangun ketika komputer berada dalam status daya sistem yang ditentukan oleh SystemPowerState.

Jika rutinitas tidak dapat menentukan status perangkat terjaga terdalam (mungkin karena firmware platform tidak berisi informasi ini), panggilan gagal dan rutin mengembalikan kode status kesalahan. Jika panggilan GetIdleWakeInfo gagal untuk nilai parameter SystemPowerState apa pun dalam rentang PowerSystemWorking ke PowerSystemHibernate, itu akan gagal untuk semua nilai tersebut.

Menampilkan nilai

Rutinitas GetIdleWakeInfo mengembalikan STATUS_SUCCESS jika berhasil mengambil status perangkat yang dapat dibangunkan terdalam. Jika tidak, kode status kesalahan akan dikembalikan.

Keterangan

Untuk status daya sistem yang ditentukan oleh pemanggil, rutinitas ini mencoba menentukan status daya perangkat bertenaga terendah dari mana perangkat dapat memberi sinyal peristiwa bangun ke prosesor. Jika berhasil, rutin menulis status daya perangkat ke lokasi yang diarahkan oleh parameter DeepestWakeableDstate , dan mengembalikan STATUS_SUCCESS. Atau, jika rutin menentukan bahwa perangkat tidak dapat memberi sinyal peristiwa bangun dari status daya perangkat apa pun, rutin menulis nilai DeviceWakeDepthNotWakeable ke lokasi ini, dan mengembalikan STATUS_SUCCESS.

Driver untuk perangkat menggunakan informasi yang disediakan oleh rutinitas GetIdleWakeInfo untuk menentukan kondisi di mana perangkat dapat memberi sinyal peristiwa bangun. Perangkat yang harus dapat memberi sinyal peristiwa bangun tertentu tidak boleh memasuki status daya perangkat yang tidak dapat memberi sinyal peristiwa ini. Untuk beberapa jenis perangkat, sinyal bangun yang harus dikirim perangkat ketika komputer berada dalam status daya sistem S0 (bekerja) berbeda dari yang harus dikirim perangkat ketika komputer tampaknya mati.

Misalnya, ketika kartu dimasukkan ke slot kartu PCI Express, dan perangkat pengontrol hot-plug PCI Express untuk slot berada dalam status daya perangkat D0, perangkat ini memberi sinyal gangguan pada prosesor. Namun, jika perangkat pengontrol dalam status Dx berdaya rendah ketika kartu dimasukkan, status daya sistem komputer mungkin menentukan apakah perangkat ini harus memberi sinyal peristiwa bangun ke prosesor. Idealnya, perangkat pengontrol harus ber perilaku sebagai berikut:

Jika komputer dalam status daya sistem S0 (berfungsi), perangkat harus memberi sinyal peristiwa bangun ke prosesor.
Jika komputer tidur (dalam status Sx berdaya rendah), perangkat tidak boleh memberi sinyal peristiwa bangun.

Beberapa perangkat lama mungkin tidak mendukung perilaku ideal ini. Jika perangkat pengontrol hot-plug PCI Express dalam contoh ini dapat memberi sinyal peristiwa bangun hanya ketika komputer berada dalam status S3, driver (yang, dalam hal ini, adalah driver Pci.sys kotak masuk) untuk pengontrol harus menyimpan pengontrol di D0 ketika komputer berada di S0 (dan tidak bersiap untuk memasuki status tidur).

Driver dalam contoh ini dapat memanggil rutinitas GetIdleWakeInfo untuk menentukan apakah perangkat pengontrol hot-plug harus meninggalkan status D0 saat komputer berada di S0. Untuk panggilan ini, driver mengatur SystemPowerState = PowerSystemWorking. Perangkat ini tidak boleh meninggalkan status D0 (ketika komputer berada di S0) dalam salah satu kasus berikut:

Panggilan GetIdleWakeInfo mengatur parameter output ke DeviceWakeDepthNotWakeable atau DeviceWakeDepthD0 dan mengembalikan STATUS_SUCCESS.
Panggilan GetIdleWakeInfo gagal dan mengembalikan kode status kesalahan.

Driver harus menginterpretasikan salah satu hasil ini untuk berarti bahwa perangkat tidak dapat memberi sinyal peristiwa bangun ketika komputer berada di S0. Berdasarkan informasi ini, driver harus menyimpan perangkat di D0 hingga komputer bersiap untuk keluar dari S0.

Driver untuk sebagian besar perangkat dapat memperlakukan nilai output DeviceWakeDepthD0 sama dengan DeviceWakeDepthNotWakeable. Hanya beberapa driver yang mungkin memiliki alasan untuk mempersenjatai sinyal bangun ketika perangkat mereka berada di D0. Ini adalah driver untuk perangkat sederhana yang memantau peristiwa eksternal yang memicu sinyal bangun terlepas dari apakah perangkat berada di status D0 atau Dx berdaya rendah. Contoh perangkat tersebut adalah tombol daya atau tombol tidur di komputer.

GetIdleWakeInfo rutin mengkueri driver bus yang mendasarinya dan firmware sistem ACPI untuk menentukan status daya perangkat terendah tempat perangkat dapat memberi sinyal peristiwa bangun. Jika driver bus dan firmware tidak dapat memberikan informasi ini, rutinitas gagal dan mengembalikan kode status kesalahan.

Struktur DEVICE_CAPABILITIES mencakup anggota DeviceWake yang menyediakan informasi yang mirip dengan yang tersedia dari rutinitas GetIdleWakeInfo . Namun, informasi dalam anggota DeviceWake hanya berlaku untuk sistem berdaya rendah S1 ke S4. Untuk beberapa perangkat, informasi di anggota DeviceWake mungkin juga berlaku untuk status daya sistem S0, tetapi driver tidak boleh mengandalkan perilaku tersebut. Hanya GetIdleWakeInfo yang rutin melaporkan kemampuan perangkat untuk memberi sinyal peristiwa bangun jika komputer berada di S0.

Fungsi pembantu sebaris, MapWakeDepthToDstate, disediakan untuk mengonversi nilai output DEVICE_WAKE_DEPTH dari rutinitas GetIdleWakeInfo menjadi nilai DEVICE_POWER_STATE yang dapat digunakan sebagai parameter input oleh rutinitas PoRequestPowerIrp .