1// Copyright 2016 The Fuchsia Authors
2// Copyright (c) 2008 Travis Geiselbrecht
3//
4// Use of this source code is governed by a MIT-style
5// license that can be found in the LICENSE file or at
6// https://opensource.org/licenses/MIT
7
8#pragma once
9
10#include <sys/types.h>
11#include <zircon/compiler.h>
12#include <zircon/types.h>
13
14__BEGIN_CDECLS
15
16#define BOOT_CPU_ID 0
17
18typedef enum {
19    HALT_ACTION_HALT = 0,           // Spin forever.
20    HALT_ACTION_REBOOT,             // Reset the CPU.
21    HALT_ACTION_REBOOT_BOOTLOADER,  // Reboot into the bootloader.
22    HALT_ACTION_REBOOT_RECOVERY,    // Reboot into the recovery partition.
23    HALT_ACTION_SHUTDOWN,           // Shutdown and power off.
24} platform_halt_action;
25
26typedef enum {
27    HALT_REASON_UNKNOWN = 0,
28    HALT_REASON_SW_RESET,       // Generic Software Initiated Reboot
29    HALT_REASON_SW_PANIC,       // Reboot triggered by a SW panic or ASSERT
30} platform_halt_reason;
31
32/* current time in nanoseconds */
33zx_time_t current_time(void);
34
35/* high-precision timer ticks per second */
36zx_ticks_t ticks_per_second(void);
37
38/* high-precision timer current_ticks */
39zx_ticks_t current_ticks(void);
40
41/* super early platform initialization, before almost everything */
42void platform_early_init(void);
43
44/* later init, after the kernel has come up */
45void platform_init(void);
46
47/* called by the arch init code to get the platform to set up any mmu mappings it may need */
48void platform_init_mmu_mappings(void);
49
50/* if the platform has knowledge of what caused the latest reboot, it can report
51 * it to applications with this function.  */
52platform_halt_reason platform_get_reboot_reason(void);
53
54
55/* platform_panic_start informs the system that a panic message is about
56 * to be printed and that platformn_halt will be called shortly.  The
57 * platform should stop other CPUs if possible and do whatever is necessary
58 * to safely ensure that the panic message will be visible to the user.
59 */
60void platform_panic_start(void);
61
62/* platform_halt halts the system and performs the |suggested_action|.
63 *
64 * This function is used in both the graceful shutdown and panic paths so it
65 * does not perform more complex actions like switching to the primary CPU,
66 * unloading the run queue of secondary CPUs, stopping secondary CPUs, etc.
67 *
68 * There is no returning from this function.
69 */
70void platform_halt(platform_halt_action suggested_action,
71                   platform_halt_reason reason) __NO_RETURN;
72
73/* optionally stop the current cpu in a way the platform finds appropriate */
74void platform_halt_cpu(void);
75
76/* platform_halt_secondary_cpus halts secondary (non-boot) CPUs.
77 *
78 * While the mechanism used is platform dependent, this function attempts to shut them down
79 * gracefully so that secondary CPUs aren't holding any spinlocks.
80 *
81 * This function must be called from the primary (boot) CPU.
82 */
83void platform_halt_secondary_cpus(void);
84
85/* called during chain loading to make sure drivers and platform is put into a stopped state */
86void platform_quiesce(void);
87
88/* returns pointer to ramdisk image, or NULL if none.
89 * Sets size to ramdisk size or zero if none.
90 */
91void *platform_get_ramdisk(size_t *size);
92
93/* Stash the crashlog somewhere platform-specific that allows
94 * for recovery after reboot.  This will only be called out
95 * of the panic() handling path on the way to reboot, and is
96 * not necessarily safe to be called from any other state.
97 *
98 * Calling with a NULL log returns the maximum supported size.
99 * It is safe to query the size at any time after boot.  If the
100 * return is 0, no crashlog recovery is supported.
101 */
102size_t platform_stow_crashlog(void* log, size_t len);
103
104/* If len == 0, return the length of the last crashlog (or 0 if none).
105 * Otherwise call func() to return the last crashlog to the caller,
106 * returning the length the last crashlog.
107 *
108 * func() may be called as many times as necessary (adjusting off)
109 * to return the crashlog in segments.  There will not be gaps,
110 * but the individual segments may range from 1 byte to the full
111 * length requested, depending on the limitations of the underlying
112 * storage model.
113 */
114size_t platform_recover_crashlog(size_t len, void* cookie,
115                                 void (*func)(const void* data, size_t off, size_t len, void* cookie));
116
117// Called just before initiating a system suspend to give the platform layer a
118// chance to save state.  Must be called with interrupts disabled.
119void platform_suspend(void);
120
121// Called immediately after resuming from a system suspend to let the platform layer
122// reinitialize arch components.  Must be called with interrupts disabled.
123void platform_resume(void);
124
125// Returns true if this system has a debug serial port that is enabled
126bool platform_serial_enabled(void);
127
128// Returns true if the early graphics console is enabled
129bool platform_early_console_enabled(void);
130
131__END_CDECLS
132