Line data    Source code

       1            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            1 : 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            1 : 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            1 : 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            1 : 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_ */