Commit 0aa83142 authored by Paul Sokolovsky's avatar Paul Sokolovsky
Browse files

docs/machine: Add explicit note on machine module level and scope.

It's very low, hardware level, with associated constraints on operations
and callbacks.
parent 56e7ebf0
......@@ -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
......
: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
-----------------------
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment