1 /***************************************************************************//**
2  * @file
3  * @brief Power Manager Private API definition.
4  *******************************************************************************
5  * # License
6  * <b>Copyright 2019 Silicon Laboratories Inc. www.silabs.com</b>
7  *******************************************************************************
8  *
9  * SPDX-License-Identifier: Zlib
10  *
11  * The licensor of this software is Silicon Laboratories Inc.
12  *
13  * This software is provided 'as-is', without any express or implied
14  * warranty. In no event will the authors be held liable for any damages
15  * arising from the use of this software.
16  *
17  * Permission is granted to anyone to use this software for any purpose,
18  * including commercial applications, and to alter it and redistribute it
19  * freely, subject to the following restrictions:
20  *
21  * 1. The origin of this software must not be misrepresented; you must not
22  *    claim that you wrote the original software. If you use this software
23  *    in a product, an acknowledgment in the product documentation would be
24  *    appreciated but is not required.
25  * 2. Altered source versions must be plainly marked as such, and must not be
26  *    misrepresented as being the original software.
27  * 3. This notice may not be removed or altered from any source distribution.
28  *
29  ******************************************************************************/
30 
31 #ifndef SLI_POWER_MANAGER_H
32 #define SLI_POWER_MANAGER_H
33 
34 #include "sl_power_manager.h"
35 
36 #include <stdbool.h>
37 #include <stdint.h>
38 
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42 
43 /*******************************************************************************
44  ******************************   HOOK REFERENCES   ****************************
45  ******************************************************************************/
46 
47 SL_CODE_CLASSIFY(SL_CODE_COMPONENT_POWER_MANAGER, SL_CODE_CLASS_TIME_CRITICAL)
48 bool sl_power_manager_sleep_on_isr_exit(void);
49 
50 // Callback to application after wakeup but before restoring interrupts.
51 // For internal Silicon Labs use only
52 SL_CODE_CLASSIFY(SL_CODE_COMPONENT_POWER_MANAGER, SL_CODE_CLASS_TIME_CRITICAL)
53 __WEAK void sli_power_manager_on_wakeup(void);
54 
55 // Hook that can be used by the log outputer to suspend transmission of logs
56 // in case it would require energy mode changes while in the sleep loop.
57 SL_CODE_CLASSIFY(SL_CODE_COMPONENT_POWER_MANAGER, SL_CODE_CLASS_TIME_CRITICAL)
58 __WEAK void sli_power_manager_suspend_log_transmission(void);
59 
60 // Hook that can be used by the log outputer to resume transmission of logs.
61 SL_CODE_CLASSIFY(SL_CODE_COMPONENT_POWER_MANAGER, SL_CODE_CLASS_TIME_CRITICAL)
62 __WEAK void sli_power_manager_resume_log_transmission(void);
63 
64 // Callback to notify possible transition from EM1P to EM2.
65 // For internal Silicon Labs use only
66 SL_CODE_CLASSIFY(SL_CODE_COMPONENT_POWER_MANAGER, SL_CODE_CLASS_TIME_CRITICAL)
67 __WEAK void sli_power_manager_em1p_to_em2_notification(void);
68 
69 /***************************************************************************//**
70  * Mandatory callback that allows to cancel sleeping action.
71  ******************************************************************************/
72 SL_CODE_CLASSIFY(SL_CODE_COMPONENT_POWER_MANAGER, SL_CODE_CLASS_TIME_CRITICAL)
73 bool sl_power_manager_is_ok_to_sleep(void);
74 
75 /*******************************************************************************
76  *****************************   PROTOTYPES   **********************************
77  ******************************************************************************/
78 
79 void sli_power_manager_update_hf_clock_settings_preservation_requirement(bool add);
80 
81 /***************************************************************************//**
82  * Adds requirement on the preservation of the High Frequency Clocks settings.
83  *
84  * @note FOR INTERNAL USE ONLY.
85  *
86  * @note Must be used together with adding an EM2 requirement.
87  ******************************************************************************/
88 void sli_power_manager_add_hf_clock_settings_preservation_requirement(void);
89 
90 /***************************************************************************//**
91  * Removes requirement on the preservation of the High Frequency Clocks settings.
92  *
93  * @note FOR INTERNAL USE ONLY.
94  *
95  * @note Must be used together with removing an EM2 requirement.
96  ******************************************************************************/
97 void sli_power_manager_remove_hf_clock_settings_preservation_requirement(void);
98 
99 /***************************************************************************//**
100  * Informs the power manager module that the high accuracy/high frequency clock
101  * is used.
102  *
103  * @note FOR INTERNAL USE ONLY.
104  *
105  * @note Must be called by RAIL initialization in case radio clock settings
106  *       are not set before the Power Manager initialization.
107  ******************************************************************************/
108 __WEAK void sli_power_manager_set_high_accuracy_hf_clock_as_used(void);
109 
110 /***************************************************************************//**
111  * Gets the wake-up restore process time.
112  * If we are not in the context of a deepsleep and therefore don't need to
113  * do a restore, the return value is 0.
114  *
115  *
116  * @return   Wake-up restore process time.
117  ******************************************************************************/
118 SL_CODE_CLASSIFY(SL_CODE_COMPONENT_POWER_MANAGER, SL_CODE_CLASS_TIME_CRITICAL)
119 uint32_t sli_power_manager_get_restore_delay(void);
120 
121 /***************************************************************************//**
122  * Initiates the wake-up restore process.
123  ******************************************************************************/
124 void sli_power_manager_initiate_restore(void);
125 
126 /***************************************************************************//**
127  * Performs pre sleep operations.
128  *
129  * @note Must only be called by the RTOS integration code.
130  ******************************************************************************/
131 void sli_power_manager_pre_sleep(void);
132 
133 /***************************************************************************//**
134  * Fetches current energy mode
135  *
136  * @return Returns current energy mode
137  ******************************************************************************/
138 sl_power_manager_em_t sli_power_manager_get_current_em(void);
139 
140 /***************************************************************************//**
141  * Update Energy Mode 4 configurations.
142  ******************************************************************************/
143 void sli_power_manager_init_em4(void);
144 
145 /***************************************************************************//**
146  * Enable or disable fast wake-up in EM2 and EM3
147  *
148  * @note Will also update the wake up time from EM2 to EM0.
149  ******************************************************************************/
150 void sli_power_manager_em23_voltage_scaling_enable_fast_wakeup(bool enable);
151 
152 /***************************************************************************//**
153  * Initializes energy mode transition list.
154  ******************************************************************************/
155 void sli_power_manager_em_transition_event_list_init(void);
156 
157 /***************************************************************************//**
158  * Notify subscribers about energy mode transition.
159  *
160  * @param  from  Energy mode from which CPU comes from.
161  *
162  * @param  to    Energy mode to which CPU is going to.
163  ******************************************************************************/
164 SL_CODE_CLASSIFY(SL_CODE_COMPONENT_POWER_MANAGER, SL_CODE_CLASS_TIME_CRITICAL)
165 void sli_power_manager_notify_em_transition(sl_power_manager_em_t from,
166                                             sl_power_manager_em_t to);
167 
168 #ifdef __cplusplus
169 }
170 #endif
171 
172 #endif /* SLI_POWER_MANAGER_H */
173