8  * this software and associated documentation files (the "Software"), to deal in
9  * the Software without restriction, including without limitation the rights to
11  * the Software, and to permit persons to whom the Software is furnished to do so,
12  * subject to the following conditions:
14  * The above copyright notice and this permission notice shall be included in all
15  * copies or substantial portions of the Software.
17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
19  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
22  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
30 * Implementation of functions defined in portable.h for the ARM CM3 port.
47 /* Constants required to manipulate the core.  Registers first... */
53 /* ...then bits in the registers. */
66 /* Constants used to check the installation of the FreeRTOS interrupt handlers. */
71 /* Constants required to check the validity of an interrupt priority. */
81 /* Masks off all bits but the VECTACTIVE bits in the ICSR register. */
84 /* Constants required to set up the initial stack. */
87 /* The systick is a 24-bit counter. */
90 /* A fiddle factor to estimate the number of SysTick counts that would have
91  * occurred while the SysTick counter is stopped during tickless idle
95 /* For strict compliance with the Cortex-M spec the task start address should
96  * have bit-0 clear, as it is loaded into the PC on exit from an ISR. */
99 /* Let the user override the default SysTick clock rate.  If defined by the
100  * user, this symbol must equal the SysTick clock rate when the CLK bit is 0 in the
104     /* Ensure the SysTick is clocked at the same frequency as the core. */
107     /* Select the option to clock SysTick not at the same frequency as the core. */
112  * Setup the timer to generate the tick interrupts.  The implementation in this
113  * file is weak to allow application writers to change the timer used to
114  * generate the tick interrupt.
140 /* Each task maintains its own interrupt status in the critical nesting
145  * The number of SysTick increments that make up one tick period.
152  * The maximum number of tick periods that can be suppressed is limited by the
153  * 24 bit resolution of the SysTick timer.
160  * Compensate for the CPU cycles that pass while the SysTick is stopped (low
168  * Used by the portASSERT_IF_INTERRUPT_PRIORITY_INVALID() macro to ensure
187     /* Simulate the stack frame as it would be created by a context switch  in pxPortInitialiseStack()
189 …                                 /* Offset added to account for the way the MCU uses the stack on …  in pxPortInitialiseStack()
210      * defined, then stop here so application writers can catch the error. */  in prvTaskExitError()
225     /* An application can install FreeRTOS interrupt handlers in one of the  in xPortStartScheduler()
227      * 1. Direct Routing - Install the functions vPortSVCHandler and  in xPortStartScheduler()
241         /* Validate that the application has correctly installed the FreeRTOS  in xPortStartScheduler()
242          * handlers for SVCall and PendSV interrupts. We do not check the  in xPortStartScheduler()
243          * installation of the SysTick handler because the application may  in xPortStartScheduler()
244          * choose to drive the RTOS tick using a timer other than the SysTick  in xPortStartScheduler()
245          * timer by overriding the weak function vPortSetupTimerInterrupt().  in xPortStartScheduler()
247          * Assertion failures here indicate incorrect installation of the  in xPortStartScheduler()
248          * FreeRTOS handlers. For help installing the FreeRTOS handlers, see  in xPortStartScheduler()
251          * Systems with a configurable address for the interrupt vector table  in xPortStartScheduler()
253          * VTOR is not set correctly to point to the application's vector table. */  in xPortStartScheduler()
266         /* Determine the maximum priority from which ISR safe FreeRTOS API  in xPortStartScheduler()
271          * Save the interrupt priority value that is about to be clobbered. */  in xPortStartScheduler()
274         /* Determine the number of priority bits available.  First write to all  in xPortStartScheduler()
278         /* Read the value back to see how many bits stuck. */  in xPortStartScheduler()
281         /* Use the same mask on the maximum system call priority. */  in xPortStartScheduler()
284         /* Check that the maximum system call priority is nonzero after  in xPortStartScheduler()
285          * accounting for the number of priority bits supported by the  in xPortStartScheduler()
286          * hardware. A priority of 0 is invalid because setting the BASEPRI  in xPortStartScheduler()
292         /* Check that the bits not implemented in hardware are zero in  in xPortStartScheduler()
296         /* Calculate the maximum acceptable priority group value for the number  in xPortStartScheduler()
307             /* When the hardware implements 8 priority bits, there is no way for  in xPortStartScheduler()
308              * the software to configure PRIGROUP to not have sub-priorities. As  in xPortStartScheduler()
309              * a result, the least significant bit is always used for sub-priority  in xPortStartScheduler()
315              * are at the same preemption priority. This may appear confusing as  in xPortStartScheduler()
319              * to 4, this confusion does not happen and the behaviour remains the same.  in xPortStartScheduler()
321              * The following assert ensures that the sub-priority bit in the  in xPortStartScheduler()
322              * configMAX_SYSCALL_INTERRUPT_PRIORITY is clear to avoid the above mentioned  in xPortStartScheduler()
332         /* Shift the priority group value back to its position within the AIRCR  in xPortStartScheduler()
337         /* Restore the clobbered interrupt priority register to its original  in xPortStartScheduler()
343     /* Make PendSV and SysTick the lowest priority interrupts, and make SVCall  in xPortStartScheduler()
344      * the highest priority. */  in xPortStartScheduler()
349     /* Start the timer that generates the tick ISR.  Interrupts are disabled  in xPortStartScheduler()
353     /* Initialise the critical nesting count ready for the first task. */  in xPortStartScheduler()
356     /* Start the first task. */  in xPortStartScheduler()
377     /* This is not the interrupt safe version of the enter critical function so  in vPortEnterCritical()
380      * the critical nesting count is 1 to protect against recursive calls if the  in vPortEnterCritical()
403     /* The SysTick runs at the lowest interrupt priority, so when this interrupt  in xPortSysTickHandler()
405      * save and then restore the interrupt mask value as its value is already  in xPortSysTickHandler()
410         /* Increment the RTOS tick. */  in xPortSysTickHandler()
416              * the PendSV interrupt.  Pend the PendSV interrupt. */  in xPortSysTickHandler()
435         /* Make sure the SysTick reload value does not overflow the counter. */  in vPortSuppressTicksAndSleep()
441         /* Enter a critical section but don't use the taskENTER_CRITICAL()  in vPortSuppressTicksAndSleep()
447         /* If a context switch is pending or a task is waiting for the scheduler  in vPortSuppressTicksAndSleep()
448          * to be unsuspended then abandon the low power entry. */  in vPortSuppressTicksAndSleep()
451             /* Re-enable interrupts - see comments above the __disable_interrupt()  in vPortSuppressTicksAndSleep()
457             /* Stop the SysTick momentarily.  The time the SysTick is stopped for  in vPortSuppressTicksAndSleep()
458              * is accounted for as best it can be, but using the tickless mode will  in vPortSuppressTicksAndSleep()
459              * inevitably result in some tiny drift of the time maintained by the  in vPortSuppressTicksAndSleep()
463             /* Use the SysTick current-value register to determine the number of  in vPortSuppressTicksAndSleep()
464              * SysTick decrements remaining until the next tick interrupt.  If the  in vPortSuppressTicksAndSleep()
466              * ulTimerCountsForOneTick decrements remaining, not zero, because the  in vPortSuppressTicksAndSleep()
467              * SysTick requests the interrupt when decrementing from 1 to 0. */  in vPortSuppressTicksAndSleep()
475             /* Calculate the reload value required to wait xExpectedIdleTime  in vPortSuppressTicksAndSleep()
477              * way through the first tick period.  But if the SysTick IRQ is now  in vPortSuppressTicksAndSleep()
478              * pending, then clear the IRQ, suppressing the first tick, and correct  in vPortSuppressTicksAndSleep()
479              * the reload value to reflect that the second tick period is already  in vPortSuppressTicksAndSleep()
480              * underway.  The expected idle time is always at least two ticks. */  in vPortSuppressTicksAndSleep()
494             /* Set the new reload value. */  in vPortSuppressTicksAndSleep()
497             /* Clear the SysTick count flag and set the count value back to  in vPortSuppressTicksAndSleep()
507              * should not be executed again.  However, the original expected idle  in vPortSuppressTicksAndSleep()
521             /* Re-enable interrupts to allow the interrupt that brought the MCU  in vPortSuppressTicksAndSleep()
523              * the __disable_interrupt() call above. */  in vPortSuppressTicksAndSleep()
528             /* Disable interrupts again because the clock is about to be stopped  in vPortSuppressTicksAndSleep()
529              * and interrupts that execute while the clock is stopped will increase  in vPortSuppressTicksAndSleep()
530              * any slippage between the time maintained by the RTOS and calendar  in vPortSuppressTicksAndSleep()
536             /* Disable the SysTick clock without reading the  in vPortSuppressTicksAndSleep()
537              * portNVIC_SYSTICK_CTRL_REG register to ensure the  in vPortSuppressTicksAndSleep()
539              * the time the SysTick is stopped for is accounted for as best it can  in vPortSuppressTicksAndSleep()
540              * be, but using the tickless mode will inevitably result in some tiny  in vPortSuppressTicksAndSleep()
541              * drift of the time maintained by the kernel with respect to calendar  in vPortSuppressTicksAndSleep()
545             /* Determine whether the SysTick has already counted to zero. */  in vPortSuppressTicksAndSleep()
550                 /* The tick interrupt ended the sleep (or is now pending), and  in vPortSuppressTicksAndSleep()
552                  * with whatever remains of the new tick period. */  in vPortSuppressTicksAndSleep()
556                  * underflowed because the post sleep hook did something  in vPortSuppressTicksAndSleep()
557                  * that took too long or because the SysTick current-value register  in vPortSuppressTicksAndSleep()
566                 /* As the pending tick will be processed as soon as this  in vPortSuppressTicksAndSleep()
567                  * function exits, the tick value maintained by the tick is stepped  in vPortSuppressTicksAndSleep()
568                  * forward by one less than the time spent waiting. */  in vPortSuppressTicksAndSleep()
573                 /* Something other than the tick interrupt ended the sleep. */  in vPortSuppressTicksAndSleep()
575                 /* Use the SysTick current-value register to determine the  in vPortSuppressTicksAndSleep()
576                  * number of SysTick decrements remaining until the expected idle  in vPortSuppressTicksAndSleep()
581                     /* If the SysTick is not using the core clock, the current-  in vPortSuppressTicksAndSleep()
582                      * value register might still be zero here.  In that case, the  in vPortSuppressTicksAndSleep()
583                      * SysTick didn't load from the reload register, and there are  in vPortSuppressTicksAndSleep()
584                      * ulReloadValue decrements remaining in the expected idle  in vPortSuppressTicksAndSleep()
593                 /* Work out how long the sleep lasted rounded to complete tick  in vPortSuppressTicksAndSleep()
594                  * periods (not the ulReload value which accounted for part  in vPortSuppressTicksAndSleep()
598                 /* How many complete tick periods passed while the processor  in vPortSuppressTicksAndSleep()
602                 /* The reload value is set to whatever fraction of a single tick  in vPortSuppressTicksAndSleep()
609              * the SysTick is not using the core clock, temporarily configure it to  in vPortSuppressTicksAndSleep()
610              * use the core clock.  This configuration forces the SysTick to load  in vPortSuppressTicksAndSleep()
611              * from portNVIC_SYSTICK_LOAD_REG immediately instead of at the next  in vPortSuppressTicksAndSleep()
612              * cycle of the other clock.  Then portNVIC_SYSTICK_LOAD_REG is ready  in vPortSuppressTicksAndSleep()
613              * to receive the standard value immediately. */  in vPortSuppressTicksAndSleep()
622                 /* The temporary usage of the core clock has served its purpose,  in vPortSuppressTicksAndSleep()
623                  * as described above.  Resume usage of the other clock. */  in vPortSuppressTicksAndSleep()
628                     /* The partial tick period already ended.  Be sure the SysTick  in vPortSuppressTicksAndSleep()
638             /* Step the tick to account for any tick periods that elapsed. */  in vPortSuppressTicksAndSleep()
650  * Setup the systick timer to generate the tick interrupts at the required
655     /* Calculate the constants required to configure the tick interrupt. */  in vPortSetupTimerInterrupt()
664     /* Stop and clear the SysTick. */  in vPortSetupTimerInterrupt()
668     /* Configure SysTick to interrupt at the requested rate. */  in vPortSetupTimerInterrupt()
681         /* Obtain the number of the currently executing interrupt. */  in vPortValidateInterruptPriority()
684         /* Is the interrupt number a user defined interrupt? */  in vPortValidateInterruptPriority()
687             /* Look up the interrupt's priority. */  in vPortValidateInterruptPriority()
690             /* The following assertion will fail if a service routine (ISR) for  in vPortValidateInterruptPriority()
698              * interrupt priorities, therefore the priority of the interrupt must  in vPortValidateInterruptPriority()
702              * Interrupts that  use the FreeRTOS API must not be left at their  in vPortValidateInterruptPriority()
703              * default priority of  zero as that is the highest possible priority,  in vPortValidateInterruptPriority()
710              * The following links provide detailed information:  in vPortValidateInterruptPriority()
716         /* Priority grouping:  The interrupt controller (NVIC) allows the bits  in vPortValidateInterruptPriority()
718          * define the interrupt's pre-emption priority bits and bits that define  in vPortValidateInterruptPriority()
719          * the interrupt's sub-priority.  For simplicity all bits must be defined  in vPortValidateInterruptPriority()
720          * to be pre-emption priority bits.  The following assertion will fail if  in vPortValidateInterruptPriority()
721          * this is not the case (if some bits represent a sub-priority).  in vPortValidateInterruptPriority()
723          * If the application only uses CMSIS libraries for interrupt  in vPortValidateInterruptPriority()
724          * configuration then the correct setting can be achieved on all Cortex-M  in vPortValidateInterruptPriority()
725          * devices by calling NVIC_SetPriorityGrouping( 0 ); before starting the  in vPortValidateInterruptPriority()