Add note in documentation about behaviour of one-shot Hardware timer with Esp8266 (#2713)

Author: mikee47

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

@@ -80,7 +80,12 @@ void IRAM_ATTR hw_timer1_attach_interrupt(hw_timer_source_type_t source_type, hw
  * @brief Enable the timer
  * @param div
  * @param intr_type
- * @param auto_load
+ * @param auto_load true for repeating timer, false for one-shot
+ *
+ * Note: With one-shot timer application callback must stop the timer when it is no longer required.
+ * This is to reduce callback latency.
+ * If this is not done, timer will trigger again when timer counter wraps around to 0.
+ * For /16 divisor this is only 1.7s.
  */
 inline void IRAM_ATTR hw_timer1_enable(hw_timer_clkdiv_t div, hw_timer_intr_type_t intr_type, bool auto_load)
 {

docs/source/framework/timers/hardware-timer.rst

@@ -11,5 +11,19 @@ The API for hardware (and :doc:`timer-queue` timers) is identical, implemented u
 :cpp:class:`CallbackTimer` class template for best performance.
 
 
+.. note::
+
+   **Applies to Esp8266 architecture only.**
+
+   As with all Callback timers, the :cpp:type:`HardwareTimer` can be one-shot or repeating.
+
+   With the Esp8266 a one-shot timer will repeat after it has been triggered, but only after the timer
+   counter wraps around. The Esp8266 only has 23 bits of resolution so with a clock divider of 16
+   this will happen after about 1.7s.
+
+   Because the Esp8266 lacks any proper PWM hardware the timer latency is critical.
+   Adding any additional code to the callback is therefore left to the programmer.
+
+
 .. doxygengroup:: hardware_timer
    :members: