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.
41 /* Constants required to manipulate the core.  Registers first... */
46 /* ...then bits in the registers. */
59 /* Constants required to check the validity of an interrupt priority. */
69 /* Masks off all bits but the VECTACTIVE bits in the ICSR register. */
72 /* Constants required to set up the initial stack. */
75 /* The systick is a 24-bit counter. */
78 /* A fiddle factor to estimate the number of SysTick counts that would have
79  * occurred while the SysTick counter is stopped during tickless idle
83 /* For strict compliance with the Cortex-M spec the task start address should
84  * have bit-0 clear, as it is loaded into the PC on exit from an ISR. */
87 /* Let the user override the default SysTick clock rate.  If defined by the
88  * user, this symbol must equal the SysTick clock rate when the CLK bit is 0 in the
92     /* Ensure the SysTick is clocked at the same frequency as the core. */
95     /* Select the option to clock SysTick not at the same frequency as the core. */
100  * Setup the timer to generate the tick interrupts.  The implementation in this
101  * file is weak to allow application writers to change the timer used to
102  * generate the tick interrupt.
123 /* Required to allow portasm.asm access the configMAX_SYSCALL_INTERRUPT_PRIORITY
127 /* Each task maintains its own interrupt status in the critical nesting
132  * The number of SysTick increments that make up one tick period.
139  * The maximum number of tick periods that can be suppressed is limited by the
140  * 24 bit resolution of the SysTick timer.
147  * Compensate for the CPU cycles that pass while the SysTick is stopped (low
155  * Used by the portASSERT_IF_INTERRUPT_PRIORITY_INVALID() macro to ensure
174     /* Simulate the stack frame as it would be created by a context switch  in pxPortInitialiseStack()
177     /* Offset added to account for the way the MCU uses the stack on entry/exit  in pxPortInitialiseStack()
204      * defined, then stop here so application writers can catch the error. */  in prvTaskExitError()
226         /* Determine the maximum priority from which ISR safe FreeRTOS API  in xPortStartScheduler()
231          * Save the interrupt priority value that is about to be clobbered. */  in xPortStartScheduler()
234         /* Determine the number of priority bits available.  First write to all  in xPortStartScheduler()
238         /* Read the value back to see how many bits stuck. */  in xPortStartScheduler()
241         /* Use the same mask on the maximum system call priority. */  in xPortStartScheduler()
244         /* Check that the maximum system call priority is nonzero after  in xPortStartScheduler()
245          * accounting for the number of priority bits supported by the  in xPortStartScheduler()
246          * hardware. A priority of 0 is invalid because setting the BASEPRI  in xPortStartScheduler()
252         /* Check that the bits not implemented in hardware are zero in  in xPortStartScheduler()
256         /* Calculate the maximum acceptable priority group value for the number  in xPortStartScheduler()
267             /* When the hardware implements 8 priority bits, there is no way for  in xPortStartScheduler()
268             * the software to configure PRIGROUP to not have sub-priorities. As  in xPortStartScheduler()
269             * a result, the least significant bit is always used for sub-priority  in xPortStartScheduler()
275             * are at the same preemption priority. This may appear confusing as  in xPortStartScheduler()
279             * to 4, this confusion does not happen and the behaviour remains the same.  in xPortStartScheduler()
281             * The following assert ensures that the sub-priority bit in the  in xPortStartScheduler()
282             * configMAX_SYSCALL_INTERRUPT_PRIORITY is clear to avoid the above mentioned  in xPortStartScheduler()
292         /* Shift the priority group value back to its position within the AIRCR  in xPortStartScheduler()
297         /* Restore the clobbered interrupt priority register to its original  in xPortStartScheduler()
303     /* Make PendSV and SysTick the lowest priority interrupts. */  in xPortStartScheduler()
307     /* Start the timer that generates the tick ISR.  Interrupts are disabled  in xPortStartScheduler()
311     /* Initialise the critical nesting count ready for the first task. */  in xPortStartScheduler()
314     /* Start the first task. */  in xPortStartScheduler()
335     /* This is not the interrupt safe version of the enter critical function so  in vPortEnterCritical()
338      * the critical nesting count is 1 to protect against recursive calls if the  in vPortEnterCritical()
361     /* The SysTick runs at the lowest interrupt priority, so when this interrupt  in xPortSysTickHandler()
363      * save and then restore the interrupt mask value as its value is already  in xPortSysTickHandler()
368         /* Increment the RTOS tick. */  in xPortSysTickHandler()
374              * the PendSV interrupt.  Pend the PendSV interrupt. */  in xPortSysTickHandler()
394         /* Make sure the SysTick reload value does not overflow the counter. */  in vPortSuppressTicksAndSleep()
400         /* Enter a critical section but don't use the taskENTER_CRITICAL()  in vPortSuppressTicksAndSleep()
406         /* If a context switch is pending or a task is waiting for the scheduler  in vPortSuppressTicksAndSleep()
407          * to be unsuspended then abandon the low power entry. */  in vPortSuppressTicksAndSleep()
410             /* Re-enable interrupts - see comments above the cpsid instruction  in vPortSuppressTicksAndSleep()
416             /* Stop the SysTick momentarily.  The time the SysTick is stopped for  in vPortSuppressTicksAndSleep()
417              * is accounted for as best it can be, but using the tickless mode will  in vPortSuppressTicksAndSleep()
418              * inevitably result in some tiny drift of the time maintained by the  in vPortSuppressTicksAndSleep()
422             /* Use the SysTick current-value register to determine the number of  in vPortSuppressTicksAndSleep()
423              * SysTick decrements remaining until the next tick interrupt.  If the  in vPortSuppressTicksAndSleep()
425              * ulTimerCountsForOneTick decrements remaining, not zero, because the  in vPortSuppressTicksAndSleep()
426              * SysTick requests the interrupt when decrementing from 1 to 0. */  in vPortSuppressTicksAndSleep()
434             /* Calculate the reload value required to wait xExpectedIdleTime  in vPortSuppressTicksAndSleep()
436              * way through the first tick period.  But if the SysTick IRQ is now  in vPortSuppressTicksAndSleep()
437              * pending, then clear the IRQ, suppressing the first tick, and correct  in vPortSuppressTicksAndSleep()
438              * the reload value to reflect that the second tick period is already  in vPortSuppressTicksAndSleep()
439              * underway.  The expected idle time is always at least two ticks. */  in vPortSuppressTicksAndSleep()
453             /* Set the new reload value. */  in vPortSuppressTicksAndSleep()
456             /* Clear the SysTick count flag and set the count value back to  in vPortSuppressTicksAndSleep()
466              * should not be executed again.  However, the original expected idle  in vPortSuppressTicksAndSleep()
480             /* Re-enable interrupts to allow the interrupt that brought the MCU  in vPortSuppressTicksAndSleep()
482              * the cpsid instruction above. */  in vPortSuppressTicksAndSleep()
487             /* Disable interrupts again because the clock is about to be stopped  in vPortSuppressTicksAndSleep()
488              * and interrupts that execute while the clock is stopped will increase  in vPortSuppressTicksAndSleep()
489              * any slippage between the time maintained by the RTOS and calendar  in vPortSuppressTicksAndSleep()
495             /* Disable the SysTick clock without reading the  in vPortSuppressTicksAndSleep()
496              * portNVIC_SYSTICK_CTRL_REG register to ensure the  in vPortSuppressTicksAndSleep()
498              * the time the SysTick is stopped for is accounted for as best it can  in vPortSuppressTicksAndSleep()
499              * be, but using the tickless mode will inevitably result in some tiny  in vPortSuppressTicksAndSleep()
500              * drift of the time maintained by the kernel with respect to calendar  in vPortSuppressTicksAndSleep()
504             /* Determine whether the SysTick has already counted to zero. */  in vPortSuppressTicksAndSleep()
509                 /* The tick interrupt ended the sleep (or is now pending), and  in vPortSuppressTicksAndSleep()
511                  * with whatever remains of the new tick period. */  in vPortSuppressTicksAndSleep()
515                  * underflowed because the post sleep hook did something  in vPortSuppressTicksAndSleep()
516                  * that took too long or because the SysTick current-value register  in vPortSuppressTicksAndSleep()
525                 /* As the pending tick will be processed as soon as this  in vPortSuppressTicksAndSleep()
526                  * function exits, the tick value maintained by the tick is stepped  in vPortSuppressTicksAndSleep()
527                  * forward by one less than the time spent waiting. */  in vPortSuppressTicksAndSleep()
532                 /* Something other than the tick interrupt ended the sleep. */  in vPortSuppressTicksAndSleep()
534                 /* Use the SysTick current-value register to determine the  in vPortSuppressTicksAndSleep()
535                  * number of SysTick decrements remaining until the expected idle  in vPortSuppressTicksAndSleep()
540                     /* If the SysTick is not using the core clock, the current-  in vPortSuppressTicksAndSleep()
541                      * value register might still be zero here.  In that case, the  in vPortSuppressTicksAndSleep()
542                      * SysTick didn't load from the reload register, and there are  in vPortSuppressTicksAndSleep()
543                      * ulReloadValue decrements remaining in the expected idle  in vPortSuppressTicksAndSleep()
552                 /* Work out how long the sleep lasted rounded to complete tick  in vPortSuppressTicksAndSleep()
553                  * periods (not the ulReload value which accounted for part  in vPortSuppressTicksAndSleep()
557                 /* How many complete tick periods passed while the processor  in vPortSuppressTicksAndSleep()
561                 /* The reload value is set to whatever fraction of a single tick  in vPortSuppressTicksAndSleep()
568              * the SysTick is not using the core clock, temporarily configure it to  in vPortSuppressTicksAndSleep()
569              * use the core clock.  This configuration forces the SysTick to load  in vPortSuppressTicksAndSleep()
570              * from portNVIC_SYSTICK_LOAD_REG immediately instead of at the next  in vPortSuppressTicksAndSleep()
571              * cycle of the other clock.  Then portNVIC_SYSTICK_LOAD_REG is ready  in vPortSuppressTicksAndSleep()
572              * to receive the standard value immediately. */  in vPortSuppressTicksAndSleep()
581                 /* The temporary usage of the core clock has served its purpose,  in vPortSuppressTicksAndSleep()
582                  * as described above.  Resume usage of the other clock. */  in vPortSuppressTicksAndSleep()
587                     /* The partial tick period already ended.  Be sure the SysTick  in vPortSuppressTicksAndSleep()
597             /* Step the tick to account for any tick periods that elapsed. */  in vPortSuppressTicksAndSleep()
609  * Setup the systick timer to generate the tick interrupts at the required
615     /* Calculate the constants required to configure the tick interrupt. */  in vPortSetupTimerInterrupt()
624     /* Stop and clear the SysTick. */  in vPortSetupTimerInterrupt()
628     /* Configure SysTick to interrupt at the requested rate. */  in vPortSetupTimerInterrupt()
644         /* Is the interrupt number a user defined interrupt? */  in vPortValidateInterruptPriority()
647             /* Look up the interrupt's priority. */  in vPortValidateInterruptPriority()
650             /* The following assertion will fail if a service routine (ISR) for  in vPortValidateInterruptPriority()
658              * interrupt priorities, therefore the priority of the interrupt must  in vPortValidateInterruptPriority()
662              * Interrupts that  use the FreeRTOS API must not be left at their  in vPortValidateInterruptPriority()
663              * default priority of  zero as that is the highest possible priority,  in vPortValidateInterruptPriority()
670              * The following links provide detailed information:  in vPortValidateInterruptPriority()
676         /* Priority grouping:  The interrupt controller (NVIC) allows the bits  in vPortValidateInterruptPriority()
678          * define the interrupt's pre-emption priority bits and bits that define  in vPortValidateInterruptPriority()
679          * the interrupt's sub-priority.  For simplicity all bits must be defined  in vPortValidateInterruptPriority()
680          * to be pre-emption priority bits.  The following assertion will fail if  in vPortValidateInterruptPriority()
681          * this is not the case (if some bits represent a sub-priority).  in vPortValidateInterruptPriority()
683          * If the application only uses CMSIS libraries for interrupt  in vPortValidateInterruptPriority()
684          * configuration then the correct setting can be achieved on all Cortex-M  in vPortValidateInterruptPriority()
685          * devices by calling NVIC_SetPriorityGrouping( 0 ); before starting the  in vPortValidateInterruptPriority()