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