diff options
| -rw-r--r-- | docs/library/machine.Timer.rst | 60 | ||||
| -rw-r--r-- | docs/library/machine.TimerWiPy.rst | 13 | ||||
| -rw-r--r-- | docs/library/machine.rst | 8 |
3 files changed, 38 insertions, 43 deletions
diff --git a/docs/library/machine.Timer.rst b/docs/library/machine.Timer.rst index 5d228ea7b..69eea9d8d 100644 --- a/docs/library/machine.Timer.rst +++ b/docs/library/machine.Timer.rst @@ -4,37 +4,47 @@ class Timer -- control hardware timers ====================================== -Hardware timers deal with timing of periods and events. Timers are perhaps -the most flexible and heterogeneous kind of hardware in MCUs and SoCs, -differently greatly from a model to a model. MicroPython's Timer class -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 behaviour (which thus won't be portable to other boards). +Timer class provides the ability to trigger a Python callback function after an +expiry time, or periodically at a regular interval. -See discussion of :ref:`important constraints <machine_callbacks>` on -Timer callbacks. - -.. note:: - - Memory can't be allocated inside irq handlers (an interrupt) and so - exceptions raised within a handler don't give much information. See - :func:`micropython.alloc_emergency_exception_buf` for how to get around - this limitation, which applies to all callbacks of Timers created with - ``hard=True``. +The available features and restrictions of Timer objects vary depending on the +MicroPython board and port. If you are using a WiPy board please refer to :ref:`machine.TimerWiPy <machine.TimerWiPy>` instead of this class. +Timer Types +----------- + +There are two types of Timer in MicroPython, but not all ports support both: + +- Virtual timers. These are managed in software, and are generally more + flexible. Multiple virtual timers can be constructed and active at once. The + ``id`` of a virtual timer is ``-1``. Not all ports support virtual timers, but + it's recommended to use them when available. +- Hardware timers. Hardware timers have integer ``id`` values starting at ``0``. + The number of available ``id`` values is determined by the hardware. Hardware + timers may be more accurate for very fine sub-millisecond timing (especially + when ``hard=True`` is supported and set, see :ref:`isr_rules`.) Most + microcontroller ports support hardware timers, except Zephyr and RP2 which + only support virtual timers. + Constructors ------------ .. class:: Timer(id, /, ...) - Construct a new timer object of the given ``id``. ``id`` of -1 constructs a - virtual timer (if supported by a board). + Construct a new Timer object with the given ``id``. + + On ports which support virtual timers the ``id`` parameter is optional - the + default value is ``-1`` which constructs a virtual timer. + + On ports which support hardware timers, setting the ``id`` parameter to a + non-negative integer determines which timer to use. + ``id`` shall not be passed as a keyword argument. - See ``init`` for parameters of initialisation. + Any additional parameters are handled the same as :func:`Timer.init()`. Methods ------- @@ -73,22 +83,22 @@ Methods - ``callback`` - The callable to call upon expiration of the timer period. The callback must take one argument, which is passed the Timer object. + The ``callback`` argument shall be specified. Otherwise an exception will occur upon timer expiration: ``TypeError: 'NoneType' object isn't callable`` - ``hard`` can be one of: - - ``True`` - The callback will be executed in hard interrupt - context, which minimises delay and jitter but is subject to the - limitations described in :ref:`isr_rules` including being unable - to allocate on the heap. + - ``True`` - The callback will be executed in hard interrupt context, + which minimises delay and jitter but is subject to the limitations + described in :ref:`isr_rules`. Not all ports support hard interrupts, + see the port documentation for more information. - ``False`` - The callback will be scheduled as a soft interrupt, allowing it to allocate but possibly also introducing garbage-collection delays and jitter. - The default value of this option is port-specific for historical - reasons. + The default value of this parameter is port-specific for historical reasons. .. method:: Timer.deinit() diff --git a/docs/library/machine.TimerWiPy.rst b/docs/library/machine.TimerWiPy.rst index 54280a599..17215d502 100644 --- a/docs/library/machine.TimerWiPy.rst +++ b/docs/library/machine.TimerWiPy.rst @@ -18,16 +18,6 @@ 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 behaviour (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 - exceptions raised within a handler don't give much information. See - :func:`micropython.alloc_emergency_exception_buf` for how to get around this - limitation. - Constructors ------------ @@ -134,6 +124,9 @@ Methods ``TimerWiPy.ONE_SHOT``. In the case that mode is ``TimerWiPy.PWM`` then trigger must be equal to ``TimerWiPy.MATCH``. + Note that callback handlers are hard interrupts, and the constraints described in :ref:`isr_rules` + apply when they are executed. + Returns a callback object. .. method:: timerchannel.freq([value]) diff --git a/docs/library/machine.rst b/docs/library/machine.rst index 69eda917e..31acb7492 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -11,14 +11,6 @@ and unrestricted access to and control of hardware blocks on a system 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 :mod:`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 interrupts). See :ref:`isr_rules`. - Memory access ------------- |