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