fix: make fatal shutdown diagnostics visible

Author: pikasTech

docs/MDTODO/details/pikapython-syntax-compatibility/R14.16_Task_Report.md

@@ -26,7 +26,14 @@
 - 定向 GTest：递归正常调用、递归错误传播、单段/嵌套 host 对象路径共 3/3 通过。
 - 定向 Valgrind：11,688 allocs / 11,688 frees，退出 0 bytes，0 leaks，0 errors。
 - Docker 默认配置（`PIKA_CONFIG_ENABLE=ON`、4096 B VM stack）隔离网络及既定不稳定 REPL 项后，454/454 通过。
-- 曾误复用 `PIKA_CONFIG_ENABLE=OFF` 的 512 B stack 构建，测试在请求 528 B 时进入既有 overflow handler；改用全新默认配置构建后全量通过，该错误口径未计入结论。
+- 曾误复用 `PIKA_CONFIG_ENABLE=OFF` 的 512 B stack 构建，测试请求 528 B 时清晰报告 `OverflowError`、请求大小和当前容量，随后进入永久停止状态。
+- 该停止状态符合资源受限微控制器的致命故障设计：真实 VM 栈耗尽后必须停止，不能恢复执行；它不是本轮性能回归，也不是需要改成可捕获返回的普通错误。
+
+## VM 栈错误边界
+
+- 参数槽位超限、非法语法和其他可在写入前识别的边界必须返回明确错误，禁止越界写或静默死机。
+- VM 数据栈已经真实耗尽时属于致命故障：必须先清晰报告，再永久停机或进入平台 panic。
+- 后续小栈测试应使用受控子进程或 watchdog 验证“报告完整且停止执行”，不能以进程继续运行或正常退出作为验收条件。
 
 ## 在线基准
 

docs/MDTODO/details/pikapython-syntax-compatibility/R14.17_Task_Report.md

@@ -0,0 +1,32 @@
+# R14.17 任务报告
+
+## 结论
+
+真实 VM 栈耗尽继续保持 MCU 致命故障语义：先输出明确诊断，再永久停止，禁止恢复执行。本轮修复了缓冲输出模式下停机报告可能未刷新而静默的问题，并将其他明确不可恢复路径收敛到同一停机顺序，未改变 VM、parser 或对象系统架构。
+
+## 修复
+
+- `pika_platform_fflush()` 改为始终执行显式刷新；`PIKA_UNBUFFERED_ENABLE` 仅控制 `pika_putchar()` 是否逐字符自动刷新，不再屏蔽调用方主动刷新。
+- 新增 `pika_platform_fatal_handle()`：先显式刷新，再进入可由平台覆盖的 panic，若平台 panic 意外返回则以死循环兜底，保证致命故障不恢复执行；helper 位于 `PIKA_PLATFORM_NO_WEAK` 条件外，自定义平台仍只需实现既有 flush/panic 接口。
+- VM 栈耗尽报告包含请求字节数、配置容量、`PIKA_STACK_BUFF_SIZE` 和“execution stopped”，随后进入统一 fatal-stop。
+- 堆耗尽、方法声明行缓冲区耗尽、`pika_sprintf` 缓冲区耗尽、禁用 event 功能后误用 event API 的直接死循环改为明确 FatalError 后统一停机。
+- `methodArg_getTypeList()` 的容量判断由 `>` 修正为 `>=`，覆盖字符串长度恰好等于缓冲区容量但仍缺少结尾 NUL 的一字节越界边界。
+
+## 测试
+
+- 新增 Linux `fork + pipe + poll` watchdog 单元测试：子进程将 stdout 设为全缓冲后触发 VM 栈耗尽；父进程验证 FatalError、80/64 字节容量信息和停止说明完整出现，并验证子进程未返回，最后以 `SIGKILL` 受控回收。
+- 默认 Linux 配置定向 stack 测试 2/2 通过。
+- 临时设置 `PIKA_UNBUFFERED_ENABLE=0` 后，反汇编确认 `pika_putchar()` 不含逐字符 flush；同一 fatal watchdog 仍通过，直接覆盖原静默条件。配置随后恢复，未进入提交。
+- Docker `pikadev`、`PIKA_CONFIG_ENABLE=ON`、隔离网络/LVGL及既定不稳定 REPL 项后，455/455 通过。
+- Valgrind 需要把 Docker 异常的 `nofile=1073741816` 收敛为 65536；普通 stack 与 fatal watchdog 均通过，0 bytes in use、0 leaks、0 errors。
+- `PIKA_PLATFORM_NO_WEAK=1` 条件下单独编译 `PikaPlatform.c` 通过，未增加自定义平台必须实现的新符号。
+
+## 资源
+
+以 `origin/master` 的 `644d482cd` 为基线，在 Docker 内使用相同生成 API 集、Release、`PIKA_CONFIG_ENABLE=ON` 比较 core 静态库：
+
+- text：1,041,589 -> 1,041,401 B，减少 188 B；
+- data：126,480 -> 126,480 B；
+- bss：24,342 -> 24,342 B。
+
+统一 fatal-stop helper 和压缩后的具体诊断抵消了错误可见性新增代码，RAM/Flash 总体未膨胀。

docs/MDTODO/pikapython-syntax-compatibility.md

@@ -358,3 +358,7 @@ P0 修复空 import 与 from-import 缺名称在 Suger_import 路径的解析崩
 ### R14.16 [completed]
 
 在上一轮递归调用查找优化基础上重新采样 runtime/VM 热点，选择至少一个由 benchmark 证明且不改变大架构的性能债务完成同配置 A/B；同步探测相关 runtime 错误边界并补单元测试，保持 RAM/Flash 总体不膨胀，CI 仅后台验收不阻塞本轮开发，完成任务后将详细报告写入[任务报告](./details/pikapython-syntax-compatibility/R14.16_Task_Report.md)。
+
+### R14.17 [completed]
+
+按 MCU 致命故障设计改进 VM 栈真实耗尽时的停机前错误可见性：保持清晰报告后永久停止，不恢复执行；盘点并修复停机信息缺失、不清晰或因缓冲未刷新而静默的路径，补受控子进程/watchdog 单元测试，并保持架构和资源总体不膨胀，完成任务后将详细报告写入[任务报告](./details/pikapython-syntax-compatibility/R14.17_Task_Report.md)。

port/linux/test/pikaMain-test.cpp

@@ -1,7 +1,12 @@
 #include "test_common.h"
+#include <poll.h>
+#include <signal.h>
+#include <sys/wait.h>
+#include <unistd.h>
 TEST_START
 
 extern "C" uint32_t stack_spSizeFree(Stack* stack);
+extern "C" void _stack_overflow_handler(Stack* stack, size_t stack_require);
 
 TEST(stack, size_array_capacity) {
     Stack stack = {0};
@@ -14,6 +19,63 @@ TEST(stack, size_array_capacity) {
     EXPECT_EQ(pikaMemNow(), 0);
 }
 
+TEST(stack, fatal_overflow_reports_before_stopping) {
+    int output_pipe[2] = {-1, -1};
+    ASSERT_EQ(pipe(output_pipe), 0);
+    fflush(stdout);
+
+    pid_t child = fork();
+    ASSERT_NE(child, -1);
+    if (child == 0) {
+        close(output_pipe[0]);
+        if (dup2(output_pipe[1], STDOUT_FILENO) == -1) {
+            _exit(100);
+        }
+        close(output_pipe[1]);
+
+        static char output_buffer[1024];
+        setvbuf(stdout, output_buffer, _IOFBF, sizeof(output_buffer));
+        Stack stack = {0};
+        stack.stack_totle_size = 64;
+        _stack_overflow_handler(&stack, 80);
+        _exit(101);
+    }
+
+    close(output_pipe[1]);
+    struct pollfd output = {output_pipe[0], POLLIN, 0};
+    char report[1024] = {0};
+    size_t report_size = 0;
+    for (int retry = 0; retry < 100; retry++) {
+        int poll_result = poll(&output, 1, 10);
+        if (poll_result == 1) {
+            ssize_t size =
+                read(output_pipe[0], report + report_size,
+                     sizeof(report) - report_size - 1);
+            if (size > 0) {
+                report_size += (size_t)size;
+            }
+        }
+        if (strstr(report, "execution stopped") != nullptr) {
+            break;
+        }
+    }
+    EXPECT_GT(report_size, 0);
+    EXPECT_NE(strstr(report, "FatalError: VM stack exhausted"), nullptr);
+    EXPECT_NE(strstr(report, "80/64 bytes, PIKA_STACK_BUFF_SIZE"), nullptr);
+    EXPECT_NE(strstr(report, "execution stopped"), nullptr);
+
+    int status = 0;
+    pid_t wait_result = waitpid(child, &status, WNOHANG);
+    EXPECT_EQ(wait_result, 0);
+    if (wait_result == 0) {
+        EXPECT_EQ(kill(child, SIGKILL), 0);
+        EXPECT_EQ(waitpid(child, &status, 0), child);
+        EXPECT_TRUE(WIFSIGNALED(status));
+        EXPECT_EQ(WTERMSIG(status), SIGKILL);
+    }
+    close(output_pipe[0]);
+}
+
 TEST_RUN_LINES_EXCEPT_OUTPUT(
     issue,
     issue356_top_level_function_refs,

src/PikaObj.c

@@ -1028,11 +1028,12 @@ char* methodArg_getTypeList(Arg* method_arg, char* buffs, size_t size) {
     }
     char* method_dec = methodArg_getDec(method_arg);
     pika_assert(strGetSize(method_dec) <= size);
-    if (strGetSize(method_dec) > size) {
+    if (strGetSize(method_dec) >= size) {
         pika_platform_printf(
-            "OverFlowError: please use bigger PIKA_LINE_BUFF_SIZE\r\n");
-        while (1) {
-        }
+            "FatalError: PIKA_LINE_BUFF_SIZE %u < required %u; stopped\r\n",
+            (unsigned int)size,
+            (unsigned int)(strGetSize(method_dec) + 1));
+        pika_platform_fatal_handle();
     }
     char* res = strCut(buffs, method_dec, '(', ')');
     return res;
@@ -3247,9 +3248,9 @@ PIKA_RES _do_pika_eventListener_send(PikaEventListener* self,
                                      PIKA_BOOL pickupWhenNoVM) {
     pika_assert(NULL != self);
 #if !PIKA_EVENT_ENABLE
-    pika_platform_printf("PIKA_EVENT_ENABLE is not enable");
-    while (1) {
-    };
+    pika_platform_printf("FatalError: event API requires PIKA_EVENT_ENABLE; "
+                         "stopped\r\n");
+    pika_platform_fatal_handle();
 #else
     if (NULL != eventData && !_VM_is_first_lock()) {
 #if PIKA_EVENT_THREAD_ENABLE
@@ -3346,9 +3347,9 @@ Arg* pika_eventListener_sendSignalAwaitResult(PikaEventListener* self,
      * Await result from event.
      * need implement `pika_platform_thread_delay()` to support thread switch */
 #if !PIKA_EVENT_ENABLE
-    pika_platform_printf("PIKA_EVENT_ENABLE is not enable");
-    while (1) {
-    };
+    pika_platform_printf("FatalError: event API requires PIKA_EVENT_ENABLE; "
+                         "stopped\r\n");
+    pika_platform_fatal_handle();
 #else
     extern volatile VMState g_PikaVMState;
     int tail = g_PikaVMState.cq.tail;
@@ -4509,13 +4510,9 @@ int pika_sprintf(char* buff, char* fmt, ...) {
     va_end(args);
     if (res >= PIKA_SPRINTF_BUFF_SIZE) {
         pika_platform_printf(
-            "OverflowError: sprintf buff size overflow, please use bigger "
-            "PIKA_SPRINTF_BUFF_SIZE\r\n");
-        pika_platform_printf("Info: buff size request: %d\r\n", res);
-        pika_platform_printf("Info: buff size now: %d\r\n",
-                             PIKA_SPRINTF_BUFF_SIZE);
-        while (1)
-            ;
+            "FatalError: PIKA_SPRINTF_BUFF_SIZE %d < required %d; stopped\r\n",
+            PIKA_SPRINTF_BUFF_SIZE, res + 1);
+        pika_platform_fatal_handle();
     }
     return res;
 }

src/PikaPlatform.c

@@ -243,11 +243,7 @@ PIKA_WEAK int64_t pika_platform_get_tick(void) {
 }
 
 PIKA_WEAK int pika_platform_fflush(void* stream) {
-#if PIKA_UNBUFFERED_ENABLE
     return fflush(stream);
-#else
-    return 0;
-#endif
 }
 
 PIKA_WEAK int pika_platform_putchar(char ch) {
@@ -1207,6 +1203,7 @@ PIKA_WEAK void pika_platform_error_handle() {
 }
 
 PIKA_WEAK void pika_platform_panic_handle() {
+    pika_platform_fflush(stdout);
     while (1) {
     };
 }
@@ -1228,3 +1225,10 @@ PIKA_WEAK void pika_thread_idle_hook(void) {
 }
 
 #endif
+
+void pika_platform_fatal_handle() {
+    pika_platform_fflush(stdout);
+    pika_platform_panic_handle();
+    while (1) {
+    };
+}

src/PikaPlatform.h

@@ -235,6 +235,7 @@ void pika_platform_error_handle(void);
 
 /* panic */
 void pika_platform_panic_handle(void);
+void pika_platform_fatal_handle(void);
 
 int64_t pika_platform_get_tick(void);
 

src/dataMemory.c

@@ -52,9 +52,9 @@ void* pikaMalloc(uint32_t size) {
     pika_platform_enable_irq_handle();
     if (NULL == mem) {
         pika_platform_printf(
-            "Error: No heap space! Please reset the device.\r\n");
-        while (1) {
-        }
+            "FatalError: heap exhausted (%u-byte allocation); stopped\r\n",
+            (unsigned int)size);
+        pika_platform_fatal_handle();
     }
     return mem;
 }

src/dataStack.c

@@ -30,14 +30,10 @@
 
 void _stack_overflow_handler(Stack* stack, size_t stack_require) {
     pika_platform_printf(
-        "OverflowError: pika VM stack overflow, please use bigger "
-        "PIKA_STACK_BUFF_SIZE\r\n");
-    pika_platform_printf("Info: stack size request: %d\r\n",
-                         (int)stack_require);
-    pika_platform_printf("Info: stack size now: %d\r\n",
-                         (int)stack->stack_totle_size);
-    while (1) {
-    }
+        "FatalError: VM stack exhausted (%d/%d bytes, "
+        "PIKA_STACK_BUFF_SIZE); execution stopped\r\n",
+        (int)stack_require, (int)stack->stack_totle_size);
+    pika_platform_fatal_handle();
 }
 
 uint8_t* stack_popPyload(Stack* stack, int32_t size);