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 * The following requirements must be fulfilled: 69 * - the function cannot use stack (asm function or function with 'naked' attribute) 70 * - the content of the R1 and R4 registers must remain unchanged 71 * - returning from the function should be performed with the `bx lr` instruction 72 * 73 */ 74 void pm_s2ram_mark_set(void); 75 76 /** 77 * @brief Check suspend-to-RAM marking and clear its state. 78 * 79 * Function is used to determine if resuming after suspend-to-RAM shall be performed 80 * or standard boot code shall be executed. 81 * 82 * Default implementation is checking a magic word in RAM. CONFIG_PM_S2RAM_CUSTOM_MARKING 83 * allows custom implementation. 84 * The following requirements must be fulfilled: 85 * - the function cannot use stack (most likely asm function) 86 * - the content of the R1 and R4 registers must remain unchanged 87 * - the function's return value is passed by R0 register 88 * - returning from the function should be performed with the `bx lr` instruction 89 * 90 * @retval true if marking is found which indicates resuming after suspend-to-RAM. 91 * @retval false if marking is not found which indicates standard boot. 92 */ 93 bool pm_s2ram_mark_check_and_clear(void); 94 /** 95 * @} 96 */ 97 98 #ifdef __cplusplus 99 } 100 #endif 101 102 #endif /* _ASMLANGUAGE */ 103 104 #endif /* ZEPHYR_INCLUDE_ARCH_COMMON_PM_S2RAM_H_ */ 105
