ostd/
power.rs

1// SPDX-License-Identifier: MPL-2.0
2
3//! Power management.
4
5use spin::Once;
6
7use crate::{arch::irq::disable_local_and_halt, cpu::CpuSet};
8
9/// An exit code that denotes the reason for restarting or powering off.
10///
11/// Whether or not the code is used depends on the hardware. In a virtualization environment, it
12/// can be passed to the hypervisor (e.g., as QEMU's exit code). In a bare-metal environment, it
13/// can be passed to the firmware. In either case, the code may be silently ignored if reporting
14/// the code is not supported.
15#[derive(Clone, Copy)]
16pub enum ExitCode {
17    /// The code that indicates a successful exit.
18    Success,
19    /// The code that indicates a failed exit.
20    Failure,
21}
22
23static RESTART_HANDLER: Once<fn(ExitCode)> = Once::new();
24
25/// Injects a handler that can restart the system.
26///
27/// The function may be called only once; subsequent calls take no effect.
28///
29/// Note that, depending on the specific architecture, OSTD may already have a built-in handler. If
30/// so, calling this function outside of OSTD will never take effect. Currently, it happens in
31///  - x86_64: Never;
32///  - riscv64: Always;
33///  - loongarch64: Never;
34///  - aarch64: If a supported PSCI device tree node exists.
35pub fn inject_restart_handler(handler: fn(ExitCode)) {
36    RESTART_HANDLER.call_once(|| handler);
37}
38
39/// Restarts the system.
40///
41/// This function will not return. If a restart handler is missing or not working, it will halt all
42/// CPUs on the machine.
43pub fn restart(code: ExitCode) -> ! {
44    if let Some(handler) = RESTART_HANDLER.get() {
45        (handler)(code);
46        crate::error!("Failed to restart the system because the restart handler fails");
47    } else {
48        crate::error!("Failed to restart the system because a restart handler is missing");
49    }
50
51    machine_halt();
52}
53
54static POWEROFF_HANDLER: Once<fn(ExitCode)> = Once::new();
55
56/// Injects a handler that can power off the system.
57///
58/// The function may be called only once; subsequent calls take no effect.
59///
60/// Note that, depending on the specific architecture, OSTD may already have a built-in handler. If
61/// so, calling this function outside of OSTD will never take effect. Currently, it happens in
62///  - x86_64: If a QEMU hypervisor is detected;
63///  - riscv64: Always;
64///  - loongarch64: Never;
65///  - aarch64: If a supported PSCI device tree node exists.
66pub fn inject_poweroff_handler(handler: fn(ExitCode)) {
67    POWEROFF_HANDLER.call_once(|| handler);
68}
69
70/// Powers off the system.
71///
72/// This function will not return. If a poweroff handler is missing or not working, it will halt
73/// all CPUs on the machine.
74pub fn poweroff(code: ExitCode) -> ! {
75    #[cfg(feature = "coverage")]
76    crate::coverage::on_system_exit();
77
78    if let Some(handler) = POWEROFF_HANDLER.get() {
79        (handler)(code);
80        crate::error!("Failed to power off the system because the poweroff handler fails");
81    } else {
82        crate::error!("Failed to power off the system because a poweroff handler is missing");
83    }
84
85    machine_halt();
86}
87
88fn machine_halt() -> ! {
89    crate::error!("Halting the machine...");
90
91    // TODO: `inter_processor_call` may panic again (e.g., if there is an out-of-memory error). We
92    // should find a way to make it panic-free.
93    if let Some(ipi_sender) = crate::smp::IPI_SENDER.get() {
94        ipi_sender.inter_processor_call(&CpuSet::new_full(), || disable_local_and_halt());
95    }
96    disable_local_and_halt();
97}
ostd/power.rs

ostd/
power.rs
