esp_timer: document limitations on timeout/period

Closes https://github.com/espressif/esp-idf/issues/2572
Closes https://github.com/espressif/esp-idf/issues/2350

diff --git a/docs/en/api-reference/system/esp_timer.rst b/docs/en/api-reference/system/esp_timer.rst
index a4fdbc28f147f61fa08bc54b44b5711851f237fe..2f8423c0c96a4d93c435cdf68033e52bfb452d74 100644 (file)
--- a/docs/en/api-reference/system/esp_timer.rst
+++ b/docs/en/api-reference/system/esp_timer.rst
@@ -17,6 +17,12 @@ Timer callbacks are dispatched from a high-priority ``esp_timer`` task. Because
 
 .. note: Provisions are made to dispatch some simple callbacks directly from the interrupt handler, if needed. However this option is not implemented at the moment.
 
+If other tasks with priority higher than ``esp_timer`` are running, callback dispatching will be delayed until ``esp_timer`` task has a chance to run. For example, this will happen if a SPI Flash operation is in progress.
+
+Creating and starting a timer, and dispatching the callback takes some time. Therefore there is a lower limit to the timeout value of one-shot ``esp_timer``. If :cpp:func:`esp_timer_start_once` is called with a timeout value less than 20us, the callback will be dispatched only after approximately 20us.
+
+Periodic ``esp_timer`` also imposes a 50us restriction on the minimal timer period. Periodic software timers with period of less than 50us are not practical since they would consume most of the CPU time. Consider using dedicated hardware peripherals or DMA features if you find that a timer with small period is required.
+
 Using ``esp_timer`` APIs
 ------------------------