Merge branch 'dev' into rtl87xx-crash-handler

Put a recorder in front of the AmebaZ2 ROM fault handlers (vectors 3 to 7 of
the RAM vector table). It saves PC, LR, SP, CFSR, the fault address and a
stack scan into .ram.bss.noinit, re-arms the watchdog for a 1 s reset (the
ROM handler spins after its dump) and continues into the ROM handler.
The next boot logs the record and the CLI decodes it, as on BK72xx.

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,4 +1,4 @@
-#ifdef USE_BK72XX
+#ifdef USE_LIBRETINY
 
 #include "esphome/core/defines.h"
 #ifdef USE_LIBRETINY_CRASH_HANDLER
@@ -13,6 +13,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,6 +40,19 @@ 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_RTL87XX
+// 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_RTL87XX
 
 namespace esphome::libretiny {
 
@@ -47,50 +61,39 @@ ESPHOME_LOG_TAG(TAG, "libretiny.crash");
 // 0xDEAD sentinel, then the record layout version.
 static constexpr uint32_t CRASH_MAGIC_V1 = 0xDEAD0001;
 
+// 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");
-
-// 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;
+// RTL87xx: 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;
 
-// SRAM: 192 KB on the BK7231N, 256 KB on the BK7238.
-static constexpr uint32_t SRAM_START = 0x00400000;
-#ifdef USE_LIBRETINY_VARIANT_BK7231N
-static constexpr uint32_t SRAM_END = 0x00430000;
-#else
-static constexpr uint32_t SRAM_END = 0x00440000;
-#endif
-
-static constexpr uint32_t CPSR_MODE_MASK = 0x1F;
-static constexpr uint32_t CPSR_MODE_USR = 0x10;
-static constexpr uint32_t CPSR_MODE_FIQ = 0x11;
-static constexpr uint32_t CPSR_MODE_IRQ = 0x12;
-static constexpr uint32_t CPSR_MODE_SVC = 0x13;
-static constexpr uint32_t CPSR_MODE_ABT = 0x17;
-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 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(".noinit"))) static CrashRecord s_record;
+__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)
@@ -112,6 +115,9 @@ void crash_handler_log() {
 
   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);
@@ -129,15 +135,61 @@ void crash_handler_log() {
   ESP_LOGE(TAG, "%s", hint);
 }
 
-// --- Crash time: exception mode, interrupts masked, a few dozen bytes of stack: no printing, no
-// large locals.
+// --- 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_V1;
+}
+
+#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;
+
+// SRAM: 192 KB on the BK7231N, 256 KB on the BK7238.
+static constexpr uint32_t SRAM_START = 0x00400000;
+#ifdef USE_LIBRETINY_VARIANT_BK7231N
+static constexpr uint32_t SRAM_END = 0x00430000;
+#else
+static constexpr uint32_t SRAM_END = 0x00440000;
+#endif
+
+static constexpr uint32_t CPSR_MODE_MASK = 0x1F;
+static constexpr uint32_t CPSR_MODE_USR = 0x10;
+static constexpr uint32_t CPSR_MODE_FIQ = 0x11;
+static constexpr uint32_t CPSR_MODE_IRQ = 0x12;
+static constexpr uint32_t CPSR_MODE_SVC = 0x13;
+static constexpr uint32_t CPSR_MODE_ABT = 0x17;
+static constexpr uint32_t CPSR_MODE_UND = 0x1B;
+static constexpr uint32_t CPSR_MODE_SYS = 0x1F;
+static constexpr uint32_t CPSR_THUMB = 1u << 5;
+
 // 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 +226,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 +251,105 @@ 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_RTL87XX
+
+// 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 + FRAME_WORDS * 4 <= SRAM_END && (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];
+}
+
+// Passes the faulting stack's frame and the vector number to esphome_record_fault, then
+// branches to the ROM handler with r0-r3 and lr as they were on entry.
+extern "C" __attribute__((naked, used)) void esphome_fault_entry() {
+  __asm volatile("push {r0-r3, r4, lr}  \n"
+                 "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"
+                 "bl   esphome_record_fault \n"
+                 "mov  r12, r0          \n"
+                 "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_RTL87XX
+
 }  // 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_RTL87XX
+/// 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

@@ -152,6 +152,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_RTL87XX)
+  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_RTL87XX)
 #define USE_LIBRETINY_CRASH_HANDLER
 #endif
 #define USE_BK72XX_BLE

esphome/platform_hooks.py

@@ -28,6 +28,7 @@ from esphome.const import (
     PLATFORM_ESP8266,
     PLATFORM_NRF52,
     PLATFORM_RP2,
+    PLATFORM_RTL87XX,
     Platform,
 )
 
@@ -64,6 +65,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,
 )
@@ -6192,7 +6192,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()