WIP: rp2,docs: Stop machine.idle() blocking indefinitely, update docs.

projectgus · projectgus · commit 5edcfaa48ae7 · 2024-06-25T16:13:20.000+10:00
When rp2 port went tickless the behaviour of machine.idle() changed as
there is no longer a tick interrupt to wake it up every millisecond. On a
quiet system it would now block indefinitely. No other port does this.

A lot of existing code (i.e. micropython-lib lps22h, lcd160cr sensor
drivers, lora sync_modem driver, usb-device-hid) call 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 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.

Marked WIP because on rp2 PICO, USB consumption of "while True:
machine.idle()" went from 18.9mA to 21.5mA. Consumption of "while True:
pass" is 21.7mA. This increase stays even with a much longer timeout, so I
suspect that softtimer is somehow keeping the CPU awake incorrectly. More
investigation needed.

Also changes the machine module documentation to explain the new behaviour
and recommended usage. I believe all ports will pause for at most 1ms now,
and suggest this is good behaviour to stick with.

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton &lt;angus@redyak.com.au&gt;
diff --git a/docs/library/machine.rst b/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])
diff --git a/ports/rp2/modmachine.c b/ports/rp2/modmachine.c
@@ -103,7 +103,7 @@ static void mp_machine_set_freq(size_t n_args, const mp_obj_t *args) {
 }
 
 static void mp_machine_idle(void) {
-    __wfe();
+    MICROPY_INTERNAL_WFE(1);
 }
 
 static void mp_machine_lightsleep(size_t n_args, const mp_obj_t *args) {

Original file line number	Diff line number	Diff line change
`@@ -103,7 +103,7 @@ static void mp_machine_set_freq(size_t n_args, const mp_obj_t *args) {`
`103`	`103`	`}`
`104`	`104`
`105`	`105`	`static void mp_machine_idle(void) {`
`106`		`- __wfe();`
	`106`	`+ MICROPY_INTERNAL_WFE(1);`
`107`	`107`	`}`
`108`	`108`
`109`	`109`	`static void mp_machine_lightsleep(size_t n_args, const mp_obj_t *args) {`