struktur PO_FX_DEVICE_V3 (wdm.h)

Artikel
08/08/2023

Struktur PO_FX_DEVICE_V3 menjelaskan atribut daya perangkat ke kerangka kerja manajemen daya (PoFx), DFx ( Directed PoFx)

Sintaks

typedef struct _PO_FX_DEVICE_V3 {
  ULONG                                      Version;
  ULONGLONG                                  Flags;
  PPO_FX_COMPONENT_ACTIVE_CONDITION_CALLBACK ComponentActiveConditionCallback;
  PPO_FX_COMPONENT_IDLE_CONDITION_CALLBACK   ComponentIdleConditionCallback;
  PPO_FX_COMPONENT_IDLE_STATE_CALLBACK       ComponentIdleStateCallback;
  PPO_FX_DEVICE_POWER_REQUIRED_CALLBACK      DevicePowerRequiredCallback;
  PPO_FX_DEVICE_POWER_NOT_REQUIRED_CALLBACK  DevicePowerNotRequiredCallback;
  PPO_FX_POWER_CONTROL_CALLBACK              PowerControlCallback;
  PPO_FX_DIRECTED_POWER_UP_CALLBACK          DirectedPowerUpCallback;
  PPO_FX_DIRECTED_POWER_DOWN_CALLBACK        DirectedPowerDownCallback;
  ULONG                                      DirectedFxTimeoutInSeconds;
  PVOID                                      DeviceContext;
  ULONG                                      ComponentCount;
  PO_FX_COMPONENT_V2                         Components[ANYSIZE_ARRAY];
} PO_FX_DEVICE_V3, *PPO_FX_DEVICE_V3;

Anggota

Version

Nomor versi struktur ini. Jika driver akan mendaftar untuk dukungan daya yang diarahkan dengan DFx, atur anggota ini ke PO_FX_VERSION_V3.

Flags

Mengontrol apakah perangkat turunan langsung dan perangkat anak daya dapat menolak Directed PoFx.

Kemungkinan nilai bendera meliputi:

Bendera	Deskripsi
PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL	Memungkinkan perangkat turunan langsung dari perangkat ini untuk secara opsional mendukung PoFx Terarah. Jika tidak diatur, semua anak langsung harus mendukung PoFx Terarah agar perangkat ini sepenuhnya mendukung Directed PoFx.
PO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONAL	Memungkinkan perangkat anak daya dari perangkat ini untuk secara opsional mendukung PoFx Terarah. Jika tidak disediakan, semua power children harus mendukung Directed PoFx agar perangkat ini dapat sepenuhnya mendukung Directed PoFx.
PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL	Mengatur PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL dan PO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONAL
PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME	Memaksa PoFx untuk mencegah S0-IRP selesai sebelum D0-IRP dilanjutkan dari status sistem seperti Hibernate atau Tidur. Saling eksklusif dengan PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME.
PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME	Memaksa PoFx untuk memungkinkan S0-IRP selesai sebelum D0-IRP dilanjutkan dari status sistem seperti Hibernate atau Tidur. Saling eksklusif dengan PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME.

ComponentActiveConditionCallback

Penunjuk ke rutinitas panggilan balik ComponentActiveConditionCallback yang diimplementasikan oleh driver perangkat.

ComponentIdleConditionCallback

Penunjuk ke rutinitas panggilan balik ComponentIdleConditionCallback yang diimplementasikan oleh driver perangkat.

ComponentIdleStateCallback

Penunjuk ke rutinitas panggilan balik ComponentIdleStateCallback yang diimplementasikan oleh driver perangkat.

DevicePowerRequiredCallback

Penunjuk ke rutinitas panggilan balik DevicePowerRequiredCallback yang diimplementasikan oleh driver perangkat.

DevicePowerNotRequiredCallback

Penunjuk ke rutinitas panggilan balik DevicePowerNotRequiredCallback yang diimplementasikan oleh driver perangkat.

PowerControlCallback

Penunjuk ke rutinitas panggilan balik PowerControlCallback yang diimplementasikan oleh driver perangkat.

DirectedPowerUpCallback

Pointer ke rutinitas panggilan balik PO_FX_DIRECTED_POWER_UP_CALLBACK yang diimplementasikan oleh driver perangkat. Perangkat hanya DirectedPower* dapat menyediakan panggilan balik saat mendaftar untuk PoFx. Ini tidak perlu mengimplementasikan sisa panggilan balik PoFx.

DirectedPowerDownCallback

Penunjuk ke rutinitas panggilan balik PO_FX_DIRECTED_POWER_DOWN_CALLBACK yang diimplementasikan oleh driver perangkat.

DirectedFxTimeoutInSeconds

Memberikan petunjuk pada kerangka kerja yang menentukan batas waktu yang disarankan dalam detik di mana perangkat harus menganggur setelah aktivitas perangkat lunak tidak lagi ada. Nilai defaultnya adalah 2 menit.

DeviceContext

Penunjuk ke konteks perangkat yang dialokasikan pemanggil. Pointer ini diteruskan sebagai parameter untuk setiap fungsi panggilan balik yang diimplementasikan driver yang diarahkan oleh struktur ini. Driver perangkat menggunakan konteks ini untuk menyimpan informasi tentang status daya perangkat saat ini. Konteks ini buram untuk PoFx.

ComponentCount

Jumlah elemen dalam array Komponen . Selain itu, anggota ini menentukan jumlah komponen dalam perangkat.

Components[ANYSIZE_ARRAY]

Anggota ini adalah elemen pertama dalam array dari satu atau beberapa elemen PO_FX_COMPONENT_V2. Jika array berisi lebih dari satu elemen, elemen tambahan segera mengikuti struktur PO_FX_DEVICE_V2 . Array berisi satu elemen untuk setiap komponen dalam perangkat. Status daya Fx dari setiap komponen dapat dikontrol secara independen dari status daya Fx komponen lain dalam perangkat. Konstanta ANYSIZE_ARRAY didefinisikan menjadi 1 dalam file header Ntdef.h.

Keterangan

Untuk mendaftarkan perangkat dengan PoFx, driver memanggil rutinitas dan persediaan PoFxRegisterDevice , sebagai parameter, pointer ke struktur PO_FX_DEVICE yang menjelaskan perangkat. Untuk menggunakan PoFx tetapi bukan DFx, daftar dengan PoFx menggunakan struktur PO_FX_DEVICE_V2 atau struktur PO_FX_DEVICE_V3.

Setiap elemen dalam array Komponen menjelaskan atribut status daya dari satu komponen di perangkat. Setiap komponen dalam perangkat diidentifikasi oleh indeks array Komponennya . Rutinitas seperti PoFxActivateComponent dan PoFxCompleteIdleCondition menggunakan indeks array komponen untuk mengidentifikasi komponen.

Driver perangkat tidak diperlukan untuk menerapkan kedelapan rutinitas panggilan balik. Driver dapat mengatur penunjuk fungsi dalam struktur PO_FX_DEVICE ke NULL jika driver tidak menerapkan rutinitas panggilan balik yang sesuai. Namun, rutinitas panggilan balik tertentu harus diimplementasikan. Secara khusus, jika satu atau beberapa komponen dalam perangkat memiliki lebih dari satu status Fx, driver harus menerapkan rutinitas ComponentIdleStateCallback, ComponentActiveConditionCallback, dan ComponentIdleConditionCallback . Jika tidak, pendaftaran perangkat gagal dan PoFxRegisterDevice mengembalikan STATUS_INVALID_PARAMETER.

Jika driver tidak menyediakan salah satu PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME atau PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME sistem akan kembali ke konfigurasi default platform. Konfigurasi default PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME untuk platform x86/x64, dan PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME untuk platform ARM32/ARM64. Bendera ini hanya dihormati untuk Win11 22000+ dan diabaikan secara diam-diam untuk rilis sebelumnya. Untuk driver WDF, bendera ini dapat disediakan menggunakan bidang PoFxDeviceFlagsWDF_POWER_FRAMEWORK_SETTINGS.