struktur WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS (wdfdevice.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Struktur WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS berisi informasi yang disediakan driver tentang kemampuan perangkat untuk membangunkan dirinya sendiri dan sistem, ketika keduanya dalam keadaan berdaya rendah.

Sintaks

typedef struct _WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS {
  ULONG                                 Size;
  DEVICE_POWER_STATE                    DxState;
  WDF_POWER_POLICY_SX_WAKE_USER_CONTROL UserControlOfWakeSettings;
  WDF_TRI_STATE                         Enabled;
  BOOLEAN                               ArmForWakeIfChildrenAreArmedForWake;
  BOOLEAN                               IndicateChildWakeOnParentWake;
} WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS, *PWDF_DEVICE_POWER_POLICY_WAKE_SETTINGS;

Anggota

Size

Ukuran, dalam byte, dari struktur ini.

DxState

Enumerator berjenis DEVICE_POWER_STATE yang mengidentifikasi status daya perangkat rendah yang akan dimasukkan perangkat ketika status daya sistem turun ke status daya rendah yang dapat dibangkitkan. Nilai DxState tidak boleh PowerDeviceD0. nilai DEVICE_POWER_STATE didefinisikan dalam wdm.h.

UserControlOfWakeSettings

Enumerator yang diketik WDF_POWER_POLICY_SX_WAKE_USER_CONTROL yang menunjukkan apakah pengguna memiliki kemampuan untuk mengubah pengaturan bangun perangkat.

Enabled

Enumerator jenis WDF_TRI_STATE yang menunjukkan apakah perangkat dapat membangunkan sistem (yaitu, memulihkan sistem ke S0) ketika sistem dalam status daya rendah. Anggota ini bisa memiliki salah satu nilai berikut ini:

WdfTrue - Membangunkan sistem diaktifkan.

WdfFalse - Membangunkan sistem dinonaktifkan.

WdfUseDefault - Membangunkan sistem awalnya diaktifkan secara default; tetapi jika anggota UserControlOfWakeSettings diatur ke WakeAllowUserControl, pengaturan pengguna atau file INF driver akan mengambil alih nilai awal.

Jika membangunkan sistem diaktifkan dan sistem akan memasuki status daya rendah, kerangka kerja memanggil fungsi panggilan balik EvtDeviceArmWakeFromSx atau EvtDeviceArmWakeFromSxWithReason driver sebelum perangkat memasuki status daya rendah.

ArmForWakeIfChildrenAreArmedForWake

Nilai Boolean yang, jika diatur ke TRUE, menunjukkan bahwa kemampuan perangkat induk untuk membangunkan dirinya sendiri dan sistem harus diaktifkan ketika kemampuan ini diaktifkan untuk perangkat anak perangkat. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini. Anggota ini tersedia di KMDF versi 1.7 dan yang lebih baru.

IndicateChildWakeOnParentWake

Nilai Boolean yang, jika diatur ke TRUE, menunjukkan bahwa kerangka kerja akan memberikan status bangun ke perangkat anak jika perangkat induk mendeteksi sinyal bangun. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini. Anggota ini tersedia di KMDF versi 1.7 dan yang lebih baru.

Keterangan

Struktur WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS digunakan sebagai input ke WdfDeviceAssignSxWakeSettings.

Untuk menginisialisasi struktur WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS , driver Anda harus memanggil WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS_INIT.

Pertama kali driver memanggil WdfDeviceAssignSxWakeSettings, tindakan berikut terjadi:

Kerangka kerja menyimpan nilai semua anggota struktur WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS .
Jika anggota UserControlOfWakeSettings diatur ke WakeAllowUserControl dan jika anggota Diaktifkan diatur ke WdfUseDefault, kerangka kerja membaca registri untuk mengetahui apakah pengguna telah mengaktifkan membangunkan sistem.

Selama panggilan berikutnya ke WdfDeviceAssignSxWakeSettings, kerangka kerja tidak menyimpan nilai anggota UserControlOfWakeSettings . Dengan kata lain, kerangka kerja melakukan langkah-langkah berikut saat pertama kali driver memanggil WdfDeviceAssignSxWakeSettings tetapi tidak selama panggilan nanti:

Menyimpan nilai anggota UserControlOfWakeSettings .
Mencari pengaturan pengguna di registri, jika nilai anggota yang Diaktifkan adalah WdfUseDefault.

Aturan berikut berlaku untuk nilai yang Anda tentukan untuk anggota DxState :

Nilai tidak boleh PowerDeviceD0.
Jika Anda menentukan PowerDeviceMaximum, kerangka kerja menggunakan nilai driver untuk bus perangkat yang disediakan dalam anggota DeviceWake dari struktur WDF_DEVICE_POWER_CAPABILITIES-nya .
Anda tidak dapat menentukan status daya perangkat yang lebih rendah dari status daya perangkat di anggota DeviceWake dari struktur WDF_DEVICE_POWER_CAPABILITIES driver bus. (Dengan kata lain, jika nilai DeviceWake driver bus adalah PowerDeviceD2, nilai DxState driver fungsi Anda tidak boleh PowerDeviceD3.)

Untuk informasi tentang entri registri yang mengontrol kemampuan bangun perangkat, lihat Kontrol Pengguna Perilaku Menganggur dan Bangun Perangkat.

Jika perangkat yang dijelaskan struktur WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS adalah perangkat induk, driver untuk perangkat induk dapat menggunakan anggota ArmForWakeIfChildrenAreArmedForWake dan IndicateChildWakeOnParentWake sebagai berikut:

Jika driver mengatur anggota ArmForWakeIfChildrenAreArmedForWake ke TRUE, kerangka kerja memanggil fungsi panggilan balik EvtDeviceArmWakeFromSx atau EvtDeviceArmWakeFromSxWithReason saat kemampuan bangun perangkat anak diaktifkan, bahkan jika kemampuan bangun perangkat induk tidak diaktifkan.
Untuk mengurangi konsumsi daya, Anda mungkin tidak ingin mengaktifkan kemampuan bangun perangkat kecuali perangkat anak yang juga mendukung kemampuan bangun dicolokkan. Jika driver Anda mengatur anggota ArmForWakeIfChildrenAreArmedForWake ke TRUE, nilai anggota yang diaktifkan memiliki arti berikut:
- Jika Diaktifkan adalah WdfFalse, kerangka kerja memungkinkan kemampuan bangun driver Anda hanya jika kemampuan bangun perangkat anak diaktifkan.
- Jika Diaktifkan adalah WdfTrue, kerangka kerja selalu memungkinkan kemampuan bangun driver Anda, baik perangkat Anda memiliki perangkat anak yang diaktifkan bangun atau tidak.
- Jika Diaktifkan adalah WdfUseDefault dan UserControlOfWakeSettings adalah WakeAllowUserControl, pengguna dapat mengontrol apakah perangkat Anda selalu diaktifkan secara bangun atau jika diaktifkan hanya saat perangkat Anda memiliki perangkat turunan yang diaktifkan.
Jika driver mengatur anggota IndicateChildWakeOnParentWake ke TRUE, kerangka kerja memanggil fungsi panggilan balik EvtDeviceWakeFromSxTriggered di driver perangkat induk dan di driver untuk setiap perangkat anak yang diaktifkan. Jika driver mengatur anggota ini ke FALSE, kerangka kerja memanggil fungsi panggilan balik EvtDeviceWakeFromSxTriggered hanya di driver perangkat induk. Driver Anda harus mengatur IndicateChildWakeOnParentWake ke TRUE jika driver untuk anak-anak perangkat Anda harus memeriksa perangkat keras untuk menentukan mengapa sistem terbangun.