[libretiny] Keep the RTL8720C frame bounds check from wrapping

The record gained the fault status and address, so its magic is now V2. The
AmebaZ2 capture and its install call are built only for the RTL8720C variant,
and a family without a capture fails the build.

esphome/components/libretiny/__init__.py

@@ -45,6 +45,7 @@ from .const import (
     FAMILY_COMPONENT,
     FAMILY_FRIENDLY,
     FAMILY_RTL8710B,
+    FAMILY_RTL8720C,
     KEY_BOARD,
     KEY_COMPONENT,
     KEY_COMPONENT_DATA,
@@ -59,6 +60,8 @@ from .const import (
 _LOGGER = logging.getLogger(__name__)
 # Fault handlers the crash handler wraps (BK7238, BK7231N)
 BK_TRAP_HANDLERS = ("bk_trap_udef", "bk_trap_pabt", "bk_trap_dabt")
+# Families with a crash handler; the RTL8720C installs it at run time (no wraps).
+CRASH_HANDLER_FAMILIES = (FAMILY_BK7231N, FAMILY_BK7238, FAMILY_RTL8720C)
 
 CODEOWNERS = ["@kuba2k2"]
 AUTO_LOAD = ["preferences"]
@@ -554,10 +557,11 @@ async def component_to_code(config):
     # RAM-executable output section and prints a post-link placement summary.
     if FAMILY_COMPONENT[config[CONF_FAMILY]] != COMPONENT_BK72XX:
         cg.add_platformio_option("extra_scripts", ["pre:patch_linker.py"])
-    if config[CONF_FAMILY] in (FAMILY_BK7231N, FAMILY_BK7238):
-        # Crash handler (crash_handler.cpp, patch_noinit.py.script)
+    if config[CONF_FAMILY] in CRASH_HANDLER_FAMILIES:
+        # Crash handler (crash_handler.cpp)
         cg.add_define("USE_LIBRETINY_CRASH_HANDLER")
         cg.add_define("USE_CRASH_HANDLER")
+    if config[CONF_FAMILY] in (FAMILY_BK7231N, FAMILY_BK7238):
         for trap in BK_TRAP_HANDLERS:
             cg.add_build_flag(f"-Wl,--wrap={trap}")
         cg.add_platformio_option("extra_scripts", ["pre:patch_noinit.py"])

esphome/components/libretiny/crash_handler.cpp

@@ -1,8 +1,12 @@
-#ifdef USE_BK72XX
+#ifdef USE_LIBRETINY
 
 #include "esphome/core/defines.h"
 #ifdef USE_LIBRETINY_CRASH_HANDLER
 
+#if !defined(USE_BK72XX) && !defined(USE_LIBRETINY_VARIANT_RTL8720C)
+#error "The LibreTiny crash handler has no fault capture for this chip family"
+#endif
+
 #include "crash_handler.h"
 #include "core.h"
 #include "esphome/core/log.h"
@@ -13,6 +17,7 @@
 #include <cstdint>
 #include <cstdio>
 
+#ifdef USE_BK72XX
 extern "C" {
 #include <arm_mcu_pub.h>  // MCU_REG_BACKUP_SP_*
 #include <intc.h>         // struct arm_registers
@@ -39,28 +44,138 @@ extern char _itcmcode_ram_begin[];
 extern char _itcmcode_ram_end[];
 }
 // NOLINTEND(bugprone-reserved-identifier,cert-dcl37-c,cert-dcl51-cpp,readability-identifier-naming)
+#endif  // USE_BK72XX
+
+#ifdef USE_LIBRETINY_VARIANT_RTL8720C
+// NOLINTBEGIN(bugprone-reserved-identifier,cert-dcl37-c,cert-dcl51-cpp,readability-identifier-naming)
+extern "C" {
+// Bounds of the code in flash (XIP) and in RAM (linker symbols, rtl8710c_ram.ld).
+extern char __xip_code_text_start__[];
+extern char __xip_code_text_end__[];
+extern char __ram_entry_text_start__[];
+extern char __ram_code_text_end__[];
+}
+// NOLINTEND(bugprone-reserved-identifier,cert-dcl37-c,cert-dcl51-cpp,readability-identifier-naming)
+#endif  // USE_LIBRETINY_VARIANT_RTL8720C
 
 namespace esphome::libretiny {
 
 ESPHOME_LOG_TAG(TAG, "libretiny.crash");
 
 // 0xDEAD sentinel, then the record layout version.
-static constexpr uint32_t CRASH_MAGIC_V1 = 0xDEAD0001;
+static constexpr uint32_t CRASH_MAGIC_V2 = 0xDEAD0002;
 
+// BK72xx: the ARM9 exception taken.
 static constexpr uint32_t CRASH_REASON_UNDEFINED = 1;
 static constexpr uint32_t CRASH_REASON_PREFETCH_ABORT = 2;
 static constexpr uint32_t CRASH_REASON_DATA_ABORT = 3;
-PROGMEM_STRING_TABLE(CrashReasonStrings, "Unknown", "Undefined instruction", "Prefetch abort", "Data abort");
+// RTL8720C: the Cortex-M exception number (3 to 7) plus this offset.
+static constexpr uint32_t CRASH_REASON_CORTEX_M_OFFSET = 1;
+PROGMEM_STRING_TABLE(CrashReasonStrings, "Unknown", "Undefined instruction", "Prefetch abort", "Data abort",
+                     "Hard fault", "MemManage fault", "Bus fault", "Usage fault", "Secure fault");
+
+static constexpr size_t MAX_BACKTRACE = 8;
+// Words scanned above sp for return addresses.
+static constexpr size_t STACK_SCAN_WORDS = 64;
+
+struct CrashRecord {
+  uint32_t magic;
+  uint32_t reason;
+  uint32_t pc;
+  uint32_t lr;
+  uint32_t sp;
+  uint32_t fault_status;   // Cortex-M CFSR, 0 on BK72xx
+  uint32_t fault_address;  // Cortex-M BFAR or MMFAR when valid, else 0
+  uint32_t backtrace[MAX_BACKTRACE];
+};
+
+#ifdef USE_BK72XX
+// Kept in ITCM, see patch_noinit.py.script.
+#define CRASH_RECORD_SECTION ".noinit"
+#else
+// rtl8710c_ram.ld keeps .ram.bss.noinit* out of the startup zeroing.
+#define CRASH_RECORD_SECTION ".ram.bss.noinit.esphome_crash"
+#endif
+// NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)
+__attribute__((section(CRASH_RECORD_SECTION))) static CrashRecord s_record;
+
+static bool s_record_read = false;   // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
+static bool s_record_valid = false;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
+
+bool crash_handler_has_data() {
+  if (!s_record_read) {
+    s_record_read = true;
+    s_record_valid = s_record.magic == CRASH_MAGIC_V2;
+    // Clear the magic so the record is reported once.
+    s_record.magic = 0;
+  }
+  return s_record_valid;
+}
+
+// One ESP_LOGE per line: the CLI decodes per line and partial output still shows.
+void crash_handler_log() {
+  if (!crash_handler_has_data())
+    return;
+
+  ESP_LOGE(TAG, "*** CRASH DETECTED ON PREVIOUS BOOT ***");
+  ESP_LOGE(TAG, "  Reason: %s", LOG_STR_ARG(CrashReasonStrings::get_log_str(s_record.reason, 0)));
+  if (s_record.fault_status != 0) {
+    ESP_LOGE(TAG, "  CFSR: 0x%08" PRIX32 "  Address: 0x%08" PRIX32, s_record.fault_status, s_record.fault_address);
+  }
+  ESP_LOGE(TAG, "  PC:  0x%08" PRIX32 "  (fault location)", s_record.pc);
+  ESP_LOGE(TAG, "  LR:  0x%08" PRIX32 "  (return address)", s_record.lr);
+  ESP_LOGE(TAG, "  SP:  0x%08" PRIX32, s_record.sp);
+  uint8_t count = 0;
+  for (; count < MAX_BACKTRACE && s_record.backtrace[count] != 0; count++) {
+    ESP_LOGE(TAG, "  BT%d: 0x%08" PRIX32 "  (stack backtrace)", count, s_record.backtrace[count]);
+  }
+  // addr2line hint with every address
+  char hint[160];
+  int pos = snprintf(hint, sizeof(hint), "Use: addr2line -pfiaC -e raw_firmware.elf 0x%08" PRIX32 " 0x%08" PRIX32,
+                     s_record.pc, s_record.lr);
+  for (uint8_t i = 0; i < count && pos < (int) sizeof(hint) - 12; i++) {
+    pos += snprintf(hint + pos, sizeof(hint) - pos, " 0x%08" PRIX32, s_record.backtrace[i]);
+  }
+  ESP_LOGE(TAG, "%s", hint);
+}
+
+// --- Crash time: exception mode, a few dozen bytes of stack: no printing, no large locals.
+
+static inline bool is_code_addr(uint32_t val) {
+  uint32_t addr = val & ~1u;  // clear the Thumb bit of a return address
+#ifdef USE_BK72XX
+  return (addr >= (uint32_t) _vector_start && addr < (uint32_t) _data_flash_begin) ||
+         (addr >= (uint32_t) _itcmcode_ram_begin && addr < (uint32_t) _itcmcode_ram_end);
+#else
+  return (addr >= (uint32_t) __xip_code_text_start__ && addr < (uint32_t) __xip_code_text_end__) ||
+         (addr >= (uint32_t) __ram_entry_text_start__ && addr < (uint32_t) __ram_code_text_end__);
+#endif
+}
+
+// Return addresses above sp give the backtrace; then the magic marks the record complete.
+static void finish_record(uint32_t sp, uint32_t sram_start, uint32_t sram_end) {
+  uint32_t count = 0;
+  if (sp >= sram_start && sp < sram_end && (sp & 3) == 0) {
+    auto *scan = (const uint32_t *) sp;       // NOLINT(performance-no-int-to-ptr)
+    auto *end = (const uint32_t *) sram_end;  // NOLINT(performance-no-int-to-ptr)
+    for (size_t i = 0; i < STACK_SCAN_WORDS && scan < end && count < MAX_BACKTRACE; i++, scan++) {
+      uint32_t val = *scan;
+      if (is_code_addr(val) && val != s_record.lr && (val & ~1u) != s_record.pc)
+        s_record.backtrace[count++] = val;
+    }
+  }
+  if (count < MAX_BACKTRACE)
+    s_record.backtrace[count] = 0;  // terminator, the reader stops at the first 0
+  s_record.magic = CRASH_MAGIC_V2;
+}
+
+#ifdef USE_BK72XX
 
 // With Wi-Fi up the boot-time watchdog no longer fires: any interrupts-off spin hangs until power is
 // cycled (BK7238 and BK7231N; cause not in the open SDK). Re-armed here, long enough for the SDK's
 // register dump when sdk_silent is off.
 static constexpr uint32_t CRASH_REBOOT_WDT_MS = 500;
 
-static constexpr size_t MAX_BACKTRACE = 8;
-// Words scanned above sp for return addresses.
-static constexpr size_t STACK_SCAN_WORDS = 64;
-
 // SRAM: 192 KB on the BK7231N, 256 KB on the BK7238.
 static constexpr uint32_t SRAM_START = 0x00400000;
 #ifdef USE_LIBRETINY_VARIANT_BK7231N
@@ -79,65 +194,6 @@ static constexpr uint32_t CPSR_MODE_UND = 0x1B;
 static constexpr uint32_t CPSR_MODE_SYS = 0x1F;
 static constexpr uint32_t CPSR_THUMB = 1u << 5;
 
-struct CrashRecord {
-  uint32_t magic;
-  uint32_t reason;
-  uint32_t pc;
-  uint32_t lr;
-  uint32_t sp;
-  uint32_t backtrace[MAX_BACKTRACE];
-};
-
-// Kept in ITCM, see patch_noinit.py.script.
-// NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)
-__attribute__((section(".noinit"))) static CrashRecord s_record;
-
-static bool s_record_read = false;   // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
-static bool s_record_valid = false;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
-
-bool crash_handler_has_data() {
-  if (!s_record_read) {
-    s_record_read = true;
-    s_record_valid = s_record.magic == CRASH_MAGIC_V1;
-    // Clear the magic so the record is reported once.
-    s_record.magic = 0;
-  }
-  return s_record_valid;
-}
-
-// One ESP_LOGE per line: the CLI decodes per line and partial output still shows.
-void crash_handler_log() {
-  if (!crash_handler_has_data())
-    return;
-
-  ESP_LOGE(TAG, "*** CRASH DETECTED ON PREVIOUS BOOT ***");
-  ESP_LOGE(TAG, "  Reason: %s", LOG_STR_ARG(CrashReasonStrings::get_log_str(s_record.reason, 0)));
-  ESP_LOGE(TAG, "  PC:  0x%08" PRIX32 "  (fault location)", s_record.pc);
-  ESP_LOGE(TAG, "  LR:  0x%08" PRIX32 "  (return address)", s_record.lr);
-  ESP_LOGE(TAG, "  SP:  0x%08" PRIX32, s_record.sp);
-  uint8_t count = 0;
-  for (; count < MAX_BACKTRACE && s_record.backtrace[count] != 0; count++) {
-    ESP_LOGE(TAG, "  BT%d: 0x%08" PRIX32 "  (stack backtrace)", count, s_record.backtrace[count]);
-  }
-  // addr2line hint with every address
-  char hint[160];
-  int pos = snprintf(hint, sizeof(hint), "Use: addr2line -pfiaC -e raw_firmware.elf 0x%08" PRIX32 " 0x%08" PRIX32,
-                     s_record.pc, s_record.lr);
-  for (uint8_t i = 0; i < count && pos < (int) sizeof(hint) - 12; i++) {
-    pos += snprintf(hint + pos, sizeof(hint) - pos, " 0x%08" PRIX32, s_record.backtrace[i]);
-  }
-  ESP_LOGE(TAG, "%s", hint);
-}
-
-// --- Crash time: exception mode, interrupts masked, a few dozen bytes of stack: no printing, no
-// large locals.
-
-static inline bool is_code_addr(uint32_t val) {
-  uint32_t addr = val & ~1u;  // clear the Thumb bit of a return address
-  return (addr >= (uint32_t) _vector_start && addr < (uint32_t) _data_flash_begin) ||
-         (addr >= (uint32_t) _itcmcode_ram_begin && addr < (uint32_t) _itcmcode_ram_end);
-}
-
 // PUSH_ALL_ARM_REG (boot_handlers.S) saves every mode's registers at the arm_mcu_pub.h addresses
 // before bk_trap_*; lr (r14) follows sp (r13).
 struct SavedBank {
@@ -174,21 +230,9 @@ static void record_crash(arm_registers *regs, uint32_t reason, uint32_t pc_offse
   s_record.pc = regs->pc - pc_offset;
   s_record.lr = lr;
   s_record.sp = sp;
-
-  // Return addresses above sp give the backtrace.
-  uint32_t count = 0;
-  if (sp >= SRAM_START && sp < SRAM_END && (sp & 3) == 0) {
-    auto *scan = (const uint32_t *) sp;       // NOLINT(performance-no-int-to-ptr)
-    auto *end = (const uint32_t *) SRAM_END;  // NOLINT(performance-no-int-to-ptr)
-    for (size_t i = 0; i < STACK_SCAN_WORDS && scan < end && count < MAX_BACKTRACE; i++, scan++) {
-      uint32_t val = *scan;
-      if (is_code_addr(val) && val != lr && (val & ~1u) != s_record.pc)
-        s_record.backtrace[count++] = val;
-    }
-  }
-  if (count < MAX_BACKTRACE)
-    s_record.backtrace[count] = 0;  // terminator, the reader stops at the first 0
-  s_record.magic = CRASH_MAGIC_V1;
+  s_record.fault_status = 0;
+  s_record.fault_address = 0;
+  finish_record(sp, SRAM_START, SRAM_END);
 
   lt_wdt_enable(CRASH_REBOOT_WDT_MS);
 }
@@ -211,7 +255,106 @@ extern "C" void __wrap_bk_trap_dabt(arm_registers *regs) {
 }
 // NOLINTEND(bugprone-reserved-identifier,cert-dcl37-c,cert-dcl51-cpp,readability-identifier-naming)
 
+#endif  // USE_BK72XX
+
+#ifdef USE_LIBRETINY_VARIANT_RTL8720C
+
+// The SDK points the fault vectors (3 HardFault to 7 SecureFault) of its RAM vector table (VTOR) at a
+// ROM handler that prints a register dump and then spins. crash_handler_install() puts
+// esphome_fault_entry() in front of it, as the SDK's own CONFIG_MIIO patch (app_start.c) does.
+static_assert(LT_HW_WATCHDOG, "the crash reboot relies on the hardware watchdog");
+// The ROM dump takes about 0.4 s at 115200 baud; without the re-arm the reset waits for the 10 s
+// watchdog from arch_init().
+static constexpr uint32_t CRASH_REBOOT_WDT_MS = 1000;
+static constexpr uint32_t FIRST_FAULT_VECTOR = 3;
+static constexpr uint32_t FAULT_VECTOR_COUNT = 5;
+
+// Architectural System Control Block registers (ARMv8-M).
+static constexpr uintptr_t SCB_VTOR = 0xE000ED08;
+static constexpr uintptr_t SCB_CFSR = 0xE000ED28;
+static constexpr uintptr_t SCB_MMFAR = 0xE000ED34;
+static constexpr uintptr_t SCB_BFAR = 0xE000ED38;
+static constexpr uint32_t CFSR_MMARVALID = 1u << 7;
+static constexpr uint32_t CFSR_BFARVALID = 1u << 15;
+
+// DTCM, where the app's stacks and heap live (rtl8710c_ram.ld).
+static constexpr uint32_t SRAM_START = 0x10000000;
+static constexpr uint32_t SRAM_END = 0x1003FA00;
+
+// Exception frame: r0-r3, r12, lr, pc, xPSR (the RTL8720C has no FPU, so never the extended frame).
+static constexpr uint32_t FRAME_LR = 5;
+static constexpr uint32_t FRAME_PC = 6;
+static constexpr uint32_t FRAME_XPSR = 7;
+static constexpr uint32_t FRAME_WORDS = 8;
+static constexpr uint32_t XPSR_STACK_ALIGNED = 1u << 9;
+
+// The ROM handlers fault_entry() continues into, by vector.
+static uint32_t s_rom_fault_vectors[FAULT_VECTOR_COUNT];  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
+
+static inline uint32_t read_reg(uintptr_t addr) {
+  return *(const volatile uint32_t *) addr;  // NOLINT(performance-no-int-to-ptr)
+}
+
+// Returns the ROM handler to continue into. pc, lr and sp stay 0 when the frame is outside DTCM.
+extern "C" __attribute__((used)) uint32_t esphome_record_fault(const uint32_t *frame, uint32_t vector) {
+  uint32_t cfsr = read_reg(SCB_CFSR);
+  uint32_t address = 0;
+  if (cfsr & CFSR_BFARVALID) {
+    address = read_reg(SCB_BFAR);
+  } else if (cfsr & CFSR_MMARVALID) {
+    address = read_reg(SCB_MMFAR);
+  }
+  s_record.reason = vector + CRASH_REASON_CORTEX_M_OFFSET;
+  s_record.fault_status = cfsr;
+  s_record.fault_address = address;
+
+  auto frame_addr = (uint32_t) frame;
+  uint32_t sp = 0;
+  if (frame_addr >= SRAM_START && frame_addr <= SRAM_END - FRAME_WORDS * 4 && (frame_addr & 3) == 0) {
+    s_record.pc = frame[FRAME_PC];
+    s_record.lr = frame[FRAME_LR];
+    sp = frame_addr + FRAME_WORDS * 4 + ((frame[FRAME_XPSR] & XPSR_STACK_ALIGNED) ? 4 : 0);
+  } else {
+    s_record.pc = 0;
+    s_record.lr = 0;
+  }
+  s_record.sp = sp;
+  finish_record(sp, SRAM_START, SRAM_END);
+
+  lt_wdt_enable(CRASH_REBOOT_WDT_MS);
+  return s_rom_fault_vectors[vector - FIRST_FAULT_VECTOR];
+}
+
+// Fault vector: calls esphome_record_fault(frame, exception number), then jumps to the ROM handler it returns
+// with r0-r3 and lr restored. Asm because C would push onto MSP before the frame is found, and the ROM handler
+// reads EXC_RETURN from lr.
+extern "C" __attribute__((naked, used)) void esphome_fault_entry() {
+  __asm volatile("push {r0-r3, r4, lr}  \n"  // r4 only keeps the stack 8-byte aligned
+                 "tst  lr, #4           \n"
+                 "ite  eq               \n"
+                 "mrseq r0, msp         \n"
+                 "mrsne r0, psp         \n"
+                 "it   eq               \n"
+                 "addeq r0, r0, #24     \n"  // MSP: skip the six words pushed above
+                 "mrs  r1, ipsr         \n"
+                 "ubfx r1, r1, #0, #9   \n"  // exception number, 3 to 7
+                 "bl   esphome_record_fault \n"
+                 "mov  r12, r0          \n"  // ROM handler address
+                 "pop  {r0-r3, r4, lr}  \n"
+                 "bx   r12              \n");
+}
+
+void crash_handler_install() {
+  auto *vectors = (uint32_t *) read_reg(SCB_VTOR);  // NOLINT(performance-no-int-to-ptr)
+  for (uint32_t i = 0; i < FAULT_VECTOR_COUNT; i++) {
+    s_rom_fault_vectors[i] = vectors[FIRST_FAULT_VECTOR + i];
+    vectors[FIRST_FAULT_VECTOR + i] = (uint32_t) &esphome_fault_entry;
+  }
+}
+
+#endif  // USE_LIBRETINY_VARIANT_RTL8720C
+
 }  // namespace esphome::libretiny
 
 #endif  // USE_LIBRETINY_CRASH_HANDLER
-#endif  // USE_BK72XX
+#endif  // USE_LIBRETINY

esphome/components/libretiny/crash_handler.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#ifdef USE_BK72XX
+#ifdef USE_LIBRETINY
 
 #include "esphome/core/defines.h"
 
@@ -14,7 +14,12 @@ void crash_handler_log();
 /// Returns true if crash data was found this boot, reading it first if needed.
 bool crash_handler_has_data();
 
+#ifdef USE_LIBRETINY_VARIANT_RTL8720C
+/// Put the crash recorder in front of the SDK's fault handlers.
+void crash_handler_install();
+#endif
+
 }  // namespace esphome::libretiny
 
 #endif  // USE_LIBRETINY_CRASH_HANDLER
-#endif  // USE_BK72XX
+#endif  // USE_LIBRETINY

esphome/components/libretiny/generate_components.py

@@ -156,6 +156,7 @@ COMPONENT_CODEOWNERS = {
 # Extra imports per component; the CLI looks up process_stacktrace on the platform package.
 COMPONENT_EXTRA_IMPORTS = {
     "bk72xx": "from esphome.stacktrace import process_crash_handler_line as process_stacktrace  # noqa: F401",
+    "rtl87xx": "from esphome.stacktrace import process_crash_handler_line as process_stacktrace  # noqa: F401",
 }
 
 

esphome/components/libretiny/hal.cpp

@@ -1,6 +1,7 @@
 #ifdef USE_LIBRETINY
 
 #include "core.h"
+#include "crash_handler.h"
 #include "esphome/core/hal.h"
 #include "preferences.h"
 
@@ -27,6 +28,9 @@ namespace esphome {
 void arch_init() {
   libretiny::setup_preferences();
   lt_wdt_enable(10000L);
+#if defined(USE_LIBRETINY_CRASH_HANDLER) && defined(USE_LIBRETINY_VARIANT_RTL8720C)
+  libretiny::crash_handler_install();
+#endif
 #ifdef USE_BK72XX
   // BK72xx SDK creates the main Arduino task at priority 3, which is lower than
   // all WiFi (4-5), LwIP (4), and TCP/IP (7) tasks. This causes ~100ms loop

esphome/components/rtl87xx/__init__.py

@@ -29,6 +29,7 @@ from esphome.components.libretiny.const import (
 )
 from esphome.core import CORE
 from esphome.cpp_generator import MockObj
+from esphome.stacktrace import process_crash_handler_line as process_stacktrace  # noqa: F401
 from esphome.types import ConfigType
 
 from .boards import RTL87XX_BOARD_PINS, RTL87XX_BOARDS

esphome/core/defines.h

@@ -774,7 +774,7 @@
 #endif
 
 #ifdef USE_LIBRETINY
-#ifdef USE_BK72XX
+#if defined(USE_BK72XX) || defined(USE_LIBRETINY_VARIANT_RTL8720C)
 #define USE_LIBRETINY_CRASH_HANDLER
 #endif
 #define USE_BK72XX_BLE

esphome/platform_hooks.py

@@ -67,6 +67,7 @@ STACKTRACE_GATES: Final[dict[str, str]] = {
     ),
     PLATFORM_RP2: _CRASH_HANDLER_GATE,
     PLATFORM_BK72XX: _CRASH_HANDLER_GATE,
+    PLATFORM_RTL87XX: _CRASH_HANDLER_GATE,
     PLATFORM_NRF52: r"0x[0-9a-fA-F]{3,}\b|Last crash:",
 }
 

esphome/stacktrace.py

@@ -152,7 +152,7 @@ def _addr2line(tool: str, elf: Path, addr: str) -> str:
 def process_crash_handler_line(
     config: ConfigType, line: str, backtrace_state: bool
 ) -> bool:
-    """Decode a crash handler report with addr2line; the process_stacktrace hook of rp2 and bk72xx."""
+    """Decode a crash handler report with addr2line; the process_stacktrace hook of rp2, bk72xx and rtl87xx."""
     if CRASH_HANDLER_RE.search(line):
         _LOGGER.error("Crash detected - decoding addresses")
         return True

script/split_components_for_ci.py

@@ -57,6 +57,7 @@ PLATFORM_BUILD_SECONDS = {
     "esp32-idf": 55,
     "esp32-p4-idf": 55,
     "ln882x-ard": 55,
+    "rtl8720c-ard": 55,
     "esp32-s3-idf": 60,
     "bk72xx-ard": 70,
     "bk7238-ard": 70,

tests/component_tests/libretiny/config/rtl8710b.yaml

@@ -0,0 +1,5 @@
+esphome:
+  name: test
+
+rtl87xx:
+  board: generic-rtl8710bn-2mb-788k

tests/component_tests/libretiny/config/rtl8720c.yaml

@@ -0,0 +1,5 @@
+esphome:
+  name: test
+
+rtl87xx:
+  board: bw15

tests/component_tests/libretiny/test_crash_handler.py

@@ -1,4 +1,4 @@
-"""Only BK7238 and BK7231N, the BK chips with an ITCM linker region, get the crash handler."""
+"""The crash handler is built for BK7238, BK7231N (both with an ITCM linker region) and RTL8720C."""
 
 from __future__ import annotations
 
@@ -12,12 +12,14 @@ from esphome.core import CORE
 
 
 @pytest.mark.parametrize(
-    ("config", "enabled"),
+    ("config", "enabled", "bk_hooks"),
     [
-        ("bk7238.yaml", True),
-        ("bk72xx.yaml", True),  # BK7231N
-        ("bk7231t.yaml", False),
-        ("ln882x.yaml", False),
+        ("bk7238.yaml", True, True),
+        ("bk72xx.yaml", True, True),  # BK7231N
+        ("bk7231t.yaml", False, False),
+        ("rtl8720c.yaml", True, False),  # installed at run time
+        ("rtl8710b.yaml", False, False),
+        ("ln882x.yaml", False, False),
     ],
 )
 def test_crash_handler_family_gate(
@@ -25,13 +27,14 @@ def test_crash_handler_family_gate(
     component_config_path: Callable[[str], Path],
     config: str,
     enabled: bool,
+    bk_hooks: bool,
 ) -> None:
     generate_main(component_config_path(config))
     defines = {define.name for define in CORE.defines}
     assert ("USE_LIBRETINY_CRASH_HANDLER" in defines) is enabled
     assert ("USE_CRASH_HANDLER" in defines) is enabled
     for trap in BK_TRAP_HANDLERS:
-        assert (f"-Wl,--wrap={trap}" in CORE.build_flags) is enabled
+        assert (f"-Wl,--wrap={trap}" in CORE.build_flags) is bk_hooks
     assert (
         "pre:patch_noinit.py" in CORE.platformio_options["extra_scripts"]
-    ) is enabled
+    ) is bk_hooks

tests/components/libretiny/test.rtl8720c-ard.yaml

@@ -0,0 +1,13 @@
+logger:
+  level: VERBOSE
+
+esphome:
+  on_boot:
+    - lambda: |-
+        int x = 100;
+        x = clamp(x, 50, 90);
+        assert(x == 90);
+        x = clamp_at_least(x, 95);
+        assert(x == 95);
+        x = clamp_at_most(x, 40);
+        assert(x == 40);

tests/test_build_components/build_components_base.rtl8720c-ard.yaml

@@ -0,0 +1,15 @@
+esphome:
+  name: componenttestesprtl8720c
+  friendly_name: $component_name
+
+rtl87xx:
+  board: bw15
+
+logger:
+  level: VERY_VERBOSE
+
+packages:
+  component_under_test: !include
+    file: $component_test_file
+    vars:
+      component_test_file: $component_test_file

tests/unit_tests/test_main.py

@@ -117,9 +117,9 @@ from esphome.const import (
     PLATFORM_ESP32,
     PLATFORM_ESP8266,
     PLATFORM_HOST,
+    PLATFORM_LN882X,
     PLATFORM_NRF52,
     PLATFORM_RP2,
-    PLATFORM_RTL87XX,
     ErrorFormat,
     Toolchain,
 )
@@ -6304,7 +6304,7 @@ def test_run_miniterm_no_stacktrace_analyzer(
     """Platforms without a stacktrace analyzer log an info and stream anyway."""
     mock_serial = MockSerial([b"[I][app:100]: Line 1\r\n", MOCK_SERIAL_END])
 
-    CORE.data[KEY_CORE] = {KEY_TARGET_PLATFORM: PLATFORM_RTL87XX}
+    CORE.data[KEY_CORE] = {KEY_TARGET_PLATFORM: PLATFORM_LN882X}
     config = {
         CONF_LOGGER: {
             CONF_BAUD_RATE: 115200,

tests/unit_tests/test_platform_hooks.py

@@ -15,7 +15,7 @@ from unittest.mock import Mock
 import pytest
 
 from esphome import platform_hooks
-from esphome.const import PLATFORM_ESP32, PLATFORM_RTL87XX, Platform
+from esphome.const import PLATFORM_ESP32, PLATFORM_LN882X, Platform
 
 
 def test_no_unregistered_platform_exposes_a_hook() -> None:
@@ -165,7 +165,7 @@ def test_get_stacktrace_handler_reports_missing_analyzer(
     caplog: pytest.LogCaptureFixture,
 ) -> None:
     caplog.set_level("INFO", logger="esphome.platform_hooks")
-    assert platform_hooks.get_stacktrace_handler(PLATFORM_RTL87XX) is None
+    assert platform_hooks.get_stacktrace_handler(PLATFORM_LN882X) is None
     assert "no compatible analyzer" in caplog.text
     # A capability gap is ordinary; it must not warn.
     assert not any(r.levelno >= logging.WARNING for r in caplog.records)

tests/unit_tests/test_stacktrace.py

@@ -18,6 +18,7 @@ from esphome.const import (
     PLATFORM_BK72XX,
     PLATFORM_ESP32,
     PLATFORM_ESP8266,
+    PLATFORM_LN882X,
     PLATFORM_NRF52,
     PLATFORM_RP2,
     PLATFORM_RTL87XX,
@@ -66,6 +67,10 @@ CRASH_SAMPLES: dict[str, dict[str, list[str]]] = {
         "state_markers": ["CRASH DETECTED ON PREVIOUS BOOT"],
         "addresses": ["PC:  0x0001614A  (fault location)"],
     },
+    PLATFORM_RTL87XX: {
+        "state_markers": ["CRASH DETECTED ON PREVIOUS BOOT"],
+        "addresses": ["PC:  0x9B0073A4  (fault location)"],
+    },
     PLATFORM_NRF52: {
         "state_markers": ["Last crash:"],
         "addresses": [
@@ -231,6 +236,7 @@ DECODER_PATTERNS: dict[str, list[str]] = {
     ],
     PLATFORM_RP2: ["CRASH_HANDLER_RE", "CRASH_HANDLER_ADDR_RE"],
     PLATFORM_BK72XX: ["CRASH_HANDLER_RE", "CRASH_HANDLER_ADDR_RE"],
+    PLATFORM_RTL87XX: ["CRASH_HANDLER_RE", "CRASH_HANDLER_ADDR_RE"],
     PLATFORM_NRF52: ["STACKTRACE_NRF52_PC_LR_RE"],
 }
 
@@ -548,7 +554,7 @@ def test_processor_registry_miss_disables_at_construction(
     caplog.set_level("INFO", logger="esphome.platform_hooks")
 
     with patch.object(stacktrace.platform_hooks, "import_module") as mock_import:
-        processor = stacktrace.LogLineProcessor(CONFIG, PLATFORM_RTL87XX)
+        processor = stacktrace.LogLineProcessor(CONFIG, PLATFORM_LN882X)
         processor.process_line("PC: 0x40104960")
 
     mock_import.assert_not_called()