Add CallbackTimer class template to support HardwareTimer, SimpleTimer and Timer.

- Contains common logic and checks for all callback timer types
- Templated for best performance (no VMT)
- Added `TimerCallback` supporting void* arg parameter (in addition to existing `InterruptCallback`)
- Templated methods added with compile-time checks on interval (so code won't compile if out of range)
- Added methods to support setting/checking/querying intervals directly in timer ticksn
- Timer intervals stored internally in timer ticks, so querying the value confirms the actual time in use accounting for rounding, etc.

Note that delegate callbacks are supported only by the Timer class, which now also has an AutoDelete variant.

Host timer queue implementation improved, handles multiple timers properly (fixes bug where all timers get cancelled instead of just one).

Add `os_timer_arm_ticks()` function so software timers are programmed in ticks instead of microseconds or milliseconds

- Used instead of `os_timer_arm_us` provides simpler and more flexible timer interface.
- Avoids un-necessary (and potentially inaccurate) time conversions
- Timers can be used with `USE_US_TIMER=0` for 3.2us tick resolution, providing basic range of 1'54" (with SimpleTimer)
- Default is still `USE_US_TIMER=1` for 0.2us tick resolution and reduced 0'7"9s range (without using Timer class)

Add timer test module to check timer ranges, calculations and operation.

Author: mikee47

Sming/Arch/Esp8266/Components/driver/include/driver/os_timer.h

@@ -0,0 +1,33 @@
+/****
+ * Sming Framework Project - Open Source framework for high efficiency native ESP8266 development.
+ * Created 2015 by Skurydin Alexey
+ * http://github.com/SmingHub/Sming
+ * All files of the Sming Core are provided under the LGPL v3 license.
+ *
+ * os_timer.h
+ *
+ * @author: 13 August 2018 - mikee47 <[email protected]>
+ *
+ * An alternative method for setting software timers based on the tick count.
+ *
+ */
+
+#pragma once
+
+#include <esp_systemapi.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Set a software timer using the Timer2 tick value
+ * @param ptimer Timer structure
+ * @param ticks Tick count duration for the timer
+ * @param repeat_flag true if timer will automatically repeat
+ */
+void IRAM_ATTR os_timer_arm_ticks(os_timer_t* ptimer, uint32_t ticks, bool repeat_flag);
+
+#ifdef __cplusplus
+}
+#endif

Sming/Arch/Esp8266/Components/driver/os_timer.cpp

@@ -0,0 +1,109 @@
+/****
+ * Sming Framework Project - Open Source framework for high efficiency native ESP8266 development.
+ * Created 2015 by Skurydin Alexey
+ * http://github.com/SmingHub/Sming
+ * All files of the Sming Core are provided under the LGPL v3 license.
+ *
+ * os_timer.cpp
+ *
+ * @author: 13 August 2018 - mikee47 <[email protected]>
+ *
+ * An alternative method for setting software timers based on the tick count.
+ *
+ * Technical notes
+ * ---------------
+ *
+ * This information was obtained by examining the SDK timer function assembly code
+ * from SDK versions 1.5.4, 2.2 and 3.0.
+ *
+ * Software timers for the ESP8266 are defined by an `os_timer_t` structure.
+ * When armed, the structure is contained in a queue ordered by expiry time.
+ * Thus, the first timer is the next one to expire and the expiry time is programmed
+ * into the Timer2 alarm register (counter compare). The timer alarm interrupt simply
+ * queues a task to handle the event.
+ *
+ * The timer task dequeues the timer (setting `timer_next` to -1) and invokes the
+ * user-provided callback routine. If it is a repeating timer then it is re-queued.
+ * The queue is implemented as a linked list so adding and removing items is very efficient
+ * and requires no additional memory allocation.
+ *
+ * Because the Sming Clock API handles all time/tick conversions, a new `os_timer_arm_ticks()`
+ * function is used which replaces the existing `ets_timer_arm_new()` function. This makes
+ * timer operation more transparent, faster.
+ *
+ * `ets_timer_arm_new`
+ * -------------------
+ *
+ * This is the SDK function which implements `os_timer_arm_us` and `os_timer_arm`.
+ *
+ * With ms_flag = false, the maximum value for `time` is 428496729us. The SDK documentation
+ * for `os_timer_arm_us` states a maximum value of 0x0FFFFFFF, which is incorrect; it probably
+ * applies to earlier SDK releases.
+ *
+ * Note: If `system_timer_reinit()` hasn't been called then calling with `ms_flag = false` will fail.
+ *
+ * This figure can be derived as follows, where 0x7FFFFFFF is the maximum tick range
+ * (signed comparison) and 5000000 is the Timer2 frequency with /16 prescale:
+ *
+ * 		0x7FFFFFFF / 5000000 = 429496729.4us = 0' 7" 9.5s
+ *
+ * With ms_flag = true, the limit is 428496ms which agrees with the value stated in the SDK documentation.
+ *
+ * Timer2 frequencies for two prescaler settings are:
+ * Prescale  Frequency   Period  Range (0x7FFFFFFF ticks)
+ * --------  ---------   ------  -------------------------
+ * - /1      80000000    12.5ns  0'  0" 26.84s
+ * - /16      5000000    200ns   0'  7"  9.5s
+ * - /256      312500    3.2us   1' 54" 31.95s
+ *
+ * @see See also `drivers/hw_timer.h`
+ *
+ */
+
+#include "include/driver/os_timer.h"
+#include <driver/hw_timer.h>
+
+/*
+ * This variable points to the first timer in the queue.
+ * It's a global variable defined in the Espressif SDK.
+ */
+extern "C" os_timer_t* timer_list;
+
+/**
+ * @brief Insert a timer into the queue
+ * @param ptimer The timer to insert
+ * @param expire The Timer2 tick value when this timer is due
+ * @note Timer is inserted into queue according to its expiry time, and _after_ any
+ * existing timers with the same expiry time. If it's inserted at the head of the
+ * queue (i.e. it's the new value for `timer_list`) then the Timer2 alarm register
+ * is updated.
+ */
+static void IRAM_ATTR timer_insert(os_timer_t* ptimer, uint32_t expire)
+{
+	os_timer_t* t_prev = nullptr;
+	auto t = timer_list;
+	while(t != nullptr) {
+		if(int(t->timer_expire - expire) > 0) {
+			break;
+		}
+		t_prev = t;
+		t = t->timer_next;
+	}
+	if(t_prev == nullptr) {
+		timer_list = ptimer;
+		hw_timer2_set_alarm(expire);
+	} else {
+		t_prev->timer_next = ptimer;
+	}
+	ptimer->timer_next = t;
+	ptimer->timer_expire = expire;
+}
+
+void os_timer_arm_ticks(os_timer_t* ptimer, uint32_t ticks, bool repeat_flag)
+{
+	os_timer_disarm(ptimer);
+	ptimer->timer_period = repeat_flag ? ticks : 0;
+	ets_intr_lock();
+	timer_insert(ptimer, hw_timer2_read() + ticks);
+	ets_intr_unlock();
+}

Sming/Arch/Host/Components/esp_hal/include/esp_timer_legacy.h

@@ -1,3 +1,11 @@
+/*
+ * This implementation mimics the behaviour of the ESP8266 Non-OS SDK timers,
+ * using Timer2 as the reference (which is _not_ in microseconds!)
+ *
+ * The ESP32 IDF contains more sophisticated timer implementations, but also
+ * this same API which it refers to as the 'legacy' timer API.
+ */
+
 #pragma once
 #include "c_types.h"
 
@@ -7,16 +15,31 @@ extern "C" {
 
 typedef void os_timer_func_t(void* timer_arg);
 
+/**
+ * @brief This is the structure used by the Espressif timer API
+ * @note This is used as an element in a linked list
+ * The Espressif implementation orders the list according to next expiry time.
+ * os_timer_setfn and os_timer_disarm set timer_next to -1
+ * When expired, timer_next is 0
+ */
 struct os_timer_t {
+	/// If disarmed, set to -1, otherwise points to the next queued timer (or NULL if last in the list)
 	struct os_timer_t* timer_next;
+	/// Set to the next Timer2 count value when the timer will expire
 	uint32_t timer_expire;
+	/// 0 if this is a one-shot timer, otherwise defines the interval in Timer2 ticks
 	uint32_t timer_period;
+	/// User-provided callback function pointer
 	os_timer_func_t* timer_func;
+	/// Argument passed to the callback function
 	void* timer_arg;
 };
 
+void os_timer_arm_ticks(struct os_timer_t* ptimer, uint32_t ticks, bool repeat_flag);
+
 void os_timer_arm(struct os_timer_t* ptimer, uint32_t time, bool repeat_flag);
 void os_timer_arm_us(struct os_timer_t* ptimer, uint32_t time, bool repeat_flag);
+
 void os_timer_disarm(struct os_timer_t* ptimer);
 void os_timer_setfn(struct os_timer_t* ptimer, os_timer_func_t* pfunction, void* parg);
 

Sming/Arch/Host/Components/esp_hal/timer_legacy.cpp

@@ -1,42 +1,62 @@
-
 #include "include/esp_system.h"
 #include "include/esp_timer_legacy.h"
 #include <hostlib/threads.h>
+#include <driver/hw_timer.h>
+#include <muldiv.h>
+#include <assert.h>
 
 static os_timer_t* timer_head;
 static CMutex mutex;
 
-void os_timer_arm(struct os_timer_t* ptimer, uint32_t time, bool repeat_flag)
+static void timer_insert(uint32_t expire, os_timer_t* ptimer)
 {
-	os_timer_arm_us(ptimer, time * 1000UL, repeat_flag);
+	os_timer_t* t_prev = nullptr;
+	auto t = timer_head;
+	while(t != nullptr) {
+		if(int(t->timer_expire - expire) > 0) {
+			break;
+		}
+		t_prev = t;
+		t = t->timer_next;
+	}
+	if(t_prev == nullptr) {
+		timer_head = ptimer;
+	} else {
+		t_prev->timer_next = ptimer;
+	}
+	ptimer->timer_next = t;
+	ptimer->timer_expire = expire;
 }
 
-void os_timer_arm_us(struct os_timer_t* ptimer, uint32_t time, bool repeat_flag)
+void os_timer_arm_ticks(os_timer_t* ptimer, uint32_t ticks, bool repeat_flag)
 {
-	os_timer_disarm(ptimer);
-	ptimer->timer_next = nullptr;
-	ptimer->timer_expire = system_get_time() + time;
-	ptimer->timer_period = repeat_flag ? time : 0;
+	assert(ptimer != nullptr);
+	//	assert(time <= MAX_OS_TIMER_INTERVAL_US);
 
-	// Append to list
+	os_timer_disarm(ptimer);
+	ptimer->timer_period = repeat_flag ? ticks : 0;
 	mutex.lock();
-	if(timer_head == nullptr) {
-		timer_head = ptimer;
-	} else {
-		auto t = timer_head;
-		while(t->timer_next != nullptr) {
-			t = t->timer_next;
-		}
-		t->timer_next = ptimer;
-	}
+	timer_insert(hw_timer2_read() + ticks, ptimer);
 	mutex.unlock();
 }
 
+void os_timer_arm(struct os_timer_t* ptimer, uint32_t time, bool repeat_flag)
+{
+	using R = std::ratio<HW_TIMER2_CLK, 1000>;
+	auto ticks = muldiv<R::num, R::den>(time);
+	os_timer_arm_ticks(ptimer, ticks, repeat_flag);
+}
+
+void os_timer_arm_us(struct os_timer_t* ptimer, uint32_t time, bool repeat_flag)
+{
+	using R = std::ratio<HW_TIMER2_CLK, 1000000>;
+	auto ticks = muldiv<R::num, R::den>(time);
+	os_timer_arm_ticks(ptimer, ticks, repeat_flag);
+}
+
 void os_timer_disarm(struct os_timer_t* ptimer)
 {
-	if(ptimer == nullptr) {
-		return;
-	}
+	assert(ptimer != nullptr);
 
 	mutex.lock();
 	if(timer_head != nullptr) {
@@ -53,6 +73,7 @@ void os_timer_disarm(struct os_timer_t* ptimer)
 				t = t->timer_next;
 			}
 		}
+		ptimer->timer_next = reinterpret_cast<os_timer_t*>(-1);
 	}
 	mutex.unlock();
 }
@@ -62,6 +83,7 @@ void os_timer_setfn(struct os_timer_t* ptimer, os_timer_func_t* pfunction, void*
 	if(ptimer != nullptr) {
 		ptimer->timer_func = pfunction;
 		ptimer->timer_arg = parg;
+		ptimer->timer_next = reinterpret_cast<os_timer_t*>(-1);
 	}
 }
 
@@ -72,23 +94,24 @@ static os_timer_t* find_expired_timer()
 		return nullptr;
 	}
 
-	auto time_now = system_get_time();
+	auto ticks_now = hw_timer2_read();
 	os_timer_t* t_prev = nullptr;
 	for(auto t = timer_head; t != nullptr; t_prev = t, t = t->timer_next) {
-		if(int(t->timer_expire - time_now) > 0) {
-			continue;
+		if(int(t->timer_expire - ticks_now) > 0) {
+			// No timers due
+			break;
 		}
 
-		// Found an expired timer
-		if(t->timer_period == 0) {
-			// Non-repeating timer, remove now
-			if(t == timer_head) {
-				timer_head = nullptr;
-			} else if(t_prev != nullptr) {
-				t_prev->timer_next = t->timer_next;
-			}
-		} else {
-			t->timer_expire = time_now + t->timer_period;
+		// Found an expired timer, so remove from queue
+		if(t == timer_head) {
+			timer_head = t->timer_next;
+		} else if(t_prev != nullptr) {
+			t_prev->timer_next = t->timer_next;
+		}
+
+		// Repeating timer?
+		if(t->timer_period != 0) {
+			timer_insert(t->timer_expire + t->timer_period, t);
 		}
 
 		return t;