Consolidate renaming of identifiers to clarify strict meaning of suspend vs. yield

Author: dok-net

cores/esp8266/Esp.cpp

@@ -119,14 +119,14 @@ void EspClass::deepSleep(uint64_t time_us, WakeMode mode)
 {
     system_deep_sleep_set_option(static_cast<int>(mode));
     system_deep_sleep(time_us);
-    esp_yield();
+    esp_suspend();
 }
 
 void EspClass::deepSleepInstant(uint64_t time_us, WakeMode mode)
 {
     system_deep_sleep_set_option(static_cast<int>(mode));
     system_deep_sleep_instant(time_us);
-    esp_yield();
+    esp_suspend();
 }
 
 //this calculation was taken verbatim from the SDK api reference for SDK 2.1.0.
@@ -198,7 +198,7 @@ void EspClass::reset(void)
 void EspClass::restart(void)
 {
     system_restart();
-    esp_yield();
+    esp_suspend();
 }
 
 [[noreturn]] void EspClass::rebootIntoUartDownloadMode()

cores/esp8266/PolledTimeout.h

@@ -46,7 +46,7 @@ struct DoNothing
 
 struct YieldOrSkip
 {
-  static void execute() {esp_break();}
+  static void execute() {esp_yield();}
 };
 
 template <unsigned long delayMs>

cores/esp8266/Schedule.cpp

@@ -164,9 +164,10 @@ void run_scheduled_functions()
         if (yieldNow)
         {
             // because scheduled functions might last too long for watchdog etc,
-            // this is yield() in cont stack:
+            // this is yield() in cont stack, but need to call cont_suspend directly
+            // to prevent recursion into run_scheduled_recurrent_functions()
             esp_schedule();
-            cont_yield(g_pcont);
+            cont_suspend(g_pcont);
         }
     }
 }
@@ -241,9 +242,10 @@ void run_scheduled_recurrent_functions()
         if (yieldNow)
         {
             // because scheduled functions might last too long for watchdog etc,
-            // this is yield() in cont stack:
+            // this is yield() in cont stack, but need to call cont_suspend directly
+            // to prevent recursion into run_scheduled_recurrent_functions()
             esp_schedule();
-            cont_yield(g_pcont);
+            cont_suspend(g_pcont);
         }
     } while (current && !done);
 

cores/esp8266/cont.S

@@ -21,9 +21,9 @@
     .section .irom0.text
     .align    4
     .literal_position
-    .global   cont_yield
-    .type     cont_yield, @function
-cont_yield:
+    .global   cont_suspend
+    .type     cont_suspend, @function
+cont_suspend:
     /* a1: sp */
     /* a2: void* cont_ctx */
     /* adjust stack and save registers */
@@ -35,10 +35,10 @@ cont_yield:
     s32i    a0,  a1, 16
     s32i    a2,  a1, 20
 
-    /* &cont_continue -> cont_ctx.pc_yield */
+    /* &cont_continue -> cont_ctx.pc_suspend */
     movi    a3, cont_continue
     s32i    a3, a2, 8
-    /* sp -> cont_ctx.sp_yield */
+    /* sp -> cont_ctx.sp_suspend */
     s32i    a1, a2, 12
 
     /* a0 <- cont_ctx.pc_ret */
@@ -56,7 +56,7 @@ cont_continue:
     l32i    a2,  a1, 20
     addi    a1,  a1, 24
     ret
-    .size    cont_yield, . - cont_yield
+    .size    cont_suspend, . - cont_suspend
 
 ////////////////////////////////////////////////////
 
@@ -108,7 +108,7 @@ cont_run:
     /* sp -> cont_ctx.sp_ret */
     s32i    a1, a2, 4
 
-    /* if cont_ctx.pc_yield != 0, goto cont_resume */
+    /* if cont_ctx.pc_suspend != 0, goto cont_resume */
     l32i    a4, a2, 8
     bnez    a4, cont_resume
     /* else */
@@ -119,12 +119,12 @@ cont_run:
     jx      a2
 
 cont_resume:
-    /* a1 <- cont_ctx.sp_yield */
+    /* a1 <- cont_ctx.sp_suspend */
     l32i    a1, a2, 12
-    /* reset yield flag, 0 -> cont_ctx.pc_yield */
+    /* reset yield flag, 0 -> cont_ctx.pc_suspend */
     movi    a3, 0
     s32i    a3, a2, 8
-    /* jump to saved cont_ctx.pc_yield */
+    /* jump to saved cont_ctx.pc_suspend */
     movi    a0, cont_ret
     jx       a4
 

cores/esp8266/cont.h

@@ -35,8 +35,8 @@ typedef struct cont_ {
         void (*pc_ret)(void);
         unsigned* sp_ret;
 
-        void (*pc_yield)(void);
-        unsigned* sp_yield;
+        void (*pc_suspend)(void);
+        unsigned* sp_suspend;
 
         unsigned* stack_end;
         unsigned unused1;
@@ -55,12 +55,12 @@ extern cont_t* g_pcont;
 void cont_init(cont_t*);
 
 // Run function pfn in a separate stack, or continue execution
-// at the point where cont_yield was called
+// at the point where cont_suspend was called
 void cont_run(cont_t*, void (*pfn)(void));
 
 // Return to the point where cont_run was called, saving the
 // execution state (registers and stack)
-void cont_yield(cont_t*);
+void cont_suspend(cont_t*);
 
 // Check guard bytes around the stack. Return 0 in case everything is ok,
 // return 1 if guard bytes were overwritten.
@@ -70,9 +70,9 @@ int cont_check(cont_t* cont);
 // and thus weren't used by the user code. i.e. that stack space is free. (high water mark)
 int cont_get_free_stack(cont_t* cont);
 
-// Check if yield() may be called. Returns true if we are running inside
+// Check if cont_suspend() may be called. Returns true if we are running inside
 // continuation stack
-bool cont_can_yield(cont_t* cont);
+bool cont_can_suspend(cont_t* cont);
 
 // Repaint the stack from the current SP to the end, to allow individual
 // routines' stack usages to be calculated by re-painting, checking current

cores/esp8266/cont_util.cpp

@@ -62,9 +62,9 @@ int cont_get_free_stack(cont_t* cont) {
     return freeWords * 4;
 }
 
-bool IRAM_ATTR cont_can_yield(cont_t* cont) {
+bool IRAM_ATTR cont_can_suspend(cont_t* cont) {
     return !ETS_INTR_WITHINISR() &&
-           cont->pc_ret != 0 && cont->pc_yield == 0;
+           cont->pc_ret != 0 && cont->pc_suspend == 0;
 }
 
 // No need for this to be in IRAM, not expected to be IRQ called

cores/esp8266/core_esp8266_main.cpp

@@ -62,7 +62,7 @@ cont_t* g_pcont __attribute__((section(".noinit")));
 static os_event_t s_loop_queue[LOOP_QUEUE_SIZE];
 
 /* Used to implement optimistic_yield */
-static uint32_t s_cycles_at_yield_start;
+static uint32_t s_cycles_at_resume;
 
 /* For ets_intr_lock_nest / ets_intr_unlock_nest
  * Max nesting seen by SDK so far is 2.
@@ -106,41 +106,41 @@ extern "C" void __preloop_update_frequency() {
 extern "C" void preloop_update_frequency() __attribute__((weak, alias("__preloop_update_frequency")));
 
 extern "C" bool can_yield() {
-  return cont_can_yield(g_pcont);
+  return cont_can_suspend(g_pcont);
 }
 
-static inline void esp_yield_within_cont() __attribute__((always_inline));
-static void esp_yield_within_cont() {
-        cont_yield(g_pcont);
-        s_cycles_at_yield_start = ESP.getCycleCount();
+static inline void esp_suspend_within_cont() __attribute__((always_inline));
+static void esp_suspend_within_cont() {
+        cont_suspend(g_pcont);
+        s_cycles_at_resume = ESP.getCycleCount();
         run_scheduled_recurrent_functions();
 }
 
-extern "C" void __esp_yield() {
-    if (can_yield()) {
-        esp_yield_within_cont();
+extern "C" void __esp_suspend() {
+    if (cont_can_suspend(g_pcont)) {
+        esp_suspend_within_cont();
     }
 }
 
-extern "C" void esp_yield() __attribute__ ((weak, alias("__esp_yield")));
+extern "C" void esp_suspend() __attribute__ ((weak, alias("__esp_suspend")));
 
 extern "C" IRAM_ATTR void esp_schedule() {
     ets_post(LOOP_TASK_PRIORITY, 0, 0);
 }
 
 // Replacement for delay(0). In CONT, same as yield(). Whereas yield() panics
-// in SYS, esp_break() is safe to call and only schedules CONT. Use yield()
-// whereever only called from CONT, use esp_break() if code is called from SYS
+// in SYS, esp_yield() is safe to call and only schedules CONT. Use yield()
+// whereever only called from CONT, use esp_yield() if code is called from SYS
 // or both CONT and SYS.
-extern "C" void esp_break() {
+extern "C" void esp_yield() {
     esp_schedule();
-    esp_yield();
+    esp_suspend();
 }
 
 extern "C" void __yield() {
-    if (can_yield()) {
+    if (cont_can_suspend(g_pcont)) {
         esp_schedule();
-        esp_yield_within_cont();
+        esp_suspend_within_cont();
     }
     else {
         panic();
@@ -156,7 +156,7 @@ extern "C" void optimistic_yield(uint32_t interval_us) {
 #else
         ESP.getCpuFreqMHz();
 #endif
-    if ((ESP.getCycleCount() - s_cycles_at_yield_start) > intvl_cycles &&
+    if ((ESP.getCycleCount() - s_cycles_at_resume) > intvl_cycles &&
         can_yield())
     {
         yield();
@@ -216,7 +216,7 @@ static void loop_wrapper() {
 
 static void loop_task(os_event_t *events) {
     (void) events;
-    s_cycles_at_yield_start = ESP.getCycleCount();
+    s_cycles_at_resume = ESP.getCycleCount();
     ESP.resetHeap();
     cont_run(g_pcont, &loop_wrapper);
     ESP.setDramHeap();

cores/esp8266/core_esp8266_waveform_pwm.cpp

@@ -163,7 +163,7 @@ static IRAM_ATTR void _notifyPWM(PWMState *p, bool idle) {
   forceTimerInterrupt();
   while (pwmState.pwmUpdate) {
     if (idle) {
-      esp_break();
+      esp_yield();
     }
     MEMBARRIER();
   }

cores/esp8266/core_esp8266_wiring.cpp

@@ -47,7 +47,7 @@ void __delay(unsigned long ms) {
     } else {
         esp_schedule();
     }
-    esp_yield();
+    esp_suspend();
     if(ms) {
         os_timer_disarm(&delay_timer);
     }

cores/esp8266/coredecls.h

@@ -13,9 +13,9 @@ extern "C" {
 #include <cont.h> // g_pcont declaration
 
 bool can_yield();
-void esp_yield();
+void esp_suspend();
 void esp_schedule();
-void esp_break();
+void esp_yield();
 void tune_timeshift64 (uint64_t now_us);
 void disable_extra4k_at_link_time (void) __attribute__((noinline));
 bool sntp_set_timezone_in_seconds(int32_t timezone);