update to 10.5.0-1

feilipu · feilipu · commit 9c78dea4bbeb · 2023-05-02T13:46:25.000+10:00
diff --git a/doc/tick_sources.md b/doc/tick_sources.md
@@ -28,21 +28,22 @@ The frequency of the Watchdog Oscillator is voltage and temperature dependent as
 Timing consistency may vary as much as 20% between two devices in same setup due to individual device differences, or between a prototype and production device due to setup differences.
 
 ## Alternative tick sources
-For applications requiring high precision timing, the Ticks can be sourced from a hardware timer or external clock.
+For applications requiring high precision timing, the Ticks can be sourced from one of the hardware timers or an external clock input.
 
-First, you switch it in `FreeRTOSVariant.h` header by removing or undefining `portUSE_WDTO` and defining `portUSE_TIMER0`.
+First, you switch it in `FreeRTOSVariant.h` header by removing or undefining `portUSE_WDTO` and defining, here for example, the 8-bit Timer0 `portUSE_TIMER0`.
 
 ```cpp
 #undef portUSE_WDTO
 #define portUSE_TIMER0
-#define portTICK_PERIOD_MS 16
 ```
 
-Next, in your app you provide two pieces of code: the initialisation function and the ISR hook. Their implementation depends of what is your tick source.
+Next, in your app you provide two pieces of code: the initialisation functions and the ISR hook. Their implementation depends on your tick source.
+
+## Timer specific initialisation and ISR functions
 
+For implementation examples for many different timers, including the RTC Timer2 available on some devices, please refer to `port.c` in the [AVRfreeRTOS Repository](https://github.com/feilipu/avrfreertos/tree/master/freeRTOS10xx/portable).
 
-## Hardware timer Timer0
-### Timer initialisation function
+### Hardware timer Timer0
 _NOTE: This code snippet is verified to work on Atmega2560. Full code available [here](./tick_sources_timer0.cpp)._
 
 ```cpp
@@ -89,44 +90,101 @@ void prvSetupTimerInterrupt( void )
 }
 ```
 
+To switch to an alternative tick source, here for example Timer0, insert this block in `FreeRTOSVariant.h`:
+
+```cpp
+#undef portUSE_WDTO
+#define portUSE_TIMER0
+#define portTICK_PERIOD_MS 16
+
+/*
+ * When a tick source other than WDT is used, configuring the tick source becomes the user's responsibility.
+ * E.g., when using Timer0 for the tick source, you can use the following snippet:
+ */
+
+// Formula for the frequency is:
+//      f = F_CPU / (PRESCALER * (1 + COUNTER_TOP)
+//
+// Assuming the MCU clock of 16MHz, prescaler 1024 and counter top 249, the resulting tick period is 16 ms (62.5 Hz).
+//
+
+#define TICK_PERIOD_16MS     249
+#define PRESCALER            1024
+
+#if (portTICK_PERIOD_MS != (PRESCALER * (1 + TICK_PERIOD_16MS) * 1000 / F_CPU))
+    #warning portTICK_PERIOD_MS defined in FreeRTOSVariant.h differs from your timer configuration
+#endif
+ *
+// For register TCCR0A:
+#define NO_PWM              (0 << COM0A1) | (0 << COM0A0) | (0 << COM0B1) | (0 << COM0B0)
+#define MODE_CTC_TCCR0A     (1 << WGM01) | (0 << WGM00)
+
+// For register TCCR0B:
+#define MODE_CTC_TCCR0B     (0 << WGM02)
+#define PRESCALER_1024      (1 << CS02) | (0 << CS01) | (1 << CS00)
+
+// For register TIMSK0:
+#define INTERRUPT_AT_TOP    (1 << OCIE0A)
+
+extern "C"
+void prvSetupTimerInterrupt( void )
+{
+    // In case Arduino platform has pre-configured the timer,
+    // disable it before re-configuring here to avoid unpredicted results:
+    TIMSK0 = 0;
+ 
+    // Now configure the timer:
+    TCCR0A = NO_PWM | MODE_CTC_TCCR0A;
+    TCCR0B = MODE_CTC_TCCR0B | PRESCALER_1024;
+    OCR0A = TICK_PERIOD_16MS;
+ 
+    // Prevent missing the top and going into a possibly long wait until wrapping around:
+    TCNT0 = 0;
+ 
+    // At this point the global interrupt flag is NOT YET enabled,
+    // so you're NOT starting to get the ISR calls until FreeRTOS enables it just before launching the scheduler.
+    TIMSK0 = INTERRUPT_AT_TOP;
+}
+```
+
 Though Timer0 is given as example here, any timer can be used. A 16-bit timer (e.g., Timer1) is needed for time slices longer than ~20 milliseconds.
 
-### ISR hook
-For **preemptive** scheduler use `naked` attribute to reduce the call overhead:
+### Hardware timer ISR hook
+For **preemptive** scheduler use `ISR_NAKED` attribute to reduce the call overhead:
 
 ```cpp
 ISR(TIMER0_COMPA_vect, ISR_NAKED) __attribute__ ((hot, flatten));
 ISR(TIMER0_COMPA_vect) {
-    portSchedulerTick();
+    vPortYieldFromTick();
     __asm__ __volatile__ ( "reti" );
 }
 ```
 
-The context is saved at the start of `portSchedulerTick()`, then the tick count is incremented, finally the new context is loaded - so no dirtying occurs.
+The register context is saved at the start of `vPortYieldFromTick()`, then the tick count is incremented, finally the new context is loaded - so no dirtying occurs.
 
 
-For **cooperative** scheduler, the context is not saved because no switching is intended; therefore `naked` attribute cannot be applied because cooperative `portSchedulerTick()` dirties the context.
+For **cooperative** scheduler, the register context is not saved because no switching is intended; therefore `naked` attribute cannot be applied because cooperative `xTaskIncrementTick()` dirties the context.
 
 ```cpp
 ISR(TIMER0_COMPA_vect) __attribute__ ((hot, flatten));
 ISR(TIMER0_COMPA_vect) {
-    portSchedulerTick();
+    xTaskIncrementTick();
 }
 ```
 
-Use ISR_NOBLOCK where there is an important timer running, that should preempt the scheduler:
+Use `ISR_NOBLOCK` where there is an important timer running, that should preempt the scheduler:
 ```cpp
 ISR(portSCHEDULER_ISR, ISR_NAKED ISR_NOBLOCK) __attribute__ ((hot, flatten));
 ```
 
-Attributes `hot` and `flatten` help inlining all the code found inside your ISR thus reducing the call overhead.
+The attributes `hot` and `flatten` help inlining all the code found inside your ISR thus reducing the call overhead.
+Note: NO comma before `ISR_NOBLOCK`.
 
 
-## External clock
-### Input configuration function
-_NOTE: This code snippet was not verified on actual MCU._
+### External clock
+_NOTE: This code snippet example has not been verified to work._
 
-Assuming the external clock is connected to data pin 21 (function INT0):
+Assuming the external clock is connected to data pin 21 (external interrupt `INT0`):
 
 ```cpp
 // For register EICRA:
@@ -150,13 +208,13 @@ void prvSetupTimerInterrupt( void )
 ```
 
 
-### ISR hook
+### External clock ISR hook
 Similar to Timer0 ISR, for **preemptive** scheduler:
 
 ```cpp
 ISR(INT0_vect, ISR_NAKED) __attribute__ ((hot, flatten));
 ISR(INT0_vect) {
-    portSchedulerTick();
+    vPortYieldFromTick();
     __asm__ __volatile__ ( "reti" );
 }
 ```
@@ -165,7 +223,7 @@ For **cooperative** scheduler:
 ```cpp
 ISR(INT0_vect) __attribute__ ((hot, flatten));
 ISR(INT0_vect) {
-    portSchedulerTick();
+    xTaskIncrementTick();
 }
 ```
 
diff --git a/doc/tick_sources_timer0.cpp b/doc/tick_sources_timer0.cpp
@@ -47,6 +47,6 @@ void prvSetupTimerInterrupt( void )
 ISR(TIMER0_COMPA_vect, ISR_NAKED) __attribute__ ((hot, flatten));
 ISR(TIMER0_COMPA_vect)
 {
-    portSchedulerTick();
+    vPortYieldFromTick();
     __asm__ __volatile__ ( "reti" );
 }
diff --git a/library.properties b/library.properties
@@ -1,8 +1,8 @@
 name=FreeRTOS
-version=10.5.0-0
+version=10.5.0-1
 author=Richard Barry <info@freertos.org>
 maintainer=Phillip Stevens <phillip.stevens@gmail.com>
-sentence=<h3>FreeRTOS Real Time Operating System implemented for AVR (Uno, Nano, Leonardo, Mega).</h3>
+sentence=FreeRTOS Real Time Operating System implemented for AVR (Uno, Nano, Leonardo, Mega).
 paragraph=The primary design goals are: Easy to use, Small footprint, Robust. Uses Watchdog Timer for 15ms resolution. Slow blink = stack overflow. Fast blink = heap malloc() failure.
 category=Timing
 url=https://github.com/feilipu/Arduino_FreeRTOS_Library
diff --git a/readme.md b/readme.md
@@ -87,7 +87,7 @@ See the [Code of conduct](https://github.com/feilipu/Arduino_FreeRTOS_Library/bl
 ## Contributors ✨
 
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-6-green.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
@@ -97,12 +97,12 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 <!-- markdownlint-disable -->
 <table>
   <tr>
-    <td align="center"><a href="https://feilipu.me/"><img src="https://avatars.githubusercontent.com/u/3955592" width="100px;" alt=""/><br /><sub><b>Phillip Stevens</b></sub></a><br /><a title="Maintenance">🚧</a><a title="Code">💻</a><a title="Reviewed Pull Requests">👀</a></td>
+    <td align="center"><a href="https://feilipu.me/"><img src="https://avatars.githubusercontent.com/u/3955592" width="100px;" alt=""/><br /><sub><b>Phillip Stevens</b></sub></a><br /><a title="Maintenance">🚧</a><a title="Code">💻</a><a title="Reviewed Pull Requests">👀</a><a title=Documentation">📖</a></td>
     <td align="center"><a href="https://www.blackleg.es/"><img src="https://avatars.githubusercontent.com/u/4323228" width="100px;" alt=""/><br /><sub><b>Hector Espert</b></sub></a><br /><a title="Code">💻</a></td>
     <td align="center"><a href="https://github.com/Floessie"><img src="https://avatars.githubusercontent.com/u/10133457" width="100px;" alt=""/><br /><sub><b>Floessie</b></sub></a><br /><a title="Code">💻</a></td>
     <td align="center"><a href="https://github.com/Derekduke"><img src="https://avatars.githubusercontent.com/u/30068270" width="100px;" alt=""/><br /><sub><b>Derekduke</b></sub></a><br /><a title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/balaji"><img src="https://avatars.githubusercontent.com/u/29356302" width="100px;" alt=""/><br /><sub><b>Balaji.V</b></sub></a><br /><a title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/neboskreb"><img src="https://avatars.githubusercontent.com/u/35344069" width="100px;" alt=""/><br /><sub><b>John Y. Pazekha</b></sub></a><br /><a title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/balaji"><img src="https://avatars.githubusercontent.com/u/29356302" width="100px;" alt=""/><br /><sub><b>Balaji.V</b></sub></a><br /><a title="Code">💻</a><a title=Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/neboskreb"><img src="https://avatars.githubusercontent.com/u/35344069" width="100px;" alt=""/><br /><sub><b>John Y. Pazekha</b></sub></a><br /><a title="Code">💻</a><a title=Documentation">📖</a></td>
   </tr>
 </table>
 
diff --git a/src/FreeRTOSVariant.h b/src/FreeRTOSVariant.h
@@ -36,6 +36,8 @@ extern "C" {
 // System Tick - Scheduler timer
 // Use the Watchdog timer, and choose the rate at which scheduler interrupts will occur.
 
+/* Watchdog Timer is 128kHz nominal, but 120 kHz at 5V DC and 25 degrees is actually more accurate, from data sheet. */
+
 #ifndef portUSE_WDTO
     #define portUSE_WDTO        WDTO_15MS    // portUSE_WDTO to use the Watchdog Timer for xTaskIncrementTick
 #endif
@@ -50,94 +52,15 @@ extern "C" {
                                 WDTO_2S
 */
 
-/* Watchdog Timer is 128kHz nominal, but 120 kHz at 5V DC and 25 degrees is actually more accurate, from data sheet. */
-#define configTICK_RATE_HZ  ( (TickType_t)( (uint32_t)128000 >> (portUSE_WDTO + 11) ) )  // 2^11 = 2048 WDT scaler for 128kHz Timer
-
-/*-----------------------------------------------------------*/
-// To switch to an alternative tick source, uncomment this block:
-// #undef portUSE_WDTO
-// #define portUSE_TIMER0
-// #define portTICK_PERIOD_MS 16
+#if defined( portUSE_WDTO )
 
-/*
- * When a tick source other than WDT is used, configuring the tick source becomes the user's responsibility.
- * E.g., when using Timer0 for the tick source, you can use the following snippet:
- *
- *      // Formula for the frequency is:
- *      //      f = F_CPU / (PRESCALER * (1 + COUNTER_TOP)
- *      //
- *      // Assuming the MCU clock of 16MHz, prescaler 1024 and counter top 249, the resulting tick period is 16 ms (62.5 Hz).
- *      //
- *      #define TICK_PERIOD_16MS     249
- *      #define PRESCALER            1024
- *      #if (portTICK_PERIOD_MS != (PRESCALER * (1 + TICK_PERIOD_16MS) * 1000 / F_CPU))
- *          #warning portTICK_PERIOD_MS defined in FreeRTOSVariant.h differs from your timer configuration
- *      #endif
- *
- *      // For register TCCR0A:
- *      #define NO_PWM              (0 << COM0A1) | (0 << COM0A0) | (0 << COM0B1) | (0 << COM0B0)
- *      #define MODE_CTC_TCCR0A     (1 << WGM01) | (0 << WGM00)
- *
- *      // For register TCCR0B:
- *      #define MODE_CTC_TCCR0B     (0 << WGM02)
- *      #define PRESCALER_1024      (1 << CS02) | (0 << CS01) | (1 << CS00)
- *
- *      // For register TIMSK0:
- *      #define INTERRUPT_AT_TOP    (1 << OCIE0A)
- *
- *      extern "C"
- *      void prvSetupTimerInterrupt( void )
- *      {
- *          // In case Arduino platform has pre-configured the timer,
- *          // disable it before re-configuring here to avoid unpredicted results:
- *          TIMSK0 = 0;
- *
- *          // Now configure the timer:
- *          TCCR0A = NO_PWM | MODE_CTC_TCCR0A;
- *          TCCR0B = MODE_CTC_TCCR0B | PRESCALER_1024;
- *          OCR0A = TICK_PERIOD_16MS;
- *
- *          // Prevent missing the top and going into a possibly long wait until wrapping around:
- *          TCNT0 = 0;
- *
- *          // At this point the global interrupt flag is NOT YET enabled,
- *          // so you're NOT starting to get the ISR calls until FreeRTOS enables it just before launching the scheduler.
- *          TIMSK0 = INTERRUPT_AT_TOP;
- *      }
- */
-void prvSetupTimerInterrupt( void );
-
-/*
- * When a tick source other than WDT is used, calling the scheduler becomes the user's responsibility.
- * E.g., when using Timer0 for the tick source, you'll have a timer compare IRS wherein you call portSCHEDULER_ISR().
- *
- * Implement your ISR handler efficiently:
- *
- * For PREEMPTIVE scheduler use a `naked` attribute to reduce the call overhead:
- *
- *      ISR(portSCHEDULER_ISR, ISR_NAKED) __attribute__ ((hot, flatten)) {
- *          portSchedulerTick();
- *          __asm__ __volatile__ ( "reti" );
- *      }
- *
- *      The context is saved at the start of `portSchedulerTick()`, then the tick count is incremented, finally
- *      the new context is loaded - so no dirtying occurs.
- *
- *
- * For COOPERATIVE scheduler, the context is not saved because no switching is intended; therefore `naked` attribute
- *      cannot be applied because cooperative `portSchedulerTick()` dirties the context.
- *
- *      ISR(portSCHEDULER_ISR) __attribute__ ((hot, flatten)) {
- *          portSCHEDULER_ISR();
- *      }
- *
- *      Use ISR_NOBLOCK where there is an important timer running, that should preempt the scheduler:
- *
- *      ISR(portSCHEDULER_ISR, ISR_NAKED ISR_NOBLOCK) __attribute__ ((hot, flatten));
- *
- * Attributes `hot` and `flatten` help inlining all the code found inside your ISR thus reducing the call overhead.
- */
-void portSchedulerTick( void ) __attribute__ ((hot, flatten));
+    #define configTICK_RATE_HZ  ( (TickType_t)( (uint32_t)128000 >> (portUSE_WDTO + 11) ) )  // 2^11 = 2048 WDT scaler for 128kHz Timer
+    #define portTICK_PERIOD_MS  ( (TickType_t) _BV( portUSE_WDTO + 4 ) )
+#else
+    #warning "Variant configuration must define `configTICK_RATE_HZ` and `portTICK_PERIOD_MS` as either a macro or a constant"
+    #define configTICK_RATE_HZ  1
+    #define portTICK_PERIOD_MS  ( (TickType_t) 1000 / configTICK_RATE_HZ )
+#endif
 
 /*-----------------------------------------------------------*/
 
diff --git a/src/port.c b/src/port.c
diff --git a/src/portmacro.h b/src/portmacro.h

Original file line number	Diff line number	Diff line change
`@@ -47,6 +47,6 @@ void prvSetupTimerInterrupt( void )`
`47`	`47`	`ISR(TIMER0_COMPA_vect, ISR_NAKED) __attribute__ ((hot, flatten));`
`48`	`48`	`ISR(TIMER0_COMPA_vect)`
`49`	`49`	`{`
`50`		`- portSchedulerTick();`
	`50`	`+ vPortYieldFromTick();`
`51`	`51`	`__asm__ __volatile__ ( "reti" );`
`52`	`52`	`}`