docs/library/machine.Timer: Explain the id parameter in more detail.

As noted in discussion on PR #18263, the id parameter is optional on ports
that support virtual timers.

Add some more general explanation of hardware vs virtual timers, and remove
redundant documentation about timer callbacks in favour of the isr_rules
page.

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton <angus@redyak.com.au>

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