1 /*
2 * Copyright (c) 2013-2019 Huawei Technologies Co., Ltd. All rights reserved.
3 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without modification,
6 * are permitted provided that the following conditions are met:
7 *
8 * 1. Redistributions of source code must retain the above copyright notice, this list of
9 * conditions and the following disclaimer.
10 *
11 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
12 * of conditions and the following disclaimer in the documentation and/or other materials
13 * provided with the distribution.
14 *
15 * 3. Neither the name of the copyright holder nor the names of its contributors may be used
16 * to endorse or promote products derived from this software without specific prior written
17 * permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
21 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
22 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
23 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
24 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
25 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
26 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
27 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
28 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
29 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 */
31
32 #ifndef _LOS_PM_H
33 #define _LOS_PM_H
34
35 #include "los_config.h"
36 #include "los_compiler.h"
37 #include "los_list.h"
38 #include "los_error.h"
39
40 /**
41 * @ingroup los_pm
42 * Pm error code: Invalid low power mode.
43 *
44 * Value: 0x02002001
45 *
46 */
47 #define LOS_ERRNO_PM_INVALID_MODE LOS_ERRNO_OS_ERROR(LOS_MOD_PM, 0x01)
48
49 /**
50 * @ingroup los_pm
51 * Pm error code: Invalid input parameter.
52 *
53 * Value: 0x02002002
54 *
55 */
56 #define LOS_ERRNO_PM_INVALID_PARAM LOS_ERRNO_OS_ERROR(LOS_MOD_PM, 0x02)
57
58 /**
59 * @ingroup los_pm
60 * Pm error code: The current mode is unlocked.
61 *
62 * Value: 0x02002003
63 *
64 */
65 #define LOS_ERRNO_PM_NOT_LOCK LOS_ERRNO_OS_ERROR(LOS_MOD_PM, 0x03)
66
67 /**
68 * @ingroup los_pm
69 * Pm error code: The lock limit has been exceeded.
70 *
71 * Value: 0x02002004
72 *
73 */
74 #define LOS_ERRNO_PM_LOCK_LIMIT LOS_ERRNO_OS_ERROR(LOS_MOD_PM, 0x04)
75
76 /**
77 * @ingroup los_pm
78 * Pm error code: Invalid device node.
79 *
80 * Value: 0x02002005
81 *
82 */
83 #define LOS_ERRNO_PM_INVALID_NODE LOS_ERRNO_OS_ERROR(LOS_MOD_PM, 0x05)
84
85 /**
86 * @ingroup los_pm
87 * Pm error code: Invalid type.
88 *
89 * Value: 0x02002006
90 *
91 */
92 #define LOS_ERRNO_PM_INVALID_TYPE LOS_ERRNO_OS_ERROR(LOS_MOD_PM, 0x06)
93
94 /**
95 * @ingroup los_pm
96 * Pm error code: The hook for mode is not implemented.
97 *
98 * Value: 0x02002007
99 *
100 */
101 #define LOS_ERRNO_PM_HANDLER_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_PM, 0x07)
102
103 /**
104 * @ingroup los_pm
105 * Pm error code: Deep and shutdown must implement the Tick Timer related interface.
106 *
107 * Value: 0x02002008
108 *
109 */
110 #define LOS_ERRNO_PM_TICK_TIMER_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_PM, 0x08)
111
112 /**
113 * @ingroup los_pm
114 * Pm error code: Device is not registered.
115 *
116 * Value: 0x02002009
117 *
118 */
119 #define LOS_ERRNO_PM_DEVICE_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_PM, 0x09)
120
121 /**
122 * @ingroup los_pm
123 * Pm error code: The delay lock has already been activated.
124 *
125 * Value: 0x0200200a
126 *
127 */
128 #define LOS_ERRNO_PM_ALREADY_LOCK LOS_ERRNO_OS_ERROR(LOS_MOD_PM, 0x0a)
129
130 typedef enum {
131 LOS_SYS_NORMAL_SLEEP = 0,
132 LOS_SYS_LIGHT_SLEEP,
133 LOS_SYS_DEEP_SLEEP,
134 LOS_SYS_SHUTDOWN,
135 } LOS_SysSleepEnum;
136
137 typedef enum {
138 LOS_PM_TYPE_DEVICE = 0,
139 LOS_PM_TYPE_TICK_TIMER,
140 LOS_PM_TYPE_SYSCTRL,
141 } LOS_PmNodeType;
142
143 typedef struct {
144 UINT32 (*suspend)(UINT32 mode); /* The device enters low power consumption, Unlocked task scheduling. */
145 VOID (*resume)(UINT32 mode); /* The device exits from low power consumption, Unlocked task scheduling. */
146 } LosPmDevice;
147
148 typedef struct {
149 UINT32 freq; /* The frequency of the low power timer */
150 VOID (*timerStart)(UINT64); /* Start the low power timer */
151 VOID (*timerStop)(VOID); /* Stop the low power timer */
152 UINT64 (*timerCycleGet)(VOID); /* Gets the running time of the low power timer in unit cycle */
153 VOID (*tickLock)(VOID); /* Pause the system tick timer */
154 VOID (*tickUnlock)(VOID); /* Restore the system tick timer */
155 } LosPmTickTimer;
156
157 typedef struct {
158 /* Preparations before the CPU enters low power consumption.
159 * All modes except normal mode are invoked.
160 * Unlocked task scheduling.
161 */
162 UINT32 (*early)(UINT32 mode);
163 /* The system performs low-power recovery.
164 * All modes except normal mode are invoked.
165 * Unlocked task scheduling.
166 */
167 VOID (*late)(UINT32 mode);
168 /* Final check before low-power consumption. */
169 VOID (*suspendCheck)(UINT32 mode);
170 /* The system enters the Normal sleep mode.
171 * In normal mode, the value cannot be NULL.
172 */
173 UINT32 (*normalSuspend)(VOID);
174 /* The system recovers from normal sleep.
175 * The value can be NULL.
176 */
177 VOID (*normalResume)(VOID);
178 /* The system enters the light sleep mode.
179 * In light sleep mode, the value cannot be NULL.
180 */
181 UINT32 (*lightSuspend)(VOID);
182 /* The system recovers from light sleep.
183 * The value can be NULL.
184 */
185 VOID (*lightResume)(VOID);
186 /* The system enters the deep sleep mode.
187 * In deep sleep mode, the value cannot be NULL.
188 */
189 UINT32 (*deepSuspend)(VOID);
190 /* The system recovers from deep sleep.
191 * The value can be NULL.
192 */
193 VOID (*deepResume)(VOID);
194 /* The system enters the shutdown mode.
195 * In shutdown mode, the value cannot be NULL.
196 */
197 UINT32 (*shutdownSuspend)(VOID);
198 /* The system recovers from shutdown.
199 * In shutdown mode, the value cannot be NULL.
200 */
201 VOID (*shutdownResume)(VOID);
202 } LosPmSysctrl;
203
204 /**
205 * @ingroup los_pm
206 * @brief Initialize system low power frame.
207 *
208 * @par Description:
209 * This API is used to initialize the system low power frame.
210 *
211 * @attention None.
212 *
213 * @param None.
214 *
215 * @retval error code, LOS_OK means success.
216 * @par Dependency:
217 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
218 * @see
219 */
220 UINT32 OsPmInit(VOID);
221
222 /**
223 * @ingroup los_pm
224 * @brief Whether the low power consumption condition is met.
225 *
226 * @par Description:
227 * This API is used to check whether low power consumption is met.
228 *
229 * @attention None.
230 *
231 * @param None.
232 *
233 * @retval TRUE or FALSE.
234 * @par Dependency:
235 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
236 * @see
237 */
238 #if (LOSCFG_KERNEL_PM == 1)
239 BOOL OsIsPmMode(VOID);
240 #else
OsIsPmMode(VOID)241 STATIC INLINE BOOL OsIsPmMode(VOID)
242 {
243 return FALSE;
244 }
245 #endif
246
247 /**
248 * @ingroup los_pm
249 * @brief Register a power management node.
250 *
251 * @par Description:
252 * This API is used to register a power management node.
253 *
254 * @attention None.
255 *
256 * @param type [IN] The types supported by the PM module.
257 * @param node [IN] power management node.
258 *
259 * @retval error code, LOS_OK means success.
260 * @par Dependency:
261 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
262 * @see LOS_PmUnregister
263 */
264 UINT32 LOS_PmRegister(LOS_PmNodeType type, VOID *node);
265
266 /**
267 * @ingroup los_pm
268 * @brief Unregister a power management node.
269 *
270 * @par Description:
271 * This API is used to unregister a power management node.
272 *
273 * @attention None.
274 *
275 * @param type [IN] The types supported by the PM module.
276 * @param node [IN] power management node.
277 *
278 * @retval error code, LOS_OK means success.
279 * @par Dependency:
280 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
281 * @see LOS_PmRegister
282 */
283 UINT32 LOS_PmUnregister(LOS_PmNodeType type, VOID *node);
284
285 /**
286 * @ingroup los_pm
287 * @brief Set the system wake up flag.
288 *
289 * @par Description:
290 * This API is used to set the system wake-up flag.
291 *
292 * @attention None.
293 *
294 * @param None.
295 *
296 * @retval None.
297 * @par Dependency:
298 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
299 * @see
300 */
301 VOID LOS_PmWakeSet(VOID);
302
303 /**
304 * @ingroup los_pm
305 * @brief Get the low power mode of the current system.
306 *
307 * @par Description:
308 * This API is used to get the low power mode of the current system.
309 *
310 * @attention None.
311 *
312 * @param None.
313 *
314 * @retval error code, LOS_OK means success.
315 * @par Dependency:
316 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
317 * @see LOS_PmModeSet
318 */
319 LOS_SysSleepEnum LOS_PmModeGet(VOID);
320
321 /**
322 * @ingroup los_pm
323 * @brief Set low power mode.
324 *
325 * @par Description:
326 * This API is used to set low power mode.
327 *
328 * @attention None.
329 *
330 * @param mode [IN] low power mode.
331 *
332 * @retval error code, LOS_OK means success.
333 * @par Dependency:
334 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
335 * @see LOS_PmModeGet
336 */
337 UINT32 LOS_PmModeSet(LOS_SysSleepEnum mode);
338
339 /**
340 * @ingroup los_pm
341 * @brief Request to obtain the lock in current mode, so that the system will not enter
342 * this mode when it enters the idle task next time.
343 *
344 * @par Description:
345 * This API is used to obtain the lock in current mode.
346 *
347 * @attention None.
348 *
349 * @param name [IN] Who requests the lock.
350 *
351 * @retval error code, LOS_OK means success.
352 * @par Dependency:
353 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
354 * @see LOS_PmLockRelease
355 */
356 UINT32 LOS_PmLockRequest(const CHAR *name);
357
358 /**
359 * @ingroup los_pm
360 * @brief Request to obtain the lock in current mode, so that the system will not enter
361 * this mode when it enters the idle task next time. After the specified interval, the
362 * lock is automatically released.
363 *
364 * @par Description:
365 * This API is used to obtain the delay lock in current mode.
366 *
367 * @attention None.
368 *
369 * @param name [IN] Who requests the lock.
370 * @param millisecond [IN] Specifies the time to automatically release the lock.
371 *
372 * @retval error code, LOS_OK means success.
373 * @par Dependency:
374 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
375 * @see LOS_PmLockRelease
376 */
377 UINT32 LOS_PmTimeLockRequest(const CHAR *name, UINT64 millisecond);
378
379 /**
380 * @ingroup los_pm
381 * @brief Release the lock in current mode so that the next time the system enters
382 * the idle task, it will enter this mode.
383 *
384 * @par Description:
385 * This API is used to release the lock in current mode.
386 *
387 * @attention None.
388 *
389 * @param name [IN] Who releases the lock.
390 *
391 * @retval error code, LOS_OK means success.
392 * @par Dependency:
393 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
394 * @see LOS_PmLockRequest
395 */
396 UINT32 LOS_PmLockRelease(const CHAR *name);
397
398 /**
399 * @ingroup los_pm
400 * @brief Gets the current PM lock status.
401 *
402 * @par Description:
403 * This API is used to Get the current PM lock status.
404 *
405 * @attention None.
406 *
407 * @param None.
408 *
409 * @retval Number of awakening sources of the device.
410 * @par Dependency:
411 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
412 * @see
413 */
414 UINT32 LOS_PmReadLock(VOID);
415
416 /**
417 * @ingroup los_pm
418 * @brief The system enters the low-power flow.
419 *
420 * @par Description:
421 * This API is used to enter the system into a low-power process.
422 *
423 * @attention None.
424 *
425 * @param wakeCount [IN] Number of wake sources.
426 *
427 * @retval error code, LOS_OK means success.
428 * @par Dependency:
429 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
430 * @see
431 */
432 UINT32 LOS_PmSuspend(UINT32 wakeCount);
433
434 /**
435 * @ingroup los_pm
436 * @brief Output the locking information of the pm lock.
437 *
438 * @par Description:
439 * This API is used to output the locking information of the pm lock.
440 *
441 * @attention None.
442 *
443 * @param None.
444 *
445 * @retval error code, LOS_OK means success.
446 * @par Dependency:
447 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
448 * @see LOS_PmLockRequest
449 */
450 VOID LOS_PmLockInfoShow(VOID);
451 #endif
452