[esp8266] Add linker-script surgery and board build metadata for the native toolchain (#18555)

tests/unit_tests/components/esp8266/test_boards.py

@@ -0,0 +1,33 @@
+"""Tests for the per-board linker-script rule."""
+
+import pytest
+
+from esphome.components.esp8266 import _choose_ld_script
+from esphome.components.esp8266.boards import BOARDS, board_ld_script
+import esphome.config_validation as cv
+from esphome.core import EsphomeError
+
+
+def test_d1_wroom_02_keeps_its_shipped_layout() -> None:
+    """The override must survive a BOARDS regeneration or key typo: the
+    2m.ld default moves _FS_end and the preferences sector on deployed
+    devices."""
+    assert board_ld_script(BOARDS["d1_wroom_02"]) == "eagle.flash.2m64.ld"
+
+
+def test_default_boards_use_the_flash_size_layout() -> None:
+    assert board_ld_script(BOARDS["d1_mini"]) == "eagle.flash.4m.ld"
+    assert board_ld_script(BOARDS["esp01_1m"]) == "eagle.flash.1m.ld"
+
+
+def test_choose_ld_script_paths() -> None:
+    """Old cores get the size default, overriding boards hard-error there
+    (a substituted layout would wipe flash-backed state), modern cores
+    honor the override."""
+    assert _choose_ld_script("nodemcuv2", cv.Version(2, 3, 0)) is None
+    assert _choose_ld_script("nodemcuv2", cv.Version(2, 4, 2)) == "eagle.flash.4m.ld"
+    assert _choose_ld_script("d1_wroom_02", cv.Version(2, 7, 4)) == (
+        "eagle.flash.2m64.ld"
+    )
+    with pytest.raises(EsphomeError, match="cannot honor"):
+        _choose_ld_script("d1_wroom_02", cv.Version(2, 4, 2))

tests/unit_tests/components/esp8266/test_build_surgery.py

@@ -0,0 +1,145 @@
+"""Tests for the linker-script surgery shared with the native toolchain."""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+import sys
+
+import pytest
+
+from esphome.components.esp8266 import build_surgery
+from esphome.components.esp8266.boards import BOARDS, ESP8266_BOARD_BUILD
+from esphome.components.esp8266.build_surgery import (
+    RATETABLE_RULE,
+    apply_testing_memory_patches,
+    relocate_ratetable,
+    segment_length,
+)
+
+_COMMON_LD_SNIPPET = """\
+  .dport0.data : ALIGN(4)
+  {
+    _dport0_data_start = ABSOLUTE(.);
+  } >dport0_0_seg :dport0_0_phdr
+  .data : ALIGN(4)
+  {
+    _data_start = ABSOLUTE(.);
+    *(.data)
+  } >dram0_0_seg :dram0_0_phdr
+"""
+
+# Shaped like the real SDK flash ld scripts: no iram1_0_seg (that lives in
+# the generated common ld only)
+_FLASH_LD_SNIPPET = """\
+MEMORY
+{
+  dport0_0_seg :                        org = 0x3FF00000, len = 0x10
+  dram0_0_seg :                         org = 0x3FFE8000, len = 0x14000
+  irom0_0_seg :                         org = 0x40201010, len = 0xfeff0
+}
+"""
+
+# Shaped like the preprocessed common ld: MMU_IRAM_SIZE expands with a ul
+# suffix the patcher must leave in place
+_COMMON_LD_MEMORY_SNIPPET = """\
+MEMORY
+{
+  iram1_0_seg :                         org = 0x40100000, len = 0x8000ul
+}
+"""
+
+
+def test_relocate_ratetable_inserts_after_data_start() -> None:
+    patched = relocate_ratetable(_COMMON_LD_SNIPPET)
+    assert RATETABLE_RULE in patched
+    # Inserted after the .data section's anchor, not the .dport0.data one
+    # (whose closing brace bounds the decoy block)
+    assert RATETABLE_RULE not in patched[: patched.index("} >dport0_0_seg")]
+    assert patched.index(RATETABLE_RULE) < patched.index("*(.data)")
+    # Idempotent on an already-patched script
+    assert relocate_ratetable(patched) == patched
+
+
+def test_relocate_ratetable_requires_anchor() -> None:
+    with pytest.raises(RuntimeError, match="_data_start"):
+        relocate_ratetable("SECTIONS { }")
+
+
+def test_testing_memory_patches_enlarge_segments() -> None:
+    patched = apply_testing_memory_patches(
+        _FLASH_LD_SNIPPET, ("dram0_0_seg", "irom0_0_seg")
+    )
+    assert segment_length(patched, "dram0_0_seg") == 0x200000
+    assert segment_length(patched, "irom0_0_seg") == 0x2000000
+    # Untouched segments keep their sizes
+    assert segment_length(patched, "dport0_0_seg") == 0x10
+
+
+def test_testing_memory_patches_keep_ul_suffix() -> None:
+    """The common ld's preprocessed sizes carry a ul suffix; the patch must
+    replace only the hex digits, as testing_mode.py.script does."""
+    patched = apply_testing_memory_patches(_COMMON_LD_MEMORY_SNIPPET, ("iram1_0_seg",))
+    assert "len = 0x200000ul" in patched
+    assert segment_length(patched, "iram1_0_seg") == 0x200000
+
+
+def test_segment_length_requires_whole_name() -> None:
+    """A name must match its own line, never inside a longer segment name."""
+    assert segment_length(_FLASH_LD_SNIPPET, "ram0_0_seg") is None
+
+
+def test_testing_memory_patches_unknown_segment_raises() -> None:
+    with pytest.raises(RuntimeError, match="Unknown testing-mode segment"):
+        apply_testing_memory_patches("MEMORY { }", ("bogus_seg",))
+
+
+def test_segment_length() -> None:
+    assert segment_length(_FLASH_LD_SNIPPET, "irom0_0_seg") == 0xFEFF0
+    assert segment_length(_FLASH_LD_SNIPPET, "missing_seg") is None
+
+
+def test_testing_memory_patches_missing_segment_raises() -> None:
+    """A named segment the patch could not find raises instead of silently
+    keeping the real memory limits."""
+    with pytest.raises(RuntimeError, match="dram0_0_seg"):
+        apply_testing_memory_patches("MEMORY { }", ("dram0_0_seg",))
+
+
+def test_board_build_covers_every_board() -> None:
+    """Every supported board has native build metadata (the table may carry
+    extras that BOARDS does not expose)."""
+    assert set(BOARDS) <= set(ESP8266_BOARD_BUILD)
+
+
+def test_surgery_fingerprint_is_stable_and_sensitive(tmp_path) -> None:
+    """The properties the linker-script cache depends on: the fingerprint is
+    stable across calls and changes when the module's source changes."""
+
+    first = build_surgery.surgery_fingerprint()
+    assert first == build_surgery.surgery_fingerprint()
+    assert len(first) == 64
+    int(first, 16)  # sha256 hex digest
+
+    # A modified copy of the module must fingerprint differently
+    copy = tmp_path / "build_surgery_variant.py"
+    copy.write_text(
+        Path(build_surgery.__file__).read_text(encoding="utf-8")
+        + "\nEXTRA_BEHAVIORAL_INPUT = 1\n",
+        encoding="utf-8",
+    )
+    spec = importlib.util.spec_from_file_location("build_surgery_variant", copy)
+    variant = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = variant
+    try:
+        spec.loader.exec_module(variant)
+        assert variant.surgery_fingerprint() != first
+    finally:
+        del sys.modules[spec.name]
+
+
+def test_testing_memory_patches_present_but_unselected_raises() -> None:
+    """A known segment left off the caller's list must fail, not silently
+    keep its real memory limit."""
+    with pytest.raises(RuntimeError, match="not selected"):
+        apply_testing_memory_patches(_FLASH_LD_SNIPPET, ("dram0_0_seg",))