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