1 /* 2 * Copyright (c) 2022, Carlo Caione <ccaione@baylibre.com> 3 */ 4 5 /** 6 * @file 7 * 8 * @brief public S2RAM APIs. 9 * @defgroup pm_s2ram S2RAM APIs 10 * @ingroup subsys_pm 11 * @{ 12 */ 13 14 #ifndef ZEPHYR_INCLUDE_ARCH_COMMON_PM_S2RAM_H_ 15 #define ZEPHYR_INCLUDE_ARCH_COMMON_PM_S2RAM_H_ 16 17 #ifdef _ASMLANGUAGE 18 GTEXT(arch_pm_s2ram_suspend); 19 #else 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 /** 26 * @brief System off function 27 * 28 * This function is passed as argument and called by @ref arch_pm_s2ram_suspend 29 * to power the system off after the CPU context has been saved. 30 * 31 * This function never returns if the system is powered off. If the operation 32 * cannot be performed a proper value is returned and the code must take care 33 * of restoring the system in a fully operational state before returning. 34 * 35 * @retval none The system is powered off. 36 * @retval -EBUSY The system is busy and cannot be powered off at this time. 37 * @retval -errno Other error codes. 38 */ 39 typedef int (*pm_s2ram_system_off_fn_t)(void); 40 41 /** 42 * @brief Save CPU context on suspend 43 * 44 * This function is used on suspend-to-RAM (S2RAM) to save the CPU context in 45 * (retained) RAM before powering the system off using the provided function. 46 * This function is usually called from the PM subsystem / hooks. 47 * 48 * The CPU context is usually the minimum set of CPU registers which content 49 * must be restored on resume to let the platform resume its execution from the 50 * point it left at the time of suspension. 51 * 52 * @param system_off Function to power off the system. 53 * 54 * @retval 0 The CPU context was successfully saved and restored. 55 * @retval -EBUSY The system is busy and cannot be suspended at this time. 56 * @retval -errno Negative errno code in case of failure. 57 */ 58 int arch_pm_s2ram_suspend(pm_s2ram_system_off_fn_t system_off); 59 60 /** 61 * @brief Mark that core is entering suspend-to-RAM state. 62 * 63 * Function is called when system state is stored to RAM, just before going to system 64 * off. 65 * 66 * Default implementation is setting a magic word in RAM. CONFIG_PM_S2RAM_CUSTOM_MARKING 67 * allows custom implementation. 68 */ 69 void pm_s2ram_mark_set(void); 70 71 /** 72 * @brief Check suspend-to-RAM marking and clear its state. 73 * 74 * Function is used to determine if resuming after suspend-to-RAM shall be performed 75 * or standard boot code shall be executed. 76 * 77 * Default implementation is checking a magic word in RAM. CONFIG_PM_S2RAM_CUSTOM_MARKING 78 * allows custom implementation. 79 * 80 * @retval true if marking is found which indicates resuming after suspend-to-RAM. 81 * @retval false if marking is not found which indicates standard boot. 82 */ 83 bool pm_s2ram_mark_check_and_clear(void); 84 /** 85 * @} 86 */ 87 88 #ifdef __cplusplus 89 } 90 #endif 91 92 #endif /* _ASMLANGUAGE */ 93 94 #endif /* ZEPHYR_INCLUDE_ARCH_COMMON_PM_S2RAM_H_ */ 95
