Fix ticks

ports/atmel-samd/background.c

@@ -42,18 +42,18 @@
 // PB03 is physical pin "SCL" on the Metro M4 express
 // so you can't use this code AND an i2c peripheral
 // at the same time unless you change this
-void port_start_background_task(void) {
+void port_start_background_tick(void) {
     REG_PORT_DIRSET1 = (1 << 3);
     REG_PORT_OUTSET1 = (1 << 3);
 }
 
-void port_finish_background_task(void) {
+void port_finish_background_tick(void) {
     REG_PORT_OUTCLR1 = (1 << 3);
 }
 #else
-void port_start_background_task(void) {
+void port_start_background_tick(void) {
 }
-void port_finish_background_task(void) {
+void port_finish_background_tick(void) {
 }
 #endif
 

ports/atmel-samd/common-hal/frequencyio/FrequencyIn.c

@@ -156,7 +156,7 @@ void frequencyin_interrupt_handler(uint8_t index) {
             }
 
             // Check if we've reached the upper limit of detection
-            if (!supervisor_background_tasks_ok() || self->errored_too_fast) {
+            if (!supervisor_background_ticks_ok() || self->errored_too_fast) {
                 self->errored_too_fast = true;
                 frequencyin_emergency_cancel_capture(i);
             }

ports/broadcom/background.c

@@ -28,9 +28,9 @@
 #include "py/runtime.h"
 #include "supervisor/port.h"
 
-void port_start_background_task(void) {
+void port_start_background_tick(void) {
 }
-void port_finish_background_task(void) {
+void port_finish_background_tick(void) {
 }
 
 void port_background_tick(void) {

ports/cxd56/background.c

@@ -34,7 +34,7 @@ void port_background_tick(void) {
 }
 void port_background_task(void) {
 }
-void port_start_background_task(void) {
+void port_start_background_tick(void) {
 }
-void port_finish_background_task(void) {
+void port_finish_background_tick(void) {
 }

ports/espressif/background.c

@@ -51,8 +51,8 @@ void port_background_tick(void) {
 void port_background_task(void) {
 }
 
-void port_start_background_task(void) {
+void port_start_background_tick(void) {
 }
 
-void port_finish_background_task(void) {
+void port_finish_background_tick(void) {
 }

ports/litex/background.c

@@ -34,7 +34,7 @@ void port_background_task(void) {
 }
 void port_background_tick(void) {
 }
-void port_start_background_task(void) {
+void port_start_background_tick(void) {
 }
-void port_finish_background_task(void) {
+void port_finish_background_tick(void) {
 }

ports/mimxrt10xx/background.c

@@ -37,8 +37,8 @@ void PLACE_IN_ITCM(port_background_task)(void) {
 void port_background_tick(void) {
 }
 
-void port_start_background_task(void) {
+void port_start_background_tick(void) {
 }
 
-void port_finish_background_task(void) {
+void port_finish_background_tick(void) {
 }

ports/nrf/background.c

@@ -44,10 +44,10 @@
 #include "common-hal/audiopwmio/PWMAudioOut.h"
 #endif
 
-void port_start_background_task(void) {
+void port_start_background_tick(void) {
 }
 
-void port_finish_background_task(void) {
+void port_finish_background_tick(void) {
 }
 
 void port_background_tick(void) {

ports/raspberrypi/background.c

@@ -28,10 +28,10 @@
 #include "py/runtime.h"
 #include "supervisor/port.h"
 
-void port_start_background_task(void) {
+void port_start_background_tick(void) {
 }
 
-void port_finish_background_task(void) {
+void port_finish_background_tick(void) {
 }
 
 void port_background_tick(void) {

ports/stm/background.c

@@ -37,7 +37,7 @@ void port_background_task(void) {
 }
 void port_background_tick(void) {
 }
-void port_start_background_task(void) {
+void port_start_background_tick(void) {
 }
-void port_finish_background_task(void) {
+void port_finish_background_tick(void) {
 }

py/circuitpy_mpconfig.h

@@ -439,8 +439,8 @@ struct _supervisor_allocation_node;
     const char *readline_hist[8]; \
     struct _supervisor_allocation_node *first_embedded_allocation; \
 
-void supervisor_run_background_tasks_if_tick(void);
-#define RUN_BACKGROUND_TASKS (supervisor_run_background_tasks_if_tick())
+void background_callback_run_all(void);
+#define RUN_BACKGROUND_TASKS (background_callback_run_all())
 
 #define MICROPY_VM_HOOK_LOOP RUN_BACKGROUND_TASKS;
 #define MICROPY_VM_HOOK_RETURN RUN_BACKGROUND_TASKS;

supervisor/background_callback.h

@@ -37,15 +37,22 @@
  * To schedule the work, use background_callback_add, with fun as the
  * function to call and data pointing to the object itself.
  *
- * Next time run_background_tasks_if_tick is called, the callback will
- * be run and removed from the linked list.
+ * Next time background_callback_run_all() is called, the callback will
+ * be run and removed from the linked list. Use `RUN_BACKGROUND_TASKS;` instead
+ * of calling background_callback_run_all() directly.
  *
  * Queueing a task that is already queued does nothing.  Unconditionally
  * re-queueing it from its own background task will cause it to run during the
  * very next background-tasks invocation, leading to a CircuitPython freeze, so
  * don't do that.
  *
  * background_callback_add can be called from interrupt context.
+ *
+ * If your work isn't triggered by an event, then it may be better implemented
+ * using ticks, which runs tasks every millisecond or so. Ticks are enabled with
+ * supervisor_enable_tick() and disabled with supervisor_disable_tick(). When
+ * enabled, a timer will schedule a callback to supervisor_background_tick(),
+ * which includes port_background_tick(), every millisecond.
  */
 typedef void (*background_callback_fun)(void *data);
 typedef struct background_callback {

supervisor/port.h

@@ -94,14 +94,15 @@ void port_idle_until_interrupt(void);
 void port_background_tick(void);
 
 // Execute port specific actions during background tasks. This is before the
-// background callback system.
+// background callback system and happens *very* often. Use
+// port_background_tick() when possible.
 void port_background_task(void);
 
-// Take port specific actions at the beginning and end of background tasks.
+// Take port specific actions at the beginning and end of background ticks.
 // This is used e.g., to set a monitoring pin for debug purposes.  "Actual
-// work" should be done in port_background_task() instead.
-void port_start_background_task(void);
-void port_finish_background_task(void);
+// work" should be done in port_background_tick() instead.
+void port_start_background_tick(void);
+void port_finish_background_tick(void);
 
 // Some ports need special handling to wake the main task from another task. The
 // port must implement the necessary code in this function.  A default weak

supervisor/shared/tick.c

@@ -65,8 +65,8 @@ static volatile uint64_t last_finished_tick = 0;
 
 static volatile size_t tick_enable_count = 0;
 
-static void supervisor_background_tasks(void *unused) {
-    port_start_background_task();
+static void supervisor_background_tick(void *unused) {
+    port_start_background_tick();
 
     assert_heap_ok();
 
@@ -80,16 +80,16 @@ static void supervisor_background_tasks(void *unused) {
 
     filesystem_background();
 
-    port_background_task();
+    port_background_tick();
 
     assert_heap_ok();
 
     last_finished_tick = port_get_raw_ticks(NULL);
 
-    port_finish_background_task();
+    port_finish_background_tick();
 }
 
-bool supervisor_background_tasks_ok(void) {
+bool supervisor_background_ticks_ok(void) {
     return port_get_raw_ticks(NULL) - last_finished_tick < 1024;
 }
 
@@ -103,7 +103,7 @@ void supervisor_tick(void) {
     keypad_tick();
     #endif
 
-    background_callback_add(&tick_callback, supervisor_background_tasks, NULL);
+    background_callback_add(&tick_callback, supervisor_background_tick, NULL);
 }
 
 uint64_t supervisor_ticks_ms64() {
@@ -117,11 +117,6 @@ uint32_t supervisor_ticks_ms32() {
     return supervisor_ticks_ms64();
 }
 
-
-void PLACE_IN_ITCM(supervisor_run_background_tasks_if_tick)() {
-    background_callback_run_all();
-}
-
 void mp_hal_delay_ms(mp_uint_t delay_ms) {
     uint64_t start_tick = port_get_raw_ticks(NULL);
     // Adjust the delay to ticks vs ms.

supervisor/shared/tick.h

@@ -54,13 +54,6 @@ extern uint32_t supervisor_ticks_ms32(void);
  */
 extern uint64_t supervisor_ticks_ms64(void);
 
-/** @brief Run background ticks, but only about every millisecond.
- *
- * Normally, this is not called directly.  Instead use the RUN_BACKGROUND_TASKS
- * macro.
- */
-extern void supervisor_run_background_if_tick(void);
-
 extern void supervisor_enable_tick(void);
 extern void supervisor_disable_tick(void);
 
@@ -70,6 +63,6 @@ extern void supervisor_disable_tick(void);
  * Note that when ticks are not enabled, this function can return false; this is
  * intended.
  */
-extern bool supervisor_background_tasks_ok(void);
+extern bool supervisor_background_ticks_ok(void);
 
 #endif