arduino/esp8266
1
0
Fork 0
mirror of https://github.com/esp8266/Arduino.git synced 2025-04-21 10:26:06 +03:00
Code

Add interrupt section to docs (#6560)

Browse Source 
* 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
This commit is contained in:
Earle F. Philhower, III 2019-09-28 15:03:28 -07:00 committed by GitHub
parent c755771098
commit 4489e239bb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 36 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
doc/reference.rst
View File

@ -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
----------