From 0aa83142a42f07675a21f8d223dc97b7da0194e4 Mon Sep 17 00:00:00 2001
From: Paul Sokolovsky <pfalcon@users.sourceforge.net>
Date: Sat, 28 Jan 2017 12:08:25 +0300
Subject: [PATCH] docs/machine: Add explicit note on machine module level and
 scope.

It's very low, hardware level, with associated constraints on operations
and callbacks.
---
 docs/library/machine.Timer.rst |  3 +++
 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 318443348..eddb2ce78 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 7870da2ff..753f6b417 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
 -----------------------
-- 
GitLab