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 /* Low-power timer related implementation functions.
150 * The function is not NULL, the low-power timer is enabled.
151 */
152 UINT32 freq; /* The frequency of the low-power timer */
153 VOID (*timerStart)(UINT64); /* Start the low-power timer and set the response period */
154 VOID (*timerStop)(VOID); /* Turn off the low-power timer */
155 UINT64 (*timerCycleGet)(VOID); /* Gets the time the system sleeps */
156
157 /* When the low-power timer is enabled, the function of tickLock is to turn off the system tick timer and
158 * clear the timer's count value to zero.
159 * When the low-power timer is disabled, the function of tickLock is to pause the system timer.
160 */
161 VOID (*tickLock)(VOID);
162
163 /* When the low-power timer is enabled, the function of tickUnlock is to restart the system tick timer.
164 * When the low-power timer is disabled, the function of tickUnlock is to restore the system tick timer.
165 */
166 VOID (*tickUnlock)(VOID);
167 } LosPmTickTimer;
168
169 typedef struct {
170 /* Preparations before the CPU enters low-power consumption.
171 * All modes except normal mode are invoked.
172 * Unlocked task scheduling.
173 */
174 UINT32 (*early)(UINT32 mode);
175 /* The system performs low-power recovery.
176 * All modes except normal mode are invoked.
177 * Unlocked task scheduling.
178 */
179 VOID (*late)(UINT32 mode);
180 /* Final check before low-power consumption. */
181 VOID (*suspendCheck)(UINT32 mode);
182 /* The system enters the Normal sleep mode.
183 * In normal mode, the value cannot be NULL.
184 */
185 UINT32 (*normalSuspend)(VOID);
186 /* The system recovers from normal sleep.
187 * The value can be NULL.
188 */
189 VOID (*normalResume)(VOID);
190 /* The system enters the light sleep mode.
191 * In light sleep mode, the value cannot be NULL.
192 */
193 UINT32 (*lightSuspend)(VOID);
194 /* The system recovers from light sleep.
195 * The value can be NULL.
196 */
197 VOID (*lightResume)(VOID);
198 /* The system enters the deep sleep mode.
199 * In deep sleep mode, the value cannot be NULL.
200 */
201 UINT32 (*deepSuspend)(VOID);
202 /* The system recovers from deep sleep.
203 * The value can be NULL.
204 */
205 VOID (*deepResume)(VOID);
206 /* The system enters the shutdown mode.
207 * In shutdown mode, the value cannot be NULL.
208 */
209 UINT32 (*shutdownSuspend)(VOID);
210 /* The system recovers from shutdown.
211 * In shutdown mode, the value cannot be NULL.
212 */
213 VOID (*shutdownResume)(VOID);
214 } LosPmSysctrl;
215
216 /**
217 * @ingroup los_pm
218 * @brief Initialize system low-power frame.
219 *
220 * @par Description:
221 * This API is used to initialize the system low-power frame.
222 *
223 * @attention None.
224 *
225 * @param None.
226 *
227 * @retval error code, LOS_OK means success.
228 * @par Dependency:
229 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
230 * @see
231 */
232 UINT32 OsPmInit(VOID);
233
234 /**
235 * @ingroup los_pm
236 * @brief Whether the low-power consumption condition is met.
237 *
238 * @par Description:
239 * This API is used to check whether low-power consumption is met.
240 *
241 * @attention None.
242 *
243 * @param None.
244 *
245 * @retval TRUE or FALSE.
246 * @par Dependency:
247 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
248 * @see
249 */
250 #if (LOSCFG_KERNEL_PM == 1)
251 BOOL OsIsPmMode(VOID);
252 #else
OsIsPmMode(VOID)253 STATIC INLINE BOOL OsIsPmMode(VOID)
254 {
255 return FALSE;
256 }
257 #endif
258
259 /**
260 * @ingroup los_pm
261 * @brief Register a power management node.
262 *
263 * @par Description:
264 * This API is used to register a power management node.
265 *
266 * @attention None.
267 *
268 * @param type [IN] The types supported by the PM module.
269 * @param node [IN] power management node.
270 *
271 * @retval error code, LOS_OK means success.
272 * @par Dependency:
273 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
274 * @see LOS_PmUnregister
275 */
276 UINT32 LOS_PmRegister(LOS_PmNodeType type, VOID *node);
277
278 /**
279 * @ingroup los_pm
280 * @brief Unregister a power management node.
281 *
282 * @par Description:
283 * This API is used to unregister a power management node.
284 *
285 * @attention None.
286 *
287 * @param type [IN] The types supported by the PM module.
288 * @param node [IN] power management node.
289 *
290 * @retval error code, LOS_OK means success.
291 * @par Dependency:
292 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
293 * @see LOS_PmRegister
294 */
295 UINT32 LOS_PmUnregister(LOS_PmNodeType type, VOID *node);
296
297 /**
298 * @ingroup los_pm
299 * @brief Set the system wake up flag.
300 *
301 * @par Description:
302 * This API is used to set the system wake-up flag.
303 *
304 * @attention None.
305 *
306 * @param None.
307 *
308 * @retval None.
309 * @par Dependency:
310 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
311 * @see
312 */
313 VOID LOS_PmWakeSet(VOID);
314
315 /**
316 * @ingroup los_pm
317 * @brief Get the low-power mode of the current system.
318 *
319 * @par Description:
320 * This API is used to get the low-power mode of the current system.
321 *
322 * @attention None.
323 *
324 * @param None.
325 *
326 * @retval error code, LOS_OK means success.
327 * @par Dependency:
328 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
329 * @see LOS_PmModeSet
330 */
331 LOS_SysSleepEnum LOS_PmModeGet(VOID);
332
333 /**
334 * @ingroup los_pm
335 * @brief Set low-power mode.
336 *
337 * @par Description:
338 * This API is used to set low-power mode.
339 *
340 * @attention None.
341 *
342 * @param mode [IN] low-power mode.
343 *
344 * @retval error code, LOS_OK means success.
345 * @par Dependency:
346 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
347 * @see LOS_PmModeGet
348 */
349 UINT32 LOS_PmModeSet(LOS_SysSleepEnum mode);
350
351 /**
352 * @ingroup los_pm
353 * @brief Request to obtain the lock in current mode, so that the system will not enter
354 * this mode when it enters the idle task next time.
355 *
356 * @par Description:
357 * This API is used to obtain the lock in current mode.
358 *
359 * @attention None.
360 *
361 * @param name [IN] Who requests the lock.
362 *
363 * @retval error code, LOS_OK means success.
364 * @par Dependency:
365 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
366 * @see LOS_PmLockRelease
367 */
368 UINT32 LOS_PmLockRequest(const CHAR *name);
369
370 /**
371 * @ingroup los_pm
372 * @brief Request to obtain the lock in current mode, so that the system will not enter
373 * this mode when it enters the idle task next time. After the specified interval, the
374 * lock is automatically released.
375 *
376 * @par Description:
377 * This API is used to obtain the delay lock in current mode.
378 *
379 * @attention None.
380 *
381 * @param name [IN] Who requests the lock.
382 * @param millisecond [IN] Specifies the time to automatically release the lock.
383 *
384 * @retval error code, LOS_OK means success.
385 * @par Dependency:
386 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
387 * @see LOS_PmLockRelease
388 */
389 UINT32 LOS_PmTimeLockRequest(const CHAR *name, UINT64 millisecond);
390
391 /**
392 * @ingroup los_pm
393 * @brief Release the lock in current mode so that the next time the system enters
394 * the idle task, it will enter this mode.
395 *
396 * @par Description:
397 * This API is used to release the lock in current mode.
398 *
399 * @attention None.
400 *
401 * @param name [IN] Who releases the lock.
402 *
403 * @retval error code, LOS_OK means success.
404 * @par Dependency:
405 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
406 * @see LOS_PmLockRequest
407 */
408 UINT32 LOS_PmLockRelease(const CHAR *name);
409
410 /**
411 * @ingroup los_pm
412 * @brief Gets the current PM lock status.
413 *
414 * @par Description:
415 * This API is used to Get the current PM lock status.
416 *
417 * @attention None.
418 *
419 * @param None.
420 *
421 * @retval Number of awakening sources of the device.
422 * @par Dependency:
423 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
424 * @see
425 */
426 UINT32 LOS_PmReadLock(VOID);
427
428 /**
429 * @ingroup los_pm
430 * @brief The system enters the low-power flow.
431 *
432 * @par Description:
433 * This API is used to enter the system into a low-power process.
434 *
435 * @attention None.
436 *
437 * @param wakeCount [IN] Number of wake sources.
438 *
439 * @retval error code, LOS_OK means success.
440 * @par Dependency:
441 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
442 * @see
443 */
444 UINT32 LOS_PmSuspend(UINT32 wakeCount);
445
446 /**
447 * @ingroup los_pm
448 * @brief Output the locking information of the pm lock.
449 *
450 * @par Description:
451 * This API is used to output the locking information of the pm lock.
452 *
453 * @attention None.
454 *
455 * @param None.
456 *
457 * @retval error code, LOS_OK means success.
458 * @par Dependency:
459 * <ul><li>los_pm.h: the header file that contains the API declaration.</li></ul>
460 * @see LOS_PmLockRequest
461 */
462 VOID LOS_PmLockInfoShow(VOID);
463 #endif
464