struktur WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS (wdfdevice.h)

  • Artikel

[Berlaku untuk KMDF dan UMDF]

Struktur WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS berisi informasi yang disediakan driver yang digunakan kerangka kerja saat perangkat diam dan sistem dalam status kerja sistem (S0).

Sintaks

typedef struct _WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS {
  ULONG                                 Size;
  WDF_POWER_POLICY_S0_IDLE_CAPABILITIES IdleCaps;
  DEVICE_POWER_STATE                    DxState;
  ULONG                                 IdleTimeout;
  WDF_POWER_POLICY_S0_IDLE_USER_CONTROL UserControlOfIdleSettings;
  WDF_TRI_STATE                         Enabled;
  WDF_TRI_STATE                         PowerUpIdleDeviceOnSystemWake;
  WDF_POWER_POLICY_IDLE_TIMEOUT_TYPE    IdleTimeoutType;
  WDF_TRI_STATE                         ExcludeD3Cold;
} WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS, *PWDF_DEVICE_POWER_POLICY_IDLE_SETTINGS;

Anggota

Size

Ukuran, dalam byte, dari struktur ini.

IdleCaps

Enumerator berjenis WDF_POWER_POLICY_S0_IDLE_CAPABILITIES yang mengidentifikasi kemampuan perangkat untuk bangun sendiri setelah diatur ke status daya rendah, sementara sistem tetap dalam status bekerja (S0).

DxState

Enumerator jenis DEVICE_POWER_STATE yang mengidentifikasi status daya perangkat rendah yang akan dimasukkan perangkat setelah periode batas waktu diam berakhir. nilai DEVICE_POWER_STATE didefinisikan dalam wdm.h.

IdleTimeout

Jumlah waktu, dalam milidetik, bahwa perangkat akan tetap menganggur sebelum kerangka kerja menempatkannya dalam status daya rendah yang disediakan DxState. Untuk menggunakan nilai batas waktu diam default kerangka kerja, tentukan IdleTimeoutDefaultValue. Untuk informasi selengkapnya tentang kapan kerangka kerja menganggap perangkat menganggur, lihat Mendukung Power-Down Menganggur.

UserControlOfIdleSettings

Enumerator yang diketik WDF_POWER_POLICY_S0_IDLE_USER_CONTROL yang menunjukkan apakah pengguna memiliki kemampuan untuk memodifikasi pengaturan diam perangkat.

Enabled

Enumerator jenis WDF_TRI_STATE yang menunjukkan apakah perangkat akan dimatikan jika tetap menganggur dan saat daya sistem berada di S0. Anggota ini bisa memiliki salah satu nilai berikut:

WdfTrue - Daya mati diaktifkan.

WdfFalse - Mematikan dinonaktifkan.

WdfUseDefault - Pemadaman pada awalnya diaktifkan secara default; tetapi jika anggota UserControlOfIdleSettings diatur ke IdleAllowUserControl, pengaturan pengguna atau file INF driver akan menggantikan nilai awal.

Jika daya mati diaktifkan, perangkat memiliki kemampuan bangun, dan nilai batas waktu diam kedaluwarsa, kerangka kerja memanggil fungsi panggilan balik EvtDeviceArmWakeFromS0 driver sebelum perangkat memasuki status daya rendah.

PowerUpIdleDeviceOnSystemWake

Enumerator berjenis WDF_TRI_STATE yang menunjukkan apakah perangkat akan kembali ke status berfungsi (D0) ketika sistem kembali ke status kerjanya (S0). Anggota ini hanya berlaku jika driver menetapkan anggota IdleCaps ke IdleCannotWakeFromS0. Anggota PowerUpIdleDeviceOnSystemWake dapat memiliki salah satu nilai berikut:

WdfTrue - Jika perangkat dan sistem dalam keadaan daya rendah, perangkat kembali ke status kerjanya ketika sistem kembali ke keadaan kerjanya.

WdfFalse - Jika perangkat dan sistem dalam keadaan daya rendah, perangkat tetap dalam status daya rendah ketika sistem kembali ke status kerjanya.

WdfUseDefault - Nilai default yang digunakan kerangka kerja jika driver tidak menetapkan nilai yang berbeda. Nilai ini memiliki arti yang sama dengan WdfFalse.

Jika anggota PowerUpIdleDeviceOnSystemWake diatur ke WdfFalse atau WdfUseDefault, perangkat kembali ke status kerjanya hanya saat perangkat lunak mengakses perangkat, seperti saat aplikasi mengirim permintaan I/O ke perangkat. Untuk informasi selengkapnya, lihat Perangkat Kembali ke Status Kerjanya.

Anggota PowerUpIdleDeviceOnSystemWake tersedia di KMDF versi 1.9 dan yang lebih baru, dan mulai dari VERSI 2.0 UMDF.

IdleTimeoutType

Enumerator berjenis WDF_POWER_POLICY_IDLE_TIMEOUT_TYPE yang menunjukkan bagaimana anggota IdleTimeout digunakan.

Anggota IdleTimeoutType tersedia di KMDF versi 1.11 dan yang lebih baru, dan mulai dari VERSI 2.0 UMDF. Lihat informasi tambahan dalam Keterangan.

ExcludeD3Cold

Enumerator berjenis WDF_TRI_STATE yang menunjukkan apakah status daya D3cold harus menjadi pilihan yang diizinkan untuk status daya rendah yang akan dimasukkan perangkat saat periode batas waktu diam berakhir. Anggota ExcludeD3Cold dapat memiliki salah satu nilai berikut:

WdfTrue - Kerangka kerja akan memindahkan perangkat ke D-state berdaya rendah saat periode batas waktu diam berakhir. Jika status D adalah D3, perangkat akan dipindahkan ke D3hot. Jika ExcludeD3Cold diatur ke WdfTrue, maka tidak ada transisi lebih lanjut dari D3hot ke D3cold yang akan diizinkan.

WdfFalse - Perangkat dapat memasuki status daya D3cold saat periode batas waktu diam berakhir, jika semua kriteria berikut terpenuhi:

  • Anggota DxState dari struktur ini menentukan PowerDeviceD3 atau PowerDeviceMaximum.
  • Firmware ACPI menunjukkan bahwa perangkat mendukung status daya D3cold.
  • Jika driver yang ditentukan IdleCanWakeFromS0 atau IdleUsbSelectiveSuspend di anggota IdleCaps dari struktur ini, perangkat dapat merespons peristiwa bangun eksternal saat dalam status daya D3cold. Jika tidak, persyaratan ini tidak berlaku.
WdfUseDefault - Kerangka kerja memeriksa DDInstall. Bagian HW dari file INF driver. Jika baris berikut ada, nilai ini memiliki arti yang sama dengan WdfFalse:
Include = machine.inf
Needs = PciD3ColdSupported
Jika tidak, nilai ini memiliki arti yang sama dengan WdfTrue.

Anggota ExcludeD3Cold tersedia mulai dari KMDF versi 1.11, serta mulai dari versi 2.0 UMDF, dan diabaikan dalam sistem operasi yang lebih lama dari Windows 8. Lihat informasi tambahan dalam Keterangan.

Keterangan

Struktur WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS digunakan sebagai input ke WdfDeviceAssignS0IdleSettings.

Pertama kali driver memanggil WdfDeviceAssignS0IdleSettings, tindakan berikut terjadi:

  • Kerangka kerja menyimpan nilai semua anggota struktur WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS .
  • Jika anggota UserControlOfIdleSettings diatur ke IdleAllowUserControl dan jika anggota Diaktifkan diatur ke WdfUseDefault, kerangka kerja membaca registri untuk mengetahui apakah pengguna telah mengaktifkan daya perangkat saat diam.
Selama panggilan berikutnya ke WdfDeviceAssignS0IdleSettings, kerangka kerja hanya menyimpan nilai anggota DxState, IdleTimeout, dan Diaktifkan . Selain itu, di KMDF 1.9 dan yang lebih lama, kerangka kerja menyimpan nilai anggota IdleCapskecuali nilainya adalah IdleUsbSelectiveSuspend. Oleh karena itu, driver harus menggunakan aturan berikut:
  • Jika driver menentukan IdleUsbSelectiveSuspend untuk nilai anggota IdleCaps , driver harus melakukannya saat pertama kali memanggil WdfDeviceAssignS0IdleSettings, dan kemudian tidak dapat mengubah nilai tersebut.
  • Jika driver menentukan IdleCanWakeFromS0 atau IdleCannotWakeFromS0 saat pertama kali memanggil WdfDeviceAssignS0IdleSettings, kemudian dapat memanggil WdfDeviceAssignS0IdleSettings lagi untuk mengubah nilai tersebut (tetapi tidak dapat mengubah nilai menjadi IdleUsbSelectiveSuspend).

Mulai dari KMDF 1.11 dan UMDF 2.0, driver KMDF dapat beralih antara IdleUsbSelectiveSuspend dan IdleCannotWakeFromS0 kapan saja.

Mulai dari Windows 8, mengatur anggota IdleTimeoutType ke SystemManagedIdleTimeout atau SystemManagedIdleTimeoutWithHint menyebabkan kerangka kerja mendaftar dengan kerangka kerja manajemen daya (PoFx).

Jika driver menerapkan dukungan status daya fungsional untuk perangkat multi-komponen, driver harus mengatur IdleTimeoutType ke DriverManagedIdleTimeout atau tidak memanggil WdfDeviceAssignS0IdleSettings sama sekali.

Untuk informasi selengkapnya, lihat Mendukung Status Daya Fungsi dan Gambaran Umum Power Management Framework.

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

  • Nilai tidak boleh PowerDeviceD0.
  • Untuk perangkat USB, nilainya tidak boleh PowerDeviceD0 atau PowerDeviceD3.
  • Jika Anda menentukan PowerDeviceMaximum, kerangka kerja menggunakan nilai yang disediakan driver untuk bus perangkat dalam anggota DeviceWake dari struktur WDF_DEVICE_POWER_CAPABILITIES .
  • Jika nilai anggota IdleCaps adalah IdleCanWakeFromS0, 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.)
Dalam sistem operasi yang lebih lama dari Windows 8, status daya D3 menandakan bahwa perangkat dalam keadaan daya rendah, tetapi beberapa daya ke bus masih dipertahankan. Mulai dari Windows 8, status daya D3 sebelumnya disebut D3hot, dan status daya baru (D3cold) tersedia. Perangkat dapat memasuki status D3cold baik saat sistem dalam status berfungsi (S0) atau dalam status daya rendah. Ketika perangkat dalam status daya D3cold, bus tidak aktif dan perangkat harus memicu sinyal bangunnya sendiri ketika tindakan eksternal (misalnya mencolokkan kabel jaringan) menyebabkan peristiwa perangkat keras.

Mulai dari KMDF 1.11 dan UMDF 2.0, perangkat yang mendukung daya diam dapat menggunakan anggota ExcludeD3Cold dari struktur ini untuk menentukan apakah status daya D3cold harus menjadi pilihan yang diizinkan untuk status daya perangkat rendah yang akan dimasukkan perangkat setelah periode batas waktu diam berakhir.

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

Untuk menginisialisasi struktur WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS , driver Anda harus memanggil WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS_INIT.

Persyaratan

Persyaratan Nilai
Versi KMDF minimum 1,0
Versi UMDF minimum 2.0
Header wdfdevice.h (termasuk Wdf.h)