1 /**************************************************************************/
2 /* */
3 /* Copyright (c) Microsoft Corporation. All rights reserved. */
4 /* */
5 /* This software is licensed under the Microsoft Software License */
6 /* Terms for Microsoft Azure RTOS. Full text of the license can be */
7 /* found in the LICENSE file at https://aka.ms/AzureRTOS_EULA */
8 /* and in the root directory of this software. */
9 /* */
10 /**************************************************************************/
11
12
13 /**************************************************************************/
14 /**************************************************************************/
15 /** */
16 /** ThreadX Component */
17 /** */
18 /** Low Power Timer Management */
19 /** */
20 /**************************************************************************/
21 /**************************************************************************/
22
23 #define TX_SOURCE_CODE
24
25
26 /* Include necessary system files. */
27
28 #include "tx_api.h"
29 #include "tx_timer.h"
30 #include "tx_low_power.h"
31
32
33 /* Define low power global variables. */
34
35 /* Flag to determine if we've entered low power mode or not. */
36 UINT tx_low_power_entered;
37
38
39 /**************************************************************************/
40 /* */
41 /* FUNCTION RELEASE */
42 /* */
43 /* tx_low_power_enter PORTABLE C */
44 /* 6.1.6 */
45 /* AUTHOR */
46 /* */
47 /* William E. Lamie, Microsoft Corporation */
48 /* */
49 /* DESCRIPTION */
50 /* */
51 /* This function is the low power entry function. This function is */
52 /* assumed to be called from the idle loop of tx_thread_schedule. It */
53 /* is important to note that if an interrupt managed by ThreadX occurs */
54 /* anywhere where interrupts are enabled in this function, the entire */
55 /* processing of this function is discarded and the function won't be */
56 /* re-entered until the idle loop in tx_thread_schedule is executed */
57 /* again. */
58 /* */
59 /* INPUT */
60 /* */
61 /* None */
62 /* */
63 /* OUTPUT */
64 /* */
65 /* None */
66 /* */
67 /* CALLS */
68 /* */
69 /* tx_timer_get_next Get next timer expiration */
70 /* */
71 /* CALLED BY */
72 /* */
73 /* _tx_thread_schedule Thread scheduling loop */
74 /* */
75 /* RELEASE HISTORY */
76 /* */
77 /* DATE NAME DESCRIPTION */
78 /* */
79 /* 03-02-2021 William E. Lamie Initial Version 6.1.5 */
80 /* 04-02-2021 Scott Larson Modified comments and fixed */
81 /* compiler warning, */
82 /* resulting in version 6.1.6 */
83 /* */
84 /**************************************************************************/
tx_low_power_enter(VOID)85 VOID tx_low_power_enter(VOID)
86 {
87
88 TX_INTERRUPT_SAVE_AREA
89
90 #ifdef TX_LOW_POWER_TIMER_SETUP
91 ULONG tx_low_power_next_expiration; /* The next timer experation (units of ThreadX timer ticks). */
92 ULONG timers_active;
93 #endif
94
95 /* Disable interrupts while we prepare for low power mode. */
96 TX_DISABLE
97
98 /* TX_LOW_POWER_TIMER_SETUP is a macro to a routine that sets up a low power
99 clock. If such routine does not exist, we can skip the logic that computes
100 the next expiration time. */
101 #ifdef TX_LOW_POWER_TIMER_SETUP
102
103 /* At this point, we want to enter low power mode, since nothing
104 meaningful is going on in the system. However, in order to keep
105 the ThreadX timer services accurate, we must first determine the
106 next ThreadX timer expiration in terms of ticks. This is
107 accomplished via the tx_timer_get_next API. */
108 timers_active = tx_timer_get_next(&tx_low_power_next_expiration);
109
110 /* There are two possibilities:
111 1: A ThreadX timer is active. tx_timer_get_next returns TX_TRUE.
112 Program the hardware timer source such that the next timer
113 interrupt is equal to: tx_low_power_next_expiration*tick_frequency.
114 In most applications, the tick_frequency is 10ms, but this is
115 completely application specific in ThreadX, typically set up
116 in tx_low_level_initialize. Note that in this situation, a low
117 power clock must be used in order to wake up the CPU for the next timeout
118 event. Therefore an alternative clock must be programmed.
119 2: There are no ThreadX timers active. tx_timer_get_next returns TX_FALSE.
120 2.a: application may choose not to keep the ThreadX internal
121 tick count updated (define TX_LOW_POWER_TICKLESS), therefore no need
122 to set up a low power clock.
123 2.b: Application still needs to keep ThreadX tick up-to-date. In this case
124 a low power clock needs to be set up.
125 */
126
127 #ifndef TX_LOW_POWER_TICKLESS
128 /* We still want to keep track of time in low power mode. */
129 if (timers_active == TX_FALSE)
130 {
131 /* Set the next expiration to 0xFFFFFFF, an indication that the timer sleeps for
132 maximum amount of time the HW supports.*/
133 tx_low_power_next_expiration = 0xFFFFFFFF;
134 timers_active = TX_TRUE;
135 }
136 #endif /* TX_LOW_POWER_TICKLESS */
137
138 if (timers_active == TX_TRUE)
139 {
140 /* A ThreadX timer is active or we simply want to keep track of time. */
141 TX_LOW_POWER_TIMER_SETUP(tx_low_power_next_expiration);
142 }
143 #endif /* TX_LOW_POWER_TIMER_SETUP */
144
145
146 /* Set the flag indicating that low power has been entered. This
147 flag is checked in tx_low_power_exit to determine if the logic
148 used to adjust the ThreadX time is required. */
149 tx_low_power_entered = TX_TRUE;
150
151 /* Re-enable interrupts before low power mode is entered. */
152 TX_RESTORE
153
154 /* User code to enter low power mode. This allows the application to power down
155 peripherals and put the processor in sleep mode.
156 */
157 #ifdef TX_LOW_POWER_USER_ENTER
158 TX_LOW_POWER_USER_ENTER;
159 #endif
160
161 /* If the low power code returns, this routine returns to the tx_thread_schedule loop. */
162 }
163
164
165 /**************************************************************************/
166 /* */
167 /* FUNCTION RELEASE */
168 /* */
169 /* tx_low_power_exit PORTABLE C */
170 /* 6.1.5 */
171 /* AUTHOR */
172 /* */
173 /* William E. Lamie, Microsoft Corporation */
174 /* */
175 /* DESCRIPTION */
176 /* */
177 /* This function is the low power exit function. This function must */
178 /* be called from any interrupt that can wakeup the processor from */
179 /* low power mode. If nothing needs to be done, this function simply */
180 /* returns. */
181 /* */
182 /* INPUT */
183 /* */
184 /* None */
185 /* */
186 /* OUTPUT */
187 /* */
188 /* None */
189 /* */
190 /* CALLS */
191 /* */
192 /* tx_time_increment Update the ThreadX timer */
193 /* */
194 /* CALLED BY */
195 /* */
196 /* ISRs Front-end of Interrupt */
197 /* Service Routines */
198 /* */
199 /* RELEASE HISTORY */
200 /* */
201 /* DATE NAME DESCRIPTION */
202 /* */
203 /* 03-02-2021 William E. Lamie Initial Version 6.1.5 */
204 /* */
205 /**************************************************************************/
tx_low_power_exit(VOID)206 VOID tx_low_power_exit(VOID)
207 {
208
209 /* How many ticks to adjust ThreadX timers after exiting low power mode. */
210 ULONG tx_low_power_adjust_ticks;
211
212
213 /* Determine if the interrupt occurred in low power mode. */
214 if (tx_low_power_entered)
215 {
216 /* Yes, low power mode was interrupted. */
217
218 /* Clear the low power entered flag. */
219 tx_low_power_entered = TX_FALSE;
220
221 /* User code to exit low power mode and reprogram the
222 timer to the desired interrupt frequency. */
223 #ifdef TX_LOW_POWER_USER_EXIT
224 TX_LOW_POWER_USER_EXIT;
225 #endif
226
227 #ifdef TX_LOW_POWER_USER_TIMER_ADJUST
228 /* Call the user's low-power timer code to obtain the amount of time (in ticks)
229 the system has been in low power mode. */
230 tx_low_power_adjust_ticks = TX_LOW_POWER_USER_TIMER_ADJUST;
231 #else
232 tx_low_power_adjust_ticks = (ULONG) 0;
233 #endif
234
235 /* Determine if the ThreadX timer(s) needs incrementing. */
236 if (tx_low_power_adjust_ticks)
237 {
238 /* Yes, the ThreadX timer(s) must be incremented. */
239 tx_time_increment(tx_low_power_adjust_ticks);
240 }
241 }
242 }
243
244
245 /**************************************************************************/
246 /* */
247 /* FUNCTION RELEASE */
248 /* */
249 /* tx_timer_get_next PORTABLE C */
250 /* 6.1.5 */
251 /* AUTHOR */
252 /* */
253 /* William E. Lamie, Microsoft Corporation */
254 /* */
255 /* DESCRIPTION */
256 /* */
257 /* This function calculates the next expiration time minus 1 tick for */
258 /* the currently active ThreadX timers. If no timer is active, this */
259 /* routine will return a value of TX_FALSE and the next ticks value */
260 /* will be set to zero. */
261 /* */
262 /* INPUT */
263 /* */
264 /* next_timer_tick_ptr Pointer to destination for next */
265 /* timer expiration value */
266 /* */
267 /* OUTPUT */
268 /* */
269 /* TX_TRUE (1) At least one timer is active */
270 /* TX_FALSE (0) No timers are currently active */
271 /* */
272 /* CALLS */
273 /* */
274 /* None */
275 /* */
276 /* CALLED BY */
277 /* */
278 /* tx_low_power_enter */
279 /* */
280 /* RELEASE HISTORY */
281 /* */
282 /* DATE NAME DESCRIPTION */
283 /* */
284 /* 03-02-2021 William E. Lamie Initial Version 6.1.5 */
285 /* */
286 /**************************************************************************/
tx_timer_get_next(ULONG * next_timer_tick_ptr)287 ULONG tx_timer_get_next(ULONG *next_timer_tick_ptr)
288 {
289
290 TX_INTERRUPT_SAVE_AREA
291
292 TX_TIMER_INTERNAL **timer_list_head;
293 TX_TIMER_INTERNAL *next_timer;
294 UINT i;
295 ULONG calculated_time;
296 ULONG expiration_time = (ULONG) 0xFFFFFFFF;
297
298
299 /* Disable interrupts. */
300 TX_DISABLE
301
302 /* Look at the next timer entry. */
303 timer_list_head = _tx_timer_current_ptr;
304
305 /* Loop through the timer list, looking for the first non-NULL
306 value to signal an active timer. */
307 for (i = (UINT)0; i < TX_TIMER_ENTRIES; i++)
308 {
309 /* Now determine if there is an active timer in this slot. */
310 if (*timer_list_head)
311 {
312 /* Setup the pointer to the expiration list. */
313 next_timer = *timer_list_head;
314
315 /* Loop through the timers active for this relative time slot (determined by i). */
316 do
317 {
318 /* Determine if the remaining time is larger than the list. */
319 if (next_timer -> tx_timer_internal_remaining_ticks > TX_TIMER_ENTRIES)
320 {
321 /* Calculate the expiration time. */
322 calculated_time = next_timer -> tx_timer_internal_remaining_ticks - (TX_TIMER_ENTRIES - i);
323 }
324 else
325 {
326 /* Calculate the expiration time, which is simply the number of entries in this case. */
327 calculated_time = i;
328 }
329
330 /* Determine if a new minimum expiration time is present. */
331 if (expiration_time > calculated_time)
332 {
333 /* Yes, a new minimum expiration time is present - remember it! */
334 expiration_time = calculated_time;
335 }
336
337 /* Move to the next entry in the timer list. */
338 next_timer = next_timer -> tx_timer_internal_active_next;
339
340 } while (next_timer != *timer_list_head);
341 }
342
343 /* This timer entry is NULL, so just move to the next one. */
344 timer_list_head++;
345
346 /* Check for timer list wrap condition. */
347 if (timer_list_head >= _tx_timer_list_end)
348 {
349 /* Wrap to the beginning of the list. */
350 timer_list_head = _tx_timer_list_start;
351 }
352 }
353
354 /* Restore interrupts. */
355 TX_RESTORE
356
357 /* Determine if an active timer was found. */
358 if (expiration_time != (ULONG) 0xFFFFFFFF)
359 {
360 /* Yes, an active timer was found. */
361 *next_timer_tick_ptr = expiration_time;
362 return(TX_TRUE);
363 }
364 else
365 {
366 /* No active timer was found. */
367 *next_timer_tick_ptr = 0;
368 return(TX_FALSE);
369 }
370 }
371
372
373 /**************************************************************************/
374 /* */
375 /* FUNCTION RELEASE */
376 /* */
377 /* tx_time_increment PORTABLE C */
378 /* 6.1.5 */
379 /* AUTHOR */
380 /* */
381 /* William E. Lamie, Microsoft Corporation */
382 /* */
383 /* DESCRIPTION */
384 /* */
385 /* This function increments the current time by a specified value. */
386 /* The value was derived by the application by calling the */
387 /* tx_timer_get_next function prior to this call, which was right */
388 /* before the processor was put in sleep mode. */
389 /* */
390 /* INPUT */
391 /* */
392 /* time_increment The amount of time to catch up on */
393 /* */
394 /* OUTPUT */
395 /* */
396 /* None */
397 /* */
398 /* CALLS */
399 /* */
400 /* _tx_timer_system_activate Timer activate service */
401 /* */
402 /* CALLED BY */
403 /* */
404 /* tx_low_power_exit */
405 /* */
406 /* RELEASE HISTORY */
407 /* */
408 /* DATE NAME DESCRIPTION */
409 /* */
410 /* 03-02-2021 William E. Lamie Initial Version 6.1.5 */
411 /* */
412 /**************************************************************************/
tx_time_increment(ULONG time_increment)413 VOID tx_time_increment(ULONG time_increment)
414 {
415
416 TX_INTERRUPT_SAVE_AREA
417 UINT i;
418 TX_TIMER_INTERNAL **timer_list_head;
419 TX_TIMER_INTERNAL *next_timer;
420 TX_TIMER_INTERNAL *temp_list_head;
421
422
423 /* Determine if there is any time increment. */
424 if (time_increment == 0)
425 {
426 /* Nothing to do, just return. */
427 return;
428 }
429
430 /* Disable interrupts. */
431 TX_DISABLE
432
433 /* Adjust the system clock. */
434 _tx_timer_system_clock = _tx_timer_system_clock + time_increment;
435
436 /* Adjust the time slice variable. */
437 if (_tx_timer_time_slice)
438 {
439 /* Decrement the time-slice variable. */
440 if (_tx_timer_time_slice > time_increment)
441 {
442 _tx_timer_time_slice = _tx_timer_time_slice - time_increment;
443 }
444 else
445 {
446 _tx_timer_time_slice = 1;
447 }
448 }
449
450 /* Calculate the proper place to position the timer. */
451 timer_list_head = _tx_timer_current_ptr;
452
453 /* Setup the temporary list pointer. */
454 temp_list_head = TX_NULL;
455
456 /* Loop to pull all timers off the timer structure and put on the temporary list head. */
457 for (i = 0; i < TX_TIMER_ENTRIES; i++)
458 {
459 /* Determine if there is a timer list in this entry. */
460 if (*timer_list_head)
461 {
462 /* Walk the list and update all the relative times to actual times. */
463
464 /* Setup the pointer to the expiration list. */
465 next_timer = *timer_list_head;
466
467 /* Loop through the timers active for this relative time slot (determined by i). */
468 do
469 {
470 /* Determine if the remaining time is larger than the list. */
471 if (next_timer -> tx_timer_internal_remaining_ticks > TX_TIMER_ENTRIES)
472 {
473 /* Calculate the actual expiration time. */
474 next_timer -> tx_timer_internal_remaining_ticks =
475 next_timer -> tx_timer_internal_remaining_ticks - (TX_TIMER_ENTRIES - i) + 1;
476 }
477 else
478 {
479 /* Calculate the expiration time, which is simply the number of entries in this case. */
480 next_timer -> tx_timer_internal_remaining_ticks = i + 1;
481 }
482
483 /* Move to the next entry in the timer list. */
484 next_timer = next_timer -> tx_timer_internal_active_next;
485
486 } while (next_timer != *timer_list_head);
487
488 /* NULL terminate the current timer list. */
489 ((*timer_list_head) -> tx_timer_internal_active_previous) -> tx_timer_internal_active_next = TX_NULL;
490
491 /* Yes, determine if the temporary list is NULL. */
492 if (temp_list_head == TX_NULL)
493 {
494 /* First item on the list. Move the entire linked list. */
495 temp_list_head = *timer_list_head;
496 }
497 else
498 {
499 /* No, the temp list already has timers on it. Link the next timer list to the end. */
500 (temp_list_head -> tx_timer_internal_active_previous) -> tx_timer_internal_active_next = *timer_list_head;
501
502 /* Now update the previous to the new list's previous timer pointer. */
503 temp_list_head -> tx_timer_internal_active_previous = (*timer_list_head) -> tx_timer_internal_active_previous;
504 }
505
506 /* Now clear the current timer head pointer. */
507 *timer_list_head = TX_NULL;
508 }
509
510 /* Move to next timer entry. */
511 timer_list_head++;
512
513 /* Determine if a wrap around condition has occurred. */
514 if (timer_list_head >= _tx_timer_list_end)
515 {
516 /* Wrap from the beginning of the list. */
517 timer_list_head = _tx_timer_list_start;
518 }
519 }
520
521 /* Set the current timer pointer to the beginning of the list. */
522 _tx_timer_current_ptr = _tx_timer_list_start;
523
524 /* Loop to update and reinsert all the timers in the list. */
525 while (temp_list_head)
526 {
527 /* Pickup the next timer to update and reinsert. */
528 next_timer = temp_list_head;
529
530 /* Move the temp list head pointer to the next pointer. */
531 temp_list_head = next_timer -> tx_timer_internal_active_next;
532
533 /* Determine if the remaining time is greater than the time increment
534 value - this is the normal case. */
535 if (next_timer -> tx_timer_internal_remaining_ticks > time_increment)
536 {
537 /* Decrement the elapsed time. */
538 next_timer -> tx_timer_internal_remaining_ticks = next_timer -> tx_timer_internal_remaining_ticks - time_increment;
539 }
540 else
541 {
542 /* Simply set the expiration value to expire on the next tick. */
543 next_timer -> tx_timer_internal_remaining_ticks = 1;
544 }
545
546 /* Now clear the timer list head pointer for the timer activate function to work properly. */
547 next_timer -> tx_timer_internal_list_head = TX_NULL;
548
549 /* Now re-insert the timer into the list. */
550 _tx_timer_system_activate(next_timer);
551 }
552
553 /* Restore interrupts. */
554 TX_RESTORE
555 }
556
