diff options
| author | Paul Sokolovsky <pfalcon@users.sourceforge.net> | 2017-01-28 12:08:25 +0300 |
|---|---|---|
| committer | Paul Sokolovsky <pfalcon@users.sourceforge.net> | 2017-01-28 12:08:25 +0300 |
| commit | 0aa83142a42f07675a21f8d223dc97b7da0194e4 (patch) | |
| tree | 314684c6bc52c17c324b906f151fa60bcd366c06 | |
| parent | 56e7ebf07af8d570aadfe53b4686d014af574bf3 (diff) | |
| download | micropython-0aa83142a42f07675a21f8d223dc97b7da0194e4.tar.gz micropython-0aa83142a42f07675a21f8d223dc97b7da0194e4.zip | |
docs/machine: Add explicit note on machine module level and scope.
It's very low, hardware level, with associated constraints on operations
and callbacks.
| -rw-r--r-- | docs/library/machine.Timer.rst | 3 | ||||
| -rw-r--r-- | docs/library/machine.rst | 23 |
2 files changed, 21 insertions, 5 deletions
diff --git a/docs/library/machine.Timer.rst b/docs/library/machine.Timer.rst index 318443348e..eddb2ce780 100644 --- a/docs/library/machine.Timer.rst +++ b/docs/library/machine.Timer.rst @@ -10,6 +10,9 @@ defines a baseline operation of executing a callback with a given period (or once after some delay), and allow specific boards to define more non-standard behavior (which thus won't be portable to other boards). +See discussion of :ref:`important constraints <machine_callbacks>` on +Timer callbacks. + .. note:: Memory can't be allocated inside irq handlers (an interrupt) and so diff --git a/docs/library/machine.rst b/docs/library/machine.rst index 7870da2ffc..753f6b4173 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -1,10 +1,23 @@ -:mod:`machine` --- functions related to the board -================================================= +:mod:`machine` --- functions related to the hardware +==================================================== .. module:: machine - :synopsis: functions related to the board - -The ``machine`` module contains specific functions related to the board. + :synopsis: functions related to the hardware + +The ``machine`` module contains specific functions related to the hardware +on a particular board. Most functions in this module allow to achieve direct +and unrestricted access to and control of hardware blocks on a system +(like CPU, timers, buses, etc.). Used incorrectly, this can lead to +malfunction, lockups, crashes of your board, and in extreme cases, hardware +damage. + +.. _machine_callbacks: + +A note of callbacks used by functions and class methods of ``machine`` module: +all these callbacks should be considered as executing in an interrupt context. +This is true for both physical devices with IDs >= 0 and "virtual" devices +with negative IDs like -1 (these "virtual" devices are still thin shims on +top of real hardware and real hardware intrerrupts). See :ref:`isr_rules`. Reset related functions ----------------------- |