blob: ad8118c43321b8a2af0465b3c5d115ffc771c618 [file]
// Copyright 2026 The Fuchsia Authors
//
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file or at
// https://opensource.org/licenses/MIT
//
// Ported from zircon/kernel/dev/pdev/power/power.cc
//
// Platform Device (pdev) Power Driver Interface.
//
// Provides platform-level abstraction and dispatch for system power operations,
// including system reboot, shutdown, CPU core power state management, and
// dynamic Operating Performance Point (OPP) control for CPU power domains.
#[cfg(console_enabled)]
pub mod console;
#[cfg(not(console_enabled))]
use debug as _;
mod power_ffi;
use boot_options::BootOptions;
use core::sync::atomic::Ordering;
#[cfg(ktest)]
use unittest as _;
use zr::AtomicConstPtr;
use zx_status::Status;
// Re-exported for architecture-specific platform power drivers (e.g., arm64 iris and moonflower).
#[cfg_attr(not(target_arch = "aarch64"), allow(unused_imports))]
pub use crate::power_management::{
ControlInterface, POWER_LEVEL_OPTIONS_DOMAIN_INDEPENDENT, PowerDomainConfig, PowerLevelConfig,
};
/// Flags passed to `power_reboot` specifying the reason/target for reboot.
#[repr(C)]
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum PowerRebootFlags {
Normal = 0,
Bootloader = 1,
Recovery = 2,
Panic = 3,
}
/// Represents the architectural power state of a CPU.
#[repr(C)]
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum PowerCpuState {
On = 0,
Off = 1,
OnPending = 2,
Started = 3,
Stopped = 4,
StartPending = 5,
StopPending = 6,
Suspended = 7,
SuspendPending = 8,
ResumePending = 9,
}
impl TryFrom<u32> for PowerCpuState {
type Error = u32;
fn try_from(raw: u32) -> Result<Self, Self::Error> {
match raw {
x if x == Self::On as u32 => Ok(Self::On),
x if x == Self::Off as u32 => Ok(Self::Off),
x if x == Self::OnPending as u32 => Ok(Self::OnPending),
x if x == Self::Started as u32 => Ok(Self::Started),
x if x == Self::Stopped as u32 => Ok(Self::Stopped),
x if x == Self::StartPending as u32 => Ok(Self::StartPending),
x if x == Self::StopPending as u32 => Ok(Self::StopPending),
x if x == Self::Suspended as u32 => Ok(Self::Suspended),
x if x == Self::SuspendPending as u32 => Ok(Self::SuspendPending),
x if x == Self::ResumePending as u32 => Ok(Self::ResumePending),
_ => Err(raw),
}
}
}
/// Platform device power operations table.
#[derive(Copy, Clone, Debug)]
#[repr(C)]
pub struct PdevPowerOps {
/// Reboots the system according to the provided reboot flags.
pub reboot: Option<extern "C" fn(flags: PowerRebootFlags) -> Result<(), Status>>,
/// Powers off / shuts down the system.
pub shutdown: Option<extern "C" fn() -> Result<(), Status>>,
/// Powers off the current CPU.
pub cpu_off: Option<extern "C" fn() -> Result<(), Status>>,
/// Initiates power-on sequence for the specified hardware CPU.
pub cpu_on:
Option<extern "C" fn(hw_cpu_id: u64, entry: u64, context: u64) -> Result<(), Status>>,
/// Retrieves the current power state of the specified CPU.
pub get_cpu_state:
Option<extern "C" fn(hw_cpu_id: u64, out_state: *mut PowerCpuState) -> Result<(), Status>>,
/// Sets the Operating Performance Point (OPP) for the specified power domain.
pub opp_set: Option<extern "C" fn(domain_id: u32, opp: u64) -> Result<(), Status>>,
/// Retrieves the active Operating Performance Point (OPP) for the specified power domain.
pub opp_get: Option<extern "C" fn(domain_id: u32, out_opp: *mut u64) -> Result<(), Status>>,
/// Returns the number of supported OPP control domains.
pub opp_get_domain_count: Option<extern "C" fn(out_count: *mut usize) -> Result<(), Status>>,
/// Restores platform power state that firmware may have altered while the system was
/// suspended. Called on the boot CPU, with interrupts disabled, immediately after returning
/// from system suspend.
pub system_resume: Option<extern "C" fn() -> Result<(), Status>>,
}
zr::static_assert!(core::mem::size_of::<PowerRebootFlags>() == 4);
zr::static_assert!(core::mem::align_of::<PowerRebootFlags>() == 4);
zr::static_assert!(core::mem::size_of::<PowerCpuState>() == 4);
zr::static_assert!(core::mem::align_of::<PowerCpuState>() == 4);
zr::static_assert!(core::mem::size_of::<PdevPowerOps>() == 72);
zr::static_assert!(core::mem::align_of::<PdevPowerOps>() == 8);
/// Registers the provided power domain configurations and energy models with the kernel scheduler.
pub fn power_management_register_domains(domains: &[PowerDomainConfig<'_>]) -> Result<(), Status> {
crate::power_management::register_domains(domains)
}
/// Sets processing rate limits (min and max) for the CPU cores identified by `cpu_mask`.
///
/// # Arguments
///
/// * `cpu_mask` - Bitmask of logical CPU cores to update.
/// * `min_rate` - Minimum processing rate on the `[0, 1000]` user processing rate scale.
/// * `max_rate` - Maximum processing rate on the `[0, 1000]` user processing rate scale.
pub fn power_management_set_rate_limits(
cpu_mask: u64,
min_rate: u64,
max_rate: u64,
) -> Result<(), Status> {
crate::power_management::set_rate_limits(cpu_mask, min_rate, max_rate)
}
/// Returns whether early boot performance boosting is enabled via kernel boot options.
pub fn power_management_boot_boost_enabled() -> bool {
crate::power_management::boot_boost_enabled()
}
/// Returns whether runtime processor power management (RPPM) is enabled via kernel boot options.
pub fn power_management_rppm_enabled() -> bool {
BootOptions::get().power_rppm
}
static DEFAULT_OPS: PdevPowerOps = PdevPowerOps {
reboot: None,
shutdown: None,
cpu_off: None,
cpu_on: None,
get_cpu_state: None,
opp_set: None,
opp_get: None,
opp_get_domain_count: None,
system_resume: None,
};
static POWER_OPS: AtomicConstPtr<PdevPowerOps> =
AtomicConstPtr::new(core::ptr::addr_of!(DEFAULT_OPS));
fn get_ops() -> &'static PdevPowerOps {
let ops_ptr = POWER_OPS.load(Ordering::Acquire);
if ops_ptr.is_null() {
&DEFAULT_OPS
} else {
// SAFETY: `POWER_OPS` always points to either `DEFAULT_OPS` or a registered `PdevPowerOps`
// table with `'static` lifetime guaranteed by the caller of `pdev_register_power`.
unsafe { &*ops_ptr }
}
}
/// Registers the platform power operations table with `'static` lifetime.
pub fn pdev_register_power(ops: &'static PdevPowerOps) {
POWER_OPS.store(ops as *const PdevPowerOps, Ordering::Release);
}
/// Swaps the current power operations table with a new one for testing, returning the previous
/// table.
///
/// # Safety
///
/// If non-null, `ops` must point to a valid `PdevPowerOps` table for the duration of the test.
pub unsafe fn pdev_swap_power_for_test(ops: *const PdevPowerOps) -> *const PdevPowerOps {
let target_ptr = if ops.is_null() { core::ptr::addr_of!(DEFAULT_OPS) } else { ops };
POWER_OPS.swap(target_ptr, Ordering::AcqRel)
}
/// Reboots the system using the registered power operations.
pub fn power_reboot(flags: PowerRebootFlags) {
let ops = get_ops();
if let Some(reboot_fn) = ops.reboot {
let _ = reboot_fn(flags);
}
}
/// Shuts down the system using the registered power operations.
pub fn power_shutdown() {
let ops = get_ops();
if let Some(shutdown_fn) = ops.shutdown {
let _ = shutdown_fn();
}
}
/// Powers off the calling CPU.
pub fn power_cpu_off() -> Result<(), Status> {
let ops = get_ops();
if let Some(cpu_off_fn) = ops.cpu_off { cpu_off_fn() } else { Ok(()) }
}
/// Initiates the power-on sequence for the CPU with the given hardware CPU ID.
///
/// Note that a hardware CPU ID is architecture-specific (e.g. MPID on ARM, hart ID on RISC-V)
/// and not equivalent to a `cpu_num_t`. This function does not block/wait on the CPU actually
/// coming online; callers are expected to use [`power_get_cpu_state`] to poll the state of the
/// CPU until it comes online.
///
/// On some architectures, the `context` argument is passed to the newly started CPU.
pub fn power_cpu_on(hw_cpu_id: u64, entry: u64, context: u64) -> Result<(), Status> {
let ops = get_ops();
if let Some(cpu_on_fn) = ops.cpu_on { cpu_on_fn(hw_cpu_id, entry, context) } else { Ok(()) }
}
/// Retrieves the power state of the CPU with the specified hardware ID.
pub fn power_get_cpu_state(hw_cpu_id: u64) -> Result<PowerCpuState, Status> {
let ops = get_ops();
if let Some(get_cpu_state_fn) = ops.get_cpu_state {
let mut state = PowerCpuState::Off;
get_cpu_state_fn(hw_cpu_id, &mut state)?;
Ok(state)
} else {
Err(Status::NOT_SUPPORTED)
}
}
/// Sets the opp for the given domain, if supported.
pub fn power_opp_set(domain_id: u32, opp: u64) -> Result<(), Status> {
let ops = get_ops();
if let Some(opp_set_fn) = ops.opp_set {
opp_set_fn(domain_id, opp)
} else {
Err(Status::NOT_SUPPORTED)
}
}
/// Gets the opp for the given domain, if supported.
pub fn power_opp_get(domain_id: u32) -> Result<u64, Status> {
let ops = get_ops();
if let Some(opp_get_fn) = ops.opp_get {
let mut opp = 0;
opp_get_fn(domain_id, &mut opp)?;
Ok(opp)
} else {
Err(Status::NOT_SUPPORTED)
}
}
/// Gets the number of supported opp control domains, if supported. If this
/// returns zero or an error it generally means that in-kernel OPP control is not
/// supported.
pub fn power_opp_get_domain_count() -> Result<usize, Status> {
let ops = get_ops();
if let Some(opp_get_domain_count_fn) = ops.opp_get_domain_count {
let mut count = 0;
opp_get_domain_count_fn(&mut count)?;
Ok(count)
} else {
Err(Status::NOT_SUPPORTED)
}
}
/// Restores platform power state after returning from system suspend, if supported.
///
/// Firmware may alter platform power state (e.g. CPU OPP registers) while the system is
/// suspended. This gives the platform driver a chance to re-apply the kernel's intended state
/// before the rest of the system resumes. Platforms without such state treat this as a no-op.
pub fn power_system_resume() -> Result<(), Status> {
let ops = get_ops();
if let Some(system_resume_fn) = ops.system_resume { system_resume_fn() } else { Ok(()) }
}
/// In-kernel unit tests for the platform power subsystem.
#[cfg(ktest)]
#[unittest::suite(name = "pdev_power")]
mod tests {
use crate::pdev_power::power_ffi::rust_power_get_cpu_state;
use crate::pdev_power::{
PdevPowerOps, PowerCpuState, PowerRebootFlags, pdev_swap_power_for_test, power_cpu_off,
power_cpu_on, power_get_cpu_state, power_management_register_domains,
power_management_set_rate_limits, power_opp_get, power_opp_get_domain_count, power_opp_set,
power_reboot, power_shutdown, power_system_resume,
};
use core::sync::atomic::{AtomicU32, AtomicU64, Ordering};
use unittest::{assert_eq, assert_err, assert_ok};
use zx_status::Status;
static TEST_REBOOT_CALLED: AtomicU32 = AtomicU32::new(0);
static TEST_SHUTDOWN_CALLED: AtomicU32 = AtomicU32::new(0);
static TEST_CPU_OFF_CALLED: AtomicU32 = AtomicU32::new(0);
static TEST_CPU_ON_HW_ID: AtomicU64 = AtomicU64::new(0);
static TEST_OPP_SET_DOMAIN: AtomicU32 = AtomicU32::new(0);
static TEST_OPP_SET_VALUE: AtomicU64 = AtomicU64::new(0);
static TEST_SYSTEM_RESUME_CALLED: AtomicU32 = AtomicU32::new(0);
extern "C" fn test_reboot(flags: PowerRebootFlags) -> Result<(), Status> {
TEST_REBOOT_CALLED.store(flags as u32 + 1, Ordering::Relaxed);
Ok(())
}
extern "C" fn test_shutdown() -> Result<(), Status> {
TEST_SHUTDOWN_CALLED.fetch_add(1, Ordering::Relaxed);
Ok(())
}
extern "C" fn test_cpu_off() -> Result<(), Status> {
TEST_CPU_OFF_CALLED.fetch_add(1, Ordering::Relaxed);
Ok(())
}
extern "C" fn test_cpu_on(hw_cpu_id: u64, _entry: u64, _context: u64) -> Result<(), Status> {
TEST_CPU_ON_HW_ID.store(hw_cpu_id, Ordering::Relaxed);
Ok(())
}
extern "C" fn test_get_cpu_state(
hw_cpu_id: u64,
out_state: *mut PowerCpuState,
) -> Result<(), Status> {
if !out_state.is_null() {
// SAFETY: Caller provides a valid pointer for test.
unsafe {
*out_state = if hw_cpu_id == 42 { PowerCpuState::On } else { PowerCpuState::Off };
}
}
Ok(())
}
extern "C" fn test_opp_set(domain_id: u32, opp: u64) -> Result<(), Status> {
TEST_OPP_SET_DOMAIN.store(domain_id, Ordering::Relaxed);
TEST_OPP_SET_VALUE.store(opp, Ordering::Relaxed);
Ok(())
}
extern "C" fn test_opp_get(domain_id: u32, out_opp: *mut u64) -> Result<(), Status> {
if domain_id == 1 && !out_opp.is_null() {
// SAFETY: Caller provides a valid pointer for test.
unsafe {
*out_opp = 7;
}
Ok(())
} else {
Err(Status::INVALID_ARGS)
}
}
extern "C" fn test_opp_get_domain_count(out_count: *mut usize) -> Result<(), Status> {
if !out_count.is_null() {
// SAFETY: Caller provides a valid pointer for test.
unsafe {
*out_count = 2;
}
Ok(())
} else {
Err(Status::INVALID_ARGS)
}
}
extern "C" fn test_system_resume() -> Result<(), Status> {
TEST_SYSTEM_RESUME_CALLED.fetch_add(1, Ordering::Relaxed);
Ok(())
}
static TEST_OPS: PdevPowerOps = PdevPowerOps {
reboot: Some(test_reboot),
shutdown: Some(test_shutdown),
cpu_off: Some(test_cpu_off),
cpu_on: Some(test_cpu_on),
get_cpu_state: Some(test_get_cpu_state),
opp_set: Some(test_opp_set),
opp_get: Some(test_opp_get),
opp_get_domain_count: Some(test_opp_get_domain_count),
system_resume: Some(test_system_resume),
};
struct TestOpsGuard {
previous: *const PdevPowerOps,
}
impl TestOpsGuard {
fn new(ops: *const PdevPowerOps) -> Self {
// SAFETY: Swapping ops for the duration of the test.
let previous = unsafe { pdev_swap_power_for_test(ops) };
Self { previous }
}
}
impl Drop for TestOpsGuard {
fn drop(&mut self) {
// SAFETY: Restoring the previous ops table when test ends.
unsafe {
pdev_swap_power_for_test(self.previous);
}
}
}
/// Tests that default operations fallback cleanly without registered power ops.
#[test]
fn test_default_ops_fallback() {
let _guard = TestOpsGuard::new(core::ptr::null());
assert_ok!(power_cpu_off());
assert_ok!(power_cpu_on(1, 0, 0));
assert_err!(power_get_cpu_state(1), Status::NOT_SUPPORTED);
assert_err!(power_opp_set(0, 1), Status::NOT_SUPPORTED);
assert_err!(power_opp_get(0), Status::NOT_SUPPORTED);
assert_err!(power_opp_get_domain_count(), Status::NOT_SUPPORTED);
assert_ok!(power_system_resume());
}
/// Tests that registered power ops are dispatched correctly.
#[test]
fn test_registered_ops_dispatch() {
let _guard = TestOpsGuard::new(&TEST_OPS);
TEST_REBOOT_CALLED.store(0, Ordering::Relaxed);
power_reboot(PowerRebootFlags::Recovery);
assert_eq!(
TEST_REBOOT_CALLED.load(Ordering::Relaxed),
PowerRebootFlags::Recovery as u32 + 1
);
TEST_SHUTDOWN_CALLED.store(0, Ordering::Relaxed);
power_shutdown();
assert_eq!(TEST_SHUTDOWN_CALLED.load(Ordering::Relaxed), 1);
TEST_CPU_OFF_CALLED.store(0, Ordering::Relaxed);
assert_ok!(power_cpu_off());
assert_eq!(TEST_CPU_OFF_CALLED.load(Ordering::Relaxed), 1);
TEST_CPU_ON_HW_ID.store(0, Ordering::Relaxed);
assert_ok!(power_cpu_on(1234, 0, 0));
assert_eq!(TEST_CPU_ON_HW_ID.load(Ordering::Relaxed), 1234);
let state = power_get_cpu_state(42);
assert_ok!(state.map(|_| ()));
assert_eq!(state.unwrap(), PowerCpuState::On);
TEST_OPP_SET_DOMAIN.store(0, Ordering::Relaxed);
TEST_OPP_SET_VALUE.store(0, Ordering::Relaxed);
assert_ok!(power_opp_set(3, 5));
assert_eq!(TEST_OPP_SET_DOMAIN.load(Ordering::Relaxed), 3);
assert_eq!(TEST_OPP_SET_VALUE.load(Ordering::Relaxed), 5);
let opp = power_opp_get(1);
assert_ok!(opp.map(|_| ()));
assert_eq!(opp.unwrap(), 7);
let domain_count = power_opp_get_domain_count();
assert_ok!(domain_count.map(|_| ()));
assert_eq!(domain_count.unwrap(), 2);
TEST_SYSTEM_RESUME_CALLED.store(0, Ordering::Relaxed);
assert_ok!(power_system_resume());
assert_eq!(TEST_SYSTEM_RESUME_CALLED.load(Ordering::Relaxed), 1);
}
/// Tests null pointer handling for FFI power operations.
#[test]
fn test_null_pointer_arguments() {
let _guard = TestOpsGuard::new(&TEST_OPS);
// SAFETY: Testing null pointer validation behavior.
assert_err!(
unsafe { rust_power_get_cpu_state(1, core::ptr::null_mut()) },
Status::INVALID_ARGS
);
}
/// Tests registering an empty domain slice with power_management_register_domains.
#[test]
fn test_power_management_register_domains_empty() {
let status = power_management_register_domains(&[]);
assert_ok!(status);
}
/// Tests setting rate limits with an empty CPU mask.
#[test]
fn test_power_management_set_rate_limits_empty_mask() {
let status = power_management_set_rate_limits(0, 0, 1000);
assert_ok!(status);
}
/// Tests querying the boot boost enabled configuration.
#[test]
fn test_power_management_boot_boost_enabled() {
let _ = super::power_management_boot_boost_enabled();
}
/// Tests querying the RPPM enabled configuration.
#[test]
fn test_power_management_rppm_enabled() {
let _ = super::power_management_rppm_enabled();
}
}