Merge branch 'next'

fix(p4): execute_from_psram to fix PSRAM boot crash-loop (#31)

Claude-Session: https://claude.ai/code/session_01CDQ9ccpnsu3YtiVkvPqZtr

Author: RAR

boards/esp32p4-evboard.yaml

@@ -7,11 +7,16 @@
 # ESP32-C6/-C5 companion radio over SDIO, configured via `esp32_hosted:` below.
 # NOTE — P4 PSRAM is HEX mode only; the only valid speeds are 20 / 100 / 200 MHz.
 # Default is 200MHz, which runs fine on the Function-EV-Board and typical P4
-# modules. If YOUR specific board crash-loops at boot with
-# `esp_task_stack_is_sane_cache_disabled`, its PSRAM chip doesn't tolerate these
-# settings — drop to `speed: 100MHz` or `20MHz`, or remove the psram: block to
-# run without PSRAM. That's a per-board PSRAM/board-definition mismatch, not the
-# speed being universally wrong (see discussion #31).
+# modules.
+#
+# IMPORTANT — the P4 needs `execute_from_psram: true` (below, under
+# framework.advanced) to boot reliably with PSRAM. Without it, some P4 boards
+# crash-loop at boot with `esp_task_stack_is_sane_cache_disabled`: a
+# PSRAM-resident task stack becomes unreachable during the flash cache-disable
+# window. `execute_from_psram` maps to ESP-IDF's XIP-from-PSRAM, which keeps
+# PSRAM accessible through those windows and fixes the crash (discussion #31).
+# If a board STILL crash-loops with the flag set, drop to `speed: 100MHz` or
+# `20MHz`, or remove the psram: block to run without PSRAM.
 
 esphome:
   name: tigo-server
@@ -32,6 +37,11 @@ esp32:
       # P4's experimental-features gate. Harmless, and matches the known-good
       # TigoMonitorP4 config; some IDF/board combos want it for PSRAM.
       enable_idf_experimental_features: yes
+      # Execute code in-place from PSRAM (XIP). Required on the P4 so
+      # PSRAM-resident task stacks stay reachable during flash cache-disable
+      # windows — without it some boards crash-loop at boot with
+      # `esp_task_stack_is_sane_cache_disabled` (discussion #31).
+      execute_from_psram: true
     components:
       # esp_tsdb backs the History view; littlefs is its filesystem. The P4
       # target still needs the RAR/esp_tsdb fork (upstream 2.1.0's manifest
@@ -64,7 +74,8 @@ esp32:
       CONFIG_LWIP_MAX_LISTENING_TCP: "16"
 
 # Enable PSRAM. P4 is hex-mode only; valid speeds are 20 / 100 / 200 MHz.
-# If your board crash-loops at boot, drop to 100MHz or 20MHz, or remove this block.
+# Needs execute_from_psram: true (above) to boot reliably. If your board still
+# crash-loops at boot, drop to 100MHz or 20MHz, or remove this block.
 psram:
   mode: hex
   speed: 200MHz

boards/test-p4-tigomonitor.yaml

@@ -20,6 +20,10 @@ esp32:
     advanced:
       # P4 experimental-features gate (harmless; matches the known-good config).
       enable_idf_experimental_features: yes
+      # XIP-from-PSRAM — keeps PSRAM-resident task stacks reachable during flash
+      # cache-disable windows; without it some P4 boards crash-loop at boot with
+      # esp_task_stack_is_sane_cache_disabled (discussion #31).
+      execute_from_psram: true
     components:
       # Upstream 2.1.0 has everything we need code-wise, but its manifest still
       # lacks the esp32p4 target, so P4 stays on the RAR/esp_tsdb fork's
@@ -87,8 +91,9 @@ wifi:
 psram:
   mode: hex
   # P4 is hex-mode only; valid speeds 20 / 100 / 200 MHz. 200 works on the
-  # EV-board + typical P4 modules. If a board crash-loops at boot, drop to
-  # 100MHz/20MHz or remove this block (per-board PSRAM quirk — see #31).
+  # EV-board + typical P4 modules. Needs execute_from_psram: true (above) to
+  # boot reliably; if a board still crash-loops, drop to 100MHz/20MHz or remove
+  # this block (see #31).
   speed: 200MHz
 
 logger:

site/boards.js

@@ -232,7 +232,10 @@ font:
     flash_size: '16MB',
     partitions: { default: 'partitions/tigo-16mb.csv' },
     psram: { mode: 'hex', speed: '200MHz' },
-    frameworkAdvanced: { enable_idf_experimental_features: true },
+    // execute_from_psram (XIP) is required on the P4 so PSRAM-resident task
+    // stacks stay reachable during flash cache-disable windows — without it some
+    // boards crash-loop at boot with esp_task_stack_is_sane_cache_disabled (#31).
+    frameworkAdvanced: { enable_idf_experimental_features: true, execute_from_psram: true },
     frameworkComponents: ['joltwallet/littlefs^1.16'],
     hostedComponent: { source: 'https://github.com/RAR/esp_tsdb.git', ref: 'tigomonitor' },
     sdkconfig: {

site/lib/yaml-extract.mjs

@@ -24,9 +24,11 @@ export function extractBoardFields(text) {
   // `^\s*` anchors to line start so a commented-out `#   enable_idf_...` line
   // (an opt-in left disabled) is correctly read as NOT enabled.
   const experimental = /^\s*enable_idf_experimental_features:\s*(yes|true)\b/m.test(text);
+  // Same `^\s*` anchoring so a commented-out opt-in reads as NOT enabled.
+  const executeFromPsram = /^\s*execute_from_psram:\s*(yes|true)\b/m.test(text);
   const hasHosted = /^esp32_hosted:\s*$/m.test(text);
   const components = [...text.matchAll(/^\s*-\s*(?:name:\s*)?([A-Za-z0-9_./^-]+)\s*$/gm)]
     .map((m) => m[1])
     .filter((c) => c.includes('/'));
-  return { flash_size, partitions, psramMode, psramSpeed, experimental, hasHosted, components };
+  return { flash_size, partitions, psramMode, psramSpeed, experimental, executeFromPsram, hasHosted, components };
 }

site/test/boards.shape.test.mjs

@@ -22,6 +22,7 @@ test('P4 defines a hosted radio + 200MHz PSRAM with the experimental flag', () =
   assert.ok(p4.hosted, 'P4 must define an esp32_hosted companion');
   assert.equal(p4.psram.speed, '200MHz', 'P4 valid speeds are 20/100/200 — 200 default');
   assert.equal(p4.frameworkAdvanced.enable_idf_experimental_features, true);
+  assert.equal(p4.frameworkAdvanced.execute_from_psram, true, 'P4 needs XIP-from-PSRAM to boot (#31)');
 });
 
 test('BLE is only offered where a BLE partition exists', () => {

site/test/drift.test.mjs

@@ -23,6 +23,7 @@ for (const [id, rel] of Object.entries(FILE)) {
     assert.equal(b.psram?.mode ?? null, f.psramMode, 'psram.mode drift');
     assert.equal(b.psram?.speed ?? null, f.psramSpeed, 'psram.speed drift');
     assert.equal(b.frameworkAdvanced.enable_idf_experimental_features, f.experimental, 'experimental flag drift');
+    assert.equal(Boolean(b.frameworkAdvanced.execute_from_psram), f.executeFromPsram, 'execute_from_psram flag drift');
     assert.equal(Boolean(b.hosted), f.hasHosted, 'esp32_hosted presence drift');
   });
 }

site/test/yaml.test.mjs

@@ -27,6 +27,7 @@ test('P4 emits esp32_hosted + 200MHz PSRAM + experimental flag; no psram-less bo
   assert.ok(p4.includes('esp32_hosted:'));
   assert.ok(p4.includes('speed: 200MHz'), 'P4 default is 200MHz (valid P4 speeds: 20/100/200)');
   assert.ok(p4.includes('enable_idf_experimental_features: true'), 'P4 emits the experimental flag');
+  assert.ok(p4.includes('execute_from_psram: true'), 'P4 emits execute_from_psram (XIP) — fixes #31 boot crash');
   assert.ok(!p4.includes('80MHz'), 'P4 must not emit 80MHz — invalid for P4 (cv.one_of 20/100/200)');
   const s3lite = toYaml(assembleConfig(getBoard('esp32s3-atoms3'), { ...form, uart: { tx_pin: 'GPIO6', rx_pin: 'GPIO5' } }));
   assert.ok(!s3lite.includes('\npsram:'), 'no-PSRAM board must not emit psram');

site/yaml.js

@@ -44,9 +44,11 @@ export function toYaml(cfg) {
   L.push(`${I(1)}framework:`);
   L.push(`${I(2)}type: esp-idf`);
   L.push(`${I(2)}version: recommended`);
-  if (cfg.esp32.frameworkAdvanced.enable_idf_experimental_features) {
+  const adv = cfg.esp32.frameworkAdvanced;
+  if (adv.enable_idf_experimental_features || adv.execute_from_psram) {
     L.push(`${I(2)}advanced:`);
-    L.push(`${I(3)}enable_idf_experimental_features: true`);
+    if (adv.enable_idf_experimental_features) L.push(`${I(3)}enable_idf_experimental_features: true`);
+    if (adv.execute_from_psram) L.push(`${I(3)}execute_from_psram: true`);
   }
   const comps = [...cfg.esp32.frameworkComponents];
   if (cfg.esp32.hostedComponent || comps.length) {