From 4489e239bb680303af1af842aeab863b4bda8b4d Mon Sep 17 00:00:00 2001 From: "Earle F. Philhower, III" Date: Sat, 28 Sep 2019 15:03:28 -0700 Subject: [PATCH] Add interrupt section to docs (#6560) * Add info about installing python3 on Mac, Linux The Mac requires special handholding to allow SSL connections for get.py, so document those for end users. * Add interrupt section to docs Adds a section on interrupts to the docs and lists the restrictions and warnings about running long tasks. Fixes #6428 * Update per review comments --- doc/reference.rst | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/doc/reference.rst b/doc/reference.rst index 29ae74e37..db789128e 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -1,6 +1,42 @@ Reference ========= +Interrupts +---------- + +Interrupts can be used on the ESP8266, but they must be used with care +and have several limitations: + +* Interrupt callback functions must be in IRAM, because the flash may be + in the middle of other operations when they occur. Do this by adding + the ``ICACHE_RAM_ATTR`` attribute on the function definition. If this + attribute is not present, the sketch will crash when it attempts to + ``attachInterrupt`` with an error message. + +.. code:: cpp + + ICACHE_RAM_ATTR void gpio_change_handler(void *data) {... + +* Interrupts must not call ``delay()`` or ``yield()``, or call any routines + which internally use ``delay()`` or ``yield()`` either. + +* Long-running (>1ms) tasks in interrupts will cause instabilty or crashes. + WiFi and other portions of the core can become unstable if interrupts + are blocked by a long-running interrupt. If you have much to do, you can + set a volatile global flag that your main ``loop()`` can check each pass + or use a scheduled function (which will be called outside of the interrupt + context when it is safe) to do long-running work. + +* Memory operations can be dangerous and should be avoided in interrupts. + Calls to ``new`` or ``malloc`` should be minimized because they may require + a long running time if memory is fragmented. Calls to ``realloc`` and + ``free`` must NEVER be called. Using any routines or objects which call + ``free`` or ``realloc`` themselves is also forbidden for the same reason. + This means that ``String``, ``std::string``, ``std::vector`` and other + classes which use contiguous memory that may be resized must be used with + extreme care (ensuring strings aren't changed, vector elements aren't + added, etc.). + Digital IO ----------