1 /**
2 * \file
3 *
4 * \brief Sleep manager
5 *
6 * Copyright (c) 2010-2016 Atmel Corporation. All rights reserved.
7 *
8 * \asf_license_start
9 *
10 * \page License
11 *
12 * Redistribution and use in source and binary forms, with or without
13 * modification, are permitted provided that the following conditions are met:
14 *
15 * 1. Redistributions of source code must retain the above copyright notice,
16 * this list of conditions and the following disclaimer.
17 *
18 * 2. Redistributions in binary form must reproduce the above copyright notice,
19 * this list of conditions and the following disclaimer in the documentation
20 * and/or other materials provided with the distribution.
21 *
22 * 3. The name of Atmel may not be used to endorse or promote products derived
23 * from this software without specific prior written permission.
24 *
25 * 4. This software may only be redistributed and used in connection with an
26 * Atmel microcontroller product.
27 *
28 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
29 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
30 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
31 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
32 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
33 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
34 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
35 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
36 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
37 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
38 * POSSIBILITY OF SUCH DAMAGE.
39 *
40 * \asf_license_stop
41 *
42 */
43 /*
44 * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
45 */
46 #ifndef SLEEPMGR_H
47 #define SLEEPMGR_H
48
49 #include <compiler.h>
50 #include <parts.h>
51
52 #if (SAM3S || SAM3U || SAM3N || SAM3XA || SAM4S || SAM4E || SAM4N || SAM4C || SAMG || SAM4CP || SAM4CM || SAMV71 || SAMV70 || SAMS70 || SAME70)
53 # include "sam/sleepmgr.h"
54 #elif XMEGA
55 # include "xmega/sleepmgr.h"
56 #elif UC3
57 # include "uc3/sleepmgr.h"
58 #elif SAM4L
59 # include "sam4l/sleepmgr.h"
60 #elif MEGA
61 # include "mega/sleepmgr.h"
62 #elif (SAMD20 || SAMD21 || SAMR21 || SAMD11 || SAMDA1)
63 # include "samd/sleepmgr.h"
64 #elif (SAML21 || SAML22 || SAMR30)
65 # include "saml/sleepmgr.h"
66 #elif (SAMC21)
67 # include "samc/sleepmgr.h"
68 #else
69 # error Unsupported device.
70 #endif
71
72 #ifdef __cplusplus
73 extern "C" {
74 #endif
75
76 /**
77 * \defgroup sleepmgr_group Sleep manager
78 *
79 * The sleep manager is a service for ensuring that the device is not put to
80 * sleep in deeper sleep modes than the system (e.g., peripheral drivers,
81 * services or the application) allows at any given time.
82 *
83 * It is based on the use of lock counting for the individual sleep modes, and
84 * will put the device to sleep in the shallowest sleep mode that has a non-zero
85 * lock count. The drivers/services/application can change these counts by use
86 * of \ref sleepmgr_lock_mode and \ref sleepmgr_unlock_mode.
87 * Refer to \ref sleepmgr_mode for a list of the sleep modes available for
88 * locking, and the device datasheet for information on their effect.
89 *
90 * The application must supply the file \ref conf_sleepmgr.h.
91 *
92 * For the sleep manager to be enabled, the symbol \ref CONFIG_SLEEPMGR_ENABLE
93 * must be defined, e.g., in \ref conf_sleepmgr.h. If this symbol is not
94 * defined, the functions are replaced with dummy functions and no RAM is used.
95 *
96 * @{
97 */
98
99 /**
100 * \def CONFIG_SLEEPMGR_ENABLE
101 * \brief Configuration symbol for enabling the sleep manager
102 *
103 * If this symbol is not defined, the functions of this service are replaced
104 * with dummy functions. This is useful for reducing code size and execution
105 * time if the sleep manager is not needed in the application.
106 *
107 * This symbol may be defined in \ref conf_sleepmgr.h.
108 */
109 #if defined(__DOXYGEN__) && !defined(CONFIG_SLEEPMGR_ENABLE)
110 # define CONFIG_SLEEPMGR_ENABLE
111 #endif
112
113 /**
114 * \enum sleepmgr_mode
115 * \brief Sleep mode locks
116 *
117 * Identifiers for the different sleep mode locks.
118 */
119
120 /**
121 * \brief Initialize the lock counts
122 *
123 * Sets all lock counts to 0, except the very last one, which is set to 1. This
124 * is done to simplify the algorithm for finding the deepest allowable sleep
125 * mode in \ref sleepmgr_enter_sleep.
126 */
sleepmgr_init(void)127 static inline void sleepmgr_init(void)
128 {
129 #ifdef CONFIG_SLEEPMGR_ENABLE
130 uint8_t i;
131
132 for (i = 0; i < SLEEPMGR_NR_OF_MODES - 1; i++) {
133 sleepmgr_locks[i] = 0;
134 }
135 sleepmgr_locks[SLEEPMGR_NR_OF_MODES - 1] = 1;
136 #endif /* CONFIG_SLEEPMGR_ENABLE */
137 }
138
139 /**
140 * \brief Increase lock count for a sleep mode
141 *
142 * Increases the lock count for \a mode to ensure that the sleep manager does
143 * not put the device to sleep in the deeper sleep modes.
144 *
145 * \param mode Sleep mode to lock.
146 */
sleepmgr_lock_mode(enum sleepmgr_mode mode)147 static inline void sleepmgr_lock_mode(enum sleepmgr_mode mode)
148 {
149 #ifdef CONFIG_SLEEPMGR_ENABLE
150 irqflags_t flags;
151
152 if(sleepmgr_locks[mode] >= 0xff) {
153 while (true) {
154 // Warning: maximum value of sleepmgr_locks buffer is no more than 255.
155 // Check APP or change the data type to uint16_t.
156 }
157 }
158
159 // Enter a critical section
160 flags = cpu_irq_save();
161
162 ++sleepmgr_locks[mode];
163
164 // Leave the critical section
165 cpu_irq_restore(flags);
166 #else
167 UNUSED(mode);
168 #endif /* CONFIG_SLEEPMGR_ENABLE */
169 }
170
171 /**
172 * \brief Decrease lock count for a sleep mode
173 *
174 * Decreases the lock count for \a mode. If the lock count reaches 0, the sleep
175 * manager can put the device to sleep in the deeper sleep modes.
176 *
177 * \param mode Sleep mode to unlock.
178 */
sleepmgr_unlock_mode(enum sleepmgr_mode mode)179 static inline void sleepmgr_unlock_mode(enum sleepmgr_mode mode)
180 {
181 #ifdef CONFIG_SLEEPMGR_ENABLE
182 irqflags_t flags;
183
184 if(sleepmgr_locks[mode] == 0) {
185 while (true) {
186 // Warning: minimum value of sleepmgr_locks buffer is no less than 0.
187 // Check APP.
188 }
189 }
190
191 // Enter a critical section
192 flags = cpu_irq_save();
193
194 --sleepmgr_locks[mode];
195
196 // Leave the critical section
197 cpu_irq_restore(flags);
198 #else
199 UNUSED(mode);
200 #endif /* CONFIG_SLEEPMGR_ENABLE */
201 }
202
203 /**
204 * \brief Retrieves the deepest allowable sleep mode
205 *
206 * Searches through the sleep mode lock counts, starting at the shallowest sleep
207 * mode, until the first non-zero lock count is found. The deepest allowable
208 * sleep mode is then returned.
209 */
sleepmgr_get_sleep_mode(void)210 static inline enum sleepmgr_mode sleepmgr_get_sleep_mode(void)
211 {
212 enum sleepmgr_mode sleep_mode = SLEEPMGR_ACTIVE;
213
214 #ifdef CONFIG_SLEEPMGR_ENABLE
215 uint8_t *lock_ptr = sleepmgr_locks;
216
217 // Find first non-zero lock count, starting with the shallowest modes.
218 while (!(*lock_ptr)) {
219 lock_ptr++;
220 sleep_mode = (enum sleepmgr_mode)(sleep_mode + 1);
221 }
222
223 // Catch the case where one too many sleepmgr_unlock_mode() call has been
224 // performed on the deepest sleep mode.
225 Assert((uintptr_t)(lock_ptr - sleepmgr_locks) < SLEEPMGR_NR_OF_MODES);
226
227 #endif /* CONFIG_SLEEPMGR_ENABLE */
228
229 return sleep_mode;
230 }
231
232 /**
233 * \fn sleepmgr_enter_sleep
234 * \brief Go to sleep in the deepest allowed mode
235 *
236 * Searches through the sleep mode lock counts, starting at the shallowest sleep
237 * mode, until the first non-zero lock count is found. The device is then put to
238 * sleep in the sleep mode that corresponds to the lock.
239 *
240 * \note This function enables interrupts before going to sleep, and will leave
241 * them enabled upon return. This also applies if sleep is skipped due to ACTIVE
242 * mode being locked.
243 */
244
sleepmgr_enter_sleep(void)245 static inline void sleepmgr_enter_sleep(void)
246 {
247 #ifdef CONFIG_SLEEPMGR_ENABLE
248 enum sleepmgr_mode sleep_mode;
249
250 cpu_irq_disable();
251
252 // Find the deepest allowable sleep mode
253 sleep_mode = sleepmgr_get_sleep_mode();
254 // Return right away if first mode (ACTIVE) is locked.
255 if (sleep_mode==SLEEPMGR_ACTIVE) {
256 cpu_irq_enable();
257 return;
258 }
259 // Enter the deepest allowable sleep mode with interrupts enabled
260 sleepmgr_sleep(sleep_mode);
261 #else
262 cpu_irq_enable();
263 #endif /* CONFIG_SLEEPMGR_ENABLE */
264 }
265
266
267 //! @}
268
269 #ifdef __cplusplus
270 }
271 #endif
272
273 #endif /* SLEEPMGR_H */
274