blob: 67924ac17e688f0dcbb2d427f5646dcea0de7d52 [file]
// Copyright 2016 The Fuchsia Authors
// Copyright (c) 2008 Travis Geiselbrecht
//
// 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
#ifndef ZIRCON_KERNEL_INCLUDE_PLATFORM_H_
#define ZIRCON_KERNEL_INCLUDE_PLATFORM_H_
#include <lib/zbi-format/reboot.h>
#include <lib/zx/result.h>
#include <sys/types.h>
#include <zircon/boot/crash-reason.h>
#include <zircon/compiler.h>
#include <zircon/types.h>
#include <dev/power.h>
#include <kernel/cpu.h>
#define BOOT_CPU_ID 0
typedef enum {
HALT_ACTION_HALT = 0, // Spin forever.
HALT_ACTION_REBOOT, // Reset the CPU.
HALT_ACTION_REBOOT_BOOTLOADER, // Reboot into the bootloader.
HALT_ACTION_REBOOT_RECOVERY, // Reboot into the recovery partition.
HALT_ACTION_SHUTDOWN, // Shutdown and power off.
} platform_halt_action;
// Holds platform-specific, per-cpu state used to suspend/resume a CPU.
struct PlatformCpuResumeState {
#if defined(__aarch64__)
uint64_t cntkctl_el1{};
#endif
};
/* super early platform initialization, before almost everything */
extern "C" void platform_early_init();
/* Perform any set up required before virtual memory is enabled, or the heap is set up. */
extern "C" void platform_prevm_init();
/* later init, after the kernel has come up */
extern "C" void platform_init();
/* platform_halt halts the system and performs the |suggested_action|.
*
* This function is used in both the graceful shutdown and panic paths so it
* does not perform more complex actions like switching to the primary CPU,
* unloading the run queue of secondary CPUs, stopping secondary CPUs, etc.
*
* There is no returning from this function.
*/
extern "C" void rust_platform_halt(platform_halt_action suggested_action,
zircon_crash_reason_t reason) __NO_RETURN;
__NO_RETURN inline void platform_halt(platform_halt_action suggested_action,
zircon_crash_reason_t reason) {
rust_platform_halt(suggested_action, reason);
}
/* The platform specific actions to be taken in a halt situation. This is a
* weak symbol meant to be overloaded by platform specific implementations and
* called from the common |platform_halt| implementation. Do not call this
* function directly, call |platform_halt| instead.
*
* There is no returning from this function.
*/
void platform_specific_halt(platform_halt_action suggested_action, zircon_crash_reason_t reason,
bool halt_on_panic) __NO_RETURN;
extern "C" void cpp_platform_specific_halt(platform_halt_action suggested_action,
zircon_crash_reason_t reason,
bool halt_on_panic) __NO_RETURN;
/* optionally stop the current cpu in a way the platform finds appropriate */
void platform_halt_cpu();
extern "C" void cpp_platform_halt_cpu();
// Returns true iff this platform supports |platform_suspend_cpu|.
bool platform_supports_suspend_cpu();
// Specifies whether this suspend operation is limited to the calling CPU or may
// power down the encapsulating power domain.
enum class PlatformAllowDomainPowerDown : bool { No, Yes };
// Suspend the calling CPU.
//
// On success, the CPU will enter an implementation-defined suspend state.
//
// If |allow_domain| is No, then the operation will only target the calling CPU.
// However, if Yes is specified, then, depending on the implementation, the
// power domain encapsulating the calling CPU may also be suspended and powered
// down.
//
// Prior to calling this function, it's critical to set up some kind of
// interrupt that will wake the CPU and resume execution. Upon successful
// suspend and resume, this call returns ZX_OK.
//
// Prior to calling, interrupts must be disabled, preemption must be disabled,
// and the caller must be pinned to the calling CPU.
//
// The calling thread must be a kernel-only thread. Because this routine saves
// only the minimum required register state, it is an error to call this
// function on a thread that has a "user half" (ThreadDispatcher).
//
// Possible error results include (but are not limited to),
//
// ZX_ERR_NOT_SUPPORTED if unsupported on this platform.
//
// ZX_ERR_ACCESS_DENIED or ZX_ERR_INVALID_ARGS if the suspend power state is
// incompatible with the current power state of other CPUs. This is a somewhat
// normal error and must be handled by callers.
//
// TODO(https://fxbug.dev/417556024): Consider adding a platform-specific or
// custom result type to differentiates between success-but-did-not-power-down
// and powered-down.
//
// TODO(https://fxbug.dev/417558115): Consider checking the state of the
// secondary CPUs in order to determine which power state value to use so that
// we can eliminate the need to return ZX_ERR_ACCESS_DENIED or
// ZX_ERR_INVALID_ARGS in "normal" situations.
//
// TODO(https://fxbug.dev/417558115): Currently, the caller is responsible for
// determining if pausing/resuming the monotonic clock is necessary and then
// actually doing it. More thought needs to be given to where that logic should
// live. Right now, it's done in |IdlePowerThread::UpdateMonotonicClock|,
// however, it might be better to move some of that logic down into the platform
// layer (perhaps within |platform_suspend_cpu|).
zx_status_t platform_suspend_cpu(PlatformAllowDomainPowerDown allow_domain);
// Returns true iff this platform supports |platform_suspend_system|.
bool platform_supports_suspend_system();
// Suspend the entire system from the boot CPU after all secondary CPUs have
// been powered off.
//
// Prior to calling this function, it's critical to set up some kind of
// interrupt that will wake the boot CPU and resume execution.
//
// Prior to calling, all secondary CPUs must be powered off, interrupts must be
// disabled, preemption must be disabled, and the caller must be running on the
// boot CPU.
//
// The calling thread must be a kernel-only thread. Because this routine saves
// only the minimum required register state, it is an error to call this
// function on a thread that has a "user half" (ThreadDispatcher).
//
// Returns ZX_OK on success. Note that this does not necessarily mean that the
// system actually suspended (e.g. it may return immediately if an interrupt is
// pending).
//
// Returns ZX_ERR_NOT_SUPPORTED if unsupported on this platform.
//
// Returns ZX_ERR_BAD_STATE, without suspending, if any secondary CPU is online
// or the platform cannot confirm that every secondary CPU has powered off.
//
// May return other errors if the platform rejects the request.
zx_status_t platform_suspend_system();
// Returns true if this system has a debug serial port that is enabled
extern "C" bool rust_platform_serial_enabled();
inline bool platform_serial_enabled() { return rust_platform_serial_enabled(); }
// Suspend all kernel access to the debug UART hardware, on behalf of
// `zx_debug_suspend`.
//
// Upon successful return, the kernel will not touch the UART hardware (directly
// or indirectly) until `platform_serial_resume` has been called. In particular:
//
// - Blocking writes (`platform_dputs_thread`) write nothing and return
// ZX_ERR_SHOULD_WAIT. Callers may wait for the UART to be resumed using
// `platform_serial_wait_for_resume`.
// - Non-blocking writes (`platform_dputs_irq`, `platform_pputc`) are dropped.
// - Polling reads (`platform_pgetc`) report no data.
// - The UART interrupt is masked.
//
// Must be called from thread context. Blocks, interruptibly, until any
// in-progress UART operations have completed and any output they queued in the
// hardware has been transmitted. Transmission is detected via the driver's
// TxDrained method; drivers which do not implement it are assumed to have
// drained immediately, so with those drivers output still in the hardware FIFO
// may be lost. This is normally brief, but may take indefinitely long if the
// hardware is unable to make progress (e.g. TX is stalled by flow control). If
// the wait is interrupted, the suspend operation is abandoned and the UART is
// left running. No spinlocks are held for long, and no lock is held while
// waiting, so concurrent callers are never blocked for long.
//
// While the suspend operation is in progress, `platform_serial_is_suspended`
// returns true, writers are refused (as though the UART were suspended), and
// concurrent calls to `platform_serial_suspend` and `platform_serial_resume`
// fail with ZX_ERR_BAD_STATE.
//
// Returns:
// - ZX_OK on success.
// - ZX_ERR_NOT_SUPPORTED if there is no debug UART, or if the debuglog is
// being bypassed.
// - ZX_ERR_BAD_STATE if the UART is already suspended, another suspend
// operation is in progress, or the system is halting (see
// `platform_serial_discard_writes_while_suspended`).
// - ZX_ERR_INTERNAL_INTR_KILLED or ZX_ERR_INTERNAL_INTR_RETRY if the calling
// thread was killed or suspended while waiting. The UART is not suspended.
extern "C" zx_status_t rust_platform_serial_suspend();
inline zx_status_t platform_serial_suspend() { return rust_platform_serial_suspend(); }
// Resume kernel access to the debug UART hardware after a previous successful
// call to `platform_serial_suspend`. The caller is responsible for ensuring the
// hardware is powered and clocked before calling.
//
// Must be called from thread context. Does not block for long.
//
// Returns:
// - ZX_OK on success.
// - ZX_ERR_NOT_SUPPORTED if there is no debug UART, or if the debuglog is
// being bypassed.
// - ZX_ERR_BAD_STATE if the UART is not suspended (including while a suspend
// operation is still in progress).
extern "C" zx_status_t rust_platform_serial_resume();
inline zx_status_t platform_serial_resume() { return rust_platform_serial_resume(); }
// Defined in <kernel/wait.h>.
enum class Interruptible : bool;
// Block until the debug UART is not suspended, or until blocking writes are
// being discarded (see `platform_serial_discard_writes_while_suspended`).
//
// Note that by the time this returns, the UART may have been suspended again,
// so callers should be prepared to retry.
//
// If |interruptible| is Interruptible::Yes, the wait may be interrupted by the
// calling thread being killed (returning ZX_ERR_INTERNAL_INTR_KILLED) or
// suspended (returning ZX_ERR_INTERNAL_INTR_RETRY). Otherwise, returns ZX_OK.
//
// Must be called from thread context.
extern "C" zx_status_t rust_platform_serial_wait_for_resume(Interruptible interruptible);
inline zx_status_t platform_serial_wait_for_resume(Interruptible interruptible) {
return rust_platform_serial_wait_for_resume(interruptible);
}
// Cause blocking writes which cannot proceed because the debug UART is
// suspended to be discarded instead of blocking, and release any writers which
// are currently waiting. This is permanent, and is intended to be called as
// the system halts (when the debuglog is shut down) so that a suspended UART
// cannot prevent the system from halting. Has no effect on writes made while
// the UART is not suspended. Once called, `platform_serial_suspend` fails with
// ZX_ERR_BAD_STATE.
//
// Must be called from thread context. Does not block for long. Safe to call
// concurrently with `platform_serial_suspend` and `platform_serial_resume`.
extern "C" void rust_platform_serial_discard_writes_while_suspended();
inline void platform_serial_discard_writes_while_suspended() {
rust_platform_serial_discard_writes_while_suspended();
}
// Returns true if kernel access to the debug UART has been suspended (or a
// suspend operation is in progress) via `platform_serial_suspend`.
//
// Safe to call from any context, including during a panic.
extern "C" bool rust_platform_serial_is_suspended();
inline bool platform_serial_is_suspended() { return rust_platform_serial_is_suspended(); }
// Returns the boot time at which the debug UART was most recently suspended via
// `platform_serial_suspend`. The value is only meaningful when
// `platform_serial_is_suspended` returns true.
//
// Safe to call from any context, including during a panic.
extern "C" zx_instant_boot_t rust_platform_serial_suspended_at();
inline zx_instant_boot_t platform_serial_suspended_at() {
return rust_platform_serial_suspended_at();
}
// platform_panic_start informs the system that a panic message is about
// to be printed and that platform_halt will be called shortly. The
// platform should stop other CPUs if requested and do whatever is necessary
// to safely ensure that the panic message will be visible to the user.
enum class PanicStartHaltOtherCpus { No = 0, Yes };
void platform_panic_start(PanicStartHaltOtherCpus option = PanicStartHaltOtherCpus::Yes);
extern "C" void cpp_platform_panic_start(bool halt_other_cpus);
// Get the state of a CPU.
zx::result<power_cpu_state> platform_get_cpu_state(cpu_num_t cpu_id);
#endif // ZIRCON_KERNEL_INCLUDE_PLATFORM_H_