docs: Specify that machine.idle() returns at least every 1ms.

A lot of existing code (i.e. micropython-lib lps22h, lcd160cr sensor
drivers, lora sync_modem driver, usb-device-hid) calls machine.idle()
inside a tight loop that is polling some condition. This reduces the power
usage compared to constantly looping, but can be faster than calling a
sleep function. However on a tickless port there's not always an interrupt
before the condition they are polling for, so it's difficult to restructure
this code if machine.idle() doesn't have any upper limit on execution time.

This commit specifies an upper limit of 1ms before machine.idle() resumes
execution. This is already the case for all ports except rp2.

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton <[email protected]>

Author: projectgus

docs/library/machine.rst

@@ -127,14 +127,20 @@ Power related functions
 
 .. function:: idle()
 
-   Gates the clock to the CPU, useful to reduce power consumption at any time during
-   short or long periods. Peripherals continue working and execution resumes as soon
-   as any interrupt is triggered (on many ports this includes system timer
-   interrupt occurring at regular intervals on the order of millisecond).
+   Gates the clock to the CPU, useful to reduce power consumption at any time
+   during short or long periods. Peripherals continue working and execution
+   resumes as soon as any interrupt is triggered, or at most one millisecond
+   after the CPU was paused.
+
+   It is recommended to call this function inside any tight loop that is
+   continuously checking for an external change (i.e. polling). This will reduce
+   power consumption without significantly impacting performance. To reduce
+   power consumption further then see the :func:`lightsleep`,
+   :func:`time.sleep()` and :func:`time.sleep_ms()` functions.
 
 .. function:: sleep()
 
-   .. note:: This function is deprecated, use `lightsleep()` instead with no arguments.
+   .. note:: This function is deprecated, use :func:`lightsleep()` instead with no arguments.
 
 .. function:: lightsleep([time_ms])
               deepsleep([time_ms])