From 5be4f746ba999cba55a8389ac8ef126c9f5f83cb Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@home-assistant.io>
Date: Wed, 29 Apr 2026 05:46:56 -0500
Subject: [PATCH 1/6] [esp32] Move HAL bodies from components/esp32/core.cpp
 into core/hal/
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per-platform follow-up to #15977.

Move out-of-line HAL bodies (millis(), arch_restart(), arch_get_cpu_freq_hz())
from components/esp32/core.cpp into a new esphome/core/hal/hal_esp32.cpp so
HAL implementation finally lives next to the HAL header.

Inline the trivial one-liners directly in hal_esp32.h:
  delayMicroseconds(us)        -> delay_microseconds_safe(us)
  arch_feed_wdt()              -> esp_task_wdt_reset()
  arch_get_cpu_cycle_count()   -> esp_cpu_get_cycle_count()

arch_init() stays in components/esp32/core.cpp because it uses
esp32::crash_handler_read_and_clear() from the component-private
crash_handler.h header — moving it would require an awkward layering
inversion of core/ -> components/esp32/.

config.py FILTER_SOURCE_FILES gains a hal/hal_esp32.cpp entry so only
ESP32 builds compile it (same pattern wake/wake_*.cpp uses).

Cross-platform decls of delayMicroseconds(), arch_feed_wdt(), and
arch_get_cpu_cycle_count() are dropped from the dispatcher hal.h and
moved into each per-platform header — that way subsequent per-platform
follow-up PRs (libretiny, rp2040, host, zephyr) only need to touch
their own platform header instead of accumulating gates in hal.h.
---
 esphome/components/esp32/core.cpp | 37 ++------------------------
 esphome/core/config.py            | 10 +++++++
 esphome/core/hal.h                | 10 +++----
 esphome/core/hal/hal_esp32.cpp    | 44 +++++++++++++++++++++++++++++++
 esphome/core/hal/hal_esp32.h      | 12 +++++++++
 esphome/core/hal/hal_host.h       |  4 +++
 esphome/core/hal/hal_libretiny.h  |  4 +++
 esphome/core/hal/hal_rp2040.h     |  4 +++
 esphome/core/hal/hal_zephyr.h     |  4 +++
 9 files changed, 87 insertions(+), 42 deletions(-)
 create mode 100644 esphome/core/hal/hal_esp32.cpp

diff --git a/esphome/components/esp32/core.cpp b/esphome/components/esp32/core.cpp
index 4886745c06..267052ea2e 100644
--- a/esphome/components/esp32/core.cpp
+++ b/esphome/components/esp32/core.cpp
@@ -6,12 +6,8 @@
 #include "esphome/core/hal.h"
 #include "esphome/core/helpers.h"
 #include "preferences.h"
-#include <esp_clk_tree.h>
-#include <esp_cpu.h>
-#include <esp_idf_version.h>
 #include <esp_ota_ops.h>
 #include <esp_task_wdt.h>
-#include <esp_timer.h>
 #include <freertos/FreeRTOS.h>
 #include <freertos/task.h>
 
@@ -23,29 +19,8 @@ extern "C" __attribute__((weak)) void initArduino() {}
 namespace esphome {
 
 // yield(), delay(), micros(), millis_64() inlined in hal.h.
-// Use xTaskGetTickCount() when tick rate is 1 kHz (ESPHome's default via sdkconfig),
-// falling back to esp_timer for non-standard rates. IRAM_ATTR is required because
-// Wiegand and ZyAura call millis() from IRAM_ATTR ISR handlers on ESP32.
-// xTaskGetTickCountFromISR() is used in ISR context to satisfy the FreeRTOS API contract.
-uint32_t IRAM_ATTR HOT millis() {
-#if CONFIG_FREERTOS_HZ == 1000
-  if (xPortInIsrContext()) [[unlikely]] {
-    return xTaskGetTickCountFromISR();
-  }
-  return xTaskGetTickCount();
-#else
-  return micros_to_millis(static_cast<uint64_t>(esp_timer_get_time()));
-#endif
-}
-void IRAM_ATTR HOT delayMicroseconds(uint32_t us) { delay_microseconds_safe(us); }
-void arch_restart() {
-  esp_restart();
-  // restart() doesn't always end execution
-  while (true) {  // NOLINT(clang-diagnostic-unreachable-code)
-    yield();
-  }
-}
-
+// millis(), arch_restart(), arch_get_cpu_freq_hz() out-of-line in hal/hal_esp32.cpp.
+// delayMicroseconds(), arch_feed_wdt(), arch_get_cpu_cycle_count() inlined in hal/hal_esp32.h.
 void arch_init() {
 #ifdef USE_ESP32_CRASH_HANDLER
   // Read crash data from previous boot before anything else
@@ -61,14 +36,6 @@ void arch_init() {
   esp_ota_mark_app_valid_cancel_rollback();
 #endif
 }
-void HOT arch_feed_wdt() { esp_task_wdt_reset(); }
-
-uint32_t arch_get_cpu_cycle_count() { return esp_cpu_get_cycle_count(); }
-uint32_t arch_get_cpu_freq_hz() {
-  uint32_t freq = 0;
-  esp_clk_tree_src_get_freq_hz(SOC_MOD_CLK_CPU, ESP_CLK_TREE_SRC_FREQ_PRECISION_CACHED, &freq);
-  return freq;
-}
 
 TaskHandle_t loop_task_handle = nullptr;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
 static StaticTask_t loop_task_tcb;        // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
diff --git a/esphome/core/config.py b/esphome/core/config.py
index b4e81ce49f..ae2a40d036 100644
--- a/esphome/core/config.py
+++ b/esphome/core/config.py
@@ -815,6 +815,16 @@ FILTER_SOURCE_FILES = filter_source_files_from_platform(
         "wake/wake_zephyr.cpp": {
             PlatformFramework.NRF52_ZEPHYR,
         },
+        # Per-platform HAL out-of-line implementations — hal.h dispatches to
+        # exactly one platform header based on USE_*, and the matching .cpp
+        # provides the few HAL functions that stay out-of-line. Other
+        # platforms still keep their out-of-line bodies in
+        # components/<platform>/core.cpp until their per-platform follow-up
+        # PR moves them here.
+        "hal/hal_esp32.cpp": {
+            PlatformFramework.ESP32_ARDUINO,
+            PlatformFramework.ESP32_IDF,
+        },
         # Note: lock_free_queue.h and event_pool.h are header files and don't need to be filtered
         # as they are only included when needed by the preprocessor
     }
diff --git a/esphome/core/hal.h b/esphome/core/hal.h
index e20797cf95..312effa7b0 100644
--- a/esphome/core/hal.h
+++ b/esphome/core/hal.h
@@ -30,15 +30,11 @@
 
 namespace esphome {
 
-// ESP8266 inlines delayMicroseconds() and arch_feed_wdt() in hal/hal_esp8266.h;
-// every other platform keeps them out-of-line in components/<platform>/core.cpp.
-#ifndef USE_ESP8266
-void delayMicroseconds(uint32_t us);  // NOLINT(readability-identifier-naming)
-void arch_feed_wdt();
-#endif
+// Cross-platform declarations. delayMicroseconds(), arch_feed_wdt(),
+// arch_get_cpu_cycle_count() vary per platform (some inline, some
+// out-of-line) so they live in hal/hal_<platform>.h.
 void __attribute__((noreturn)) arch_restart();
 void arch_init();
-uint32_t arch_get_cpu_cycle_count();
 uint32_t arch_get_cpu_freq_hz();
 
 #ifndef USE_ESP8266
diff --git a/esphome/core/hal/hal_esp32.cpp b/esphome/core/hal/hal_esp32.cpp
new file mode 100644
index 0000000000..a881953208
--- /dev/null
+++ b/esphome/core/hal/hal_esp32.cpp
@@ -0,0 +1,44 @@
+#ifdef USE_ESP32
+
+#include "esphome/core/hal.h"
+
+#include <esp_clk_tree.h>
+#include <esp_system.h>
+#include <esp_timer.h>
+#include <freertos/FreeRTOS.h>
+#include <freertos/task.h>
+
+namespace esphome {
+
+// Use xTaskGetTickCount() when tick rate is 1 kHz (ESPHome's default via sdkconfig),
+// falling back to esp_timer for non-standard rates. IRAM_ATTR is required because
+// Wiegand and ZyAura call millis() from IRAM_ATTR ISR handlers on ESP32.
+// xTaskGetTickCountFromISR() is used in ISR context to satisfy the FreeRTOS API contract.
+uint32_t IRAM_ATTR HOT millis() {
+#if CONFIG_FREERTOS_HZ == 1000
+  if (xPortInIsrContext()) [[unlikely]] {
+    return xTaskGetTickCountFromISR();
+  }
+  return xTaskGetTickCount();
+#else
+  return micros_to_millis(static_cast<uint64_t>(esp_timer_get_time()));
+#endif
+}
+
+void arch_restart() {
+  esp_restart();
+  // restart() doesn't always end execution
+  while (true) {  // NOLINT(clang-diagnostic-unreachable-code)
+    yield();
+  }
+}
+
+uint32_t arch_get_cpu_freq_hz() {
+  uint32_t freq = 0;
+  esp_clk_tree_src_get_freq_hz(SOC_MOD_CLK_CPU, ESP_CLK_TREE_SRC_FREQ_PRECISION_CACHED, &freq);
+  return freq;
+}
+
+}  // namespace esphome
+
+#endif  // USE_ESP32
diff --git a/esphome/core/hal/hal_esp32.h b/esphome/core/hal/hal_esp32.h
index e755337540..2bff424441 100644
--- a/esphome/core/hal/hal_esp32.h
+++ b/esphome/core/hal/hal_esp32.h
@@ -4,6 +4,8 @@
 
 #include <cstdint>
 #include <esp_attr.h>
+#include <esp_cpu.h>
+#include <esp_task_wdt.h>
 #include <freertos/FreeRTOS.h>
 #include <freertos/task.h>
 
@@ -15,6 +17,11 @@
 
 namespace esphome {
 
+// Forward decl from helpers.h (esphome/core/helpers.h) — kept here so this
+// header does not need to pull the rest of helpers.h.
+// NOLINTNEXTLINE(readability-redundant-declaration)
+void delay_microseconds_safe(uint32_t us);
+
 /// Returns true when executing inside an interrupt handler.
 __attribute__((always_inline)) inline bool in_isr_context() { return xPortInIsrContext() != 0; }
 
@@ -30,6 +37,11 @@ __attribute__((always_inline)) inline uint64_t millis_64() {
   return micros_to_millis<uint64_t>(static_cast<uint64_t>(esp_timer_get_time()));
 }
 
+// NOLINTNEXTLINE(readability-identifier-naming)
+__attribute__((always_inline)) inline void delayMicroseconds(uint32_t us) { delay_microseconds_safe(us); }
+__attribute__((always_inline)) inline void arch_feed_wdt() { esp_task_wdt_reset(); }
+__attribute__((always_inline)) inline uint32_t arch_get_cpu_cycle_count() { return esp_cpu_get_cycle_count(); }
+
 }  // namespace esphome
 
 #endif  // USE_ESP32
diff --git a/esphome/core/hal/hal_host.h b/esphome/core/hal/hal_host.h
index 145fe4ea9c..682a1a422b 100644
--- a/esphome/core/hal/hal_host.h
+++ b/esphome/core/hal/hal_host.h
@@ -19,6 +19,10 @@ uint32_t micros();
 uint32_t millis();
 uint64_t millis_64();
 
+void delayMicroseconds(uint32_t us);  // NOLINT(readability-identifier-naming)
+void arch_feed_wdt();
+uint32_t arch_get_cpu_cycle_count();
+
 }  // namespace esphome
 
 #endif  // USE_HOST
diff --git a/esphome/core/hal/hal_libretiny.h b/esphome/core/hal/hal_libretiny.h
index e0d92735bb..e9d33b7753 100644
--- a/esphome/core/hal/hal_libretiny.h
+++ b/esphome/core/hal/hal_libretiny.h
@@ -88,6 +88,10 @@ __attribute__((always_inline)) inline uint32_t millis() { return static_cast<uin
 #endif
 __attribute__((always_inline)) inline uint64_t millis_64() { return Millis64Impl::compute(millis()); }
 
+void delayMicroseconds(uint32_t us);  // NOLINT(readability-identifier-naming)
+void arch_feed_wdt();
+uint32_t arch_get_cpu_cycle_count();
+
 }  // namespace esphome
 
 #endif  // USE_LIBRETINY
diff --git a/esphome/core/hal/hal_rp2040.h b/esphome/core/hal/hal_rp2040.h
index 156ff33b86..2a1d67b4a3 100644
--- a/esphome/core/hal/hal_rp2040.h
+++ b/esphome/core/hal/hal_rp2040.h
@@ -35,6 +35,10 @@ __attribute__((always_inline)) inline uint32_t micros() { return static_cast<uin
 __attribute__((always_inline)) inline uint32_t millis() { return micros_to_millis(::time_us_64()); }
 __attribute__((always_inline)) inline uint64_t millis_64() { return micros_to_millis<uint64_t>(::time_us_64()); }
 
+void delayMicroseconds(uint32_t us);  // NOLINT(readability-identifier-naming)
+void arch_feed_wdt();
+uint32_t arch_get_cpu_cycle_count();
+
 }  // namespace esphome
 
 #endif  // USE_RP2040
diff --git a/esphome/core/hal/hal_zephyr.h b/esphome/core/hal/hal_zephyr.h
index e28be5c775..6707c85b2c 100644
--- a/esphome/core/hal/hal_zephyr.h
+++ b/esphome/core/hal/hal_zephyr.h
@@ -19,6 +19,10 @@ uint32_t micros();
 uint32_t millis();
 uint64_t millis_64();
 
+void delayMicroseconds(uint32_t us);  // NOLINT(readability-identifier-naming)
+void arch_feed_wdt();
+uint32_t arch_get_cpu_cycle_count();
+
 }  // namespace esphome
 
 #endif  // USE_ZEPHYR

From 174a0b7631c36a6f8dde3699678c5c585a61c021 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@home-assistant.io>
Date: Wed, 29 Apr 2026 05:53:18 -0500
Subject: [PATCH 2/6] [esp32] Use components/esp32/hal.cpp instead of
 core/hal/hal_esp32.cpp
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous commit placed the out-of-line ESP32 HAL bodies under
core/hal/hal_esp32.cpp and gated compilation via FILTER_SOURCE_FILES,
mirroring the wake/wake_<platform>.cpp pattern. Switch to the simpler
components/esp32/hal.cpp location instead:

- A component-internal .cpp only compiles when USE_<PLATFORM> is set,
  so no FILTER_SOURCE_FILES entry is needed (revert that addition).
- The file can include the component's private crash_handler.h header
  directly without a layering inversion or forward decl, so arch_init()
  also moves into hal.cpp now (previously stuck in core.cpp because of
  that header dependency).
- A future consolidation PR will move the existing core/wake/wake_*.cpp
  files into components/<platform>/wake.cpp the same way and drop their
  FILTER_SOURCE_FILES entries.

ci-custom's lint_namespace check is satisfied with an empty
namespace esphome::esp32 {} block at the top of the file — the HAL
functions themselves live in namespace esphome (root) since they are
not part of the esp32 component's API.
---
 esphome/components/esp32/core.cpp             | 27 ++-----------------
 .../esp32/hal.cpp}                            | 25 +++++++++++++++++
 esphome/core/config.py                        | 10 -------
 3 files changed, 27 insertions(+), 35 deletions(-)
 rename esphome/{core/hal/hal_esp32.cpp => components/esp32/hal.cpp} (57%)

diff --git a/esphome/components/esp32/core.cpp b/esphome/components/esp32/core.cpp
index 267052ea2e..5249f4a59e 100644
--- a/esphome/components/esp32/core.cpp
+++ b/esphome/components/esp32/core.cpp
@@ -1,13 +1,8 @@
 #ifdef USE_ESP32
 
-#include "esphome/core/defines.h"
-#include "crash_handler.h"
 #include "esphome/core/application.h"
-#include "esphome/core/hal.h"
-#include "esphome/core/helpers.h"
+#include "esphome/core/defines.h"
 #include "preferences.h"
-#include <esp_ota_ops.h>
-#include <esp_task_wdt.h>
 #include <freertos/FreeRTOS.h>
 #include <freertos/task.h>
 
@@ -18,25 +13,7 @@ extern "C" __attribute__((weak)) void initArduino() {}
 
 namespace esphome {
 
-// yield(), delay(), micros(), millis_64() inlined in hal.h.
-// millis(), arch_restart(), arch_get_cpu_freq_hz() out-of-line in hal/hal_esp32.cpp.
-// delayMicroseconds(), arch_feed_wdt(), arch_get_cpu_cycle_count() inlined in hal/hal_esp32.h.
-void arch_init() {
-#ifdef USE_ESP32_CRASH_HANDLER
-  // Read crash data from previous boot before anything else
-  esp32::crash_handler_read_and_clear();
-#endif
-
-  // Enable the task watchdog only on the loop task (from which we're currently running)
-  esp_task_wdt_add(nullptr);
-
-  // Handle OTA rollback: mark partition valid immediately unless USE_OTA_ROLLBACK is enabled,
-  // in which case safe_mode will mark it valid after confirming successful boot.
-#ifndef USE_OTA_ROLLBACK
-  esp_ota_mark_app_valid_cancel_rollback();
-#endif
-}
-
+// HAL functions live in hal.cpp. This file keeps only the loop task setup.
 TaskHandle_t loop_task_handle = nullptr;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
 static StaticTask_t loop_task_tcb;        // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
 static StackType_t
diff --git a/esphome/core/hal/hal_esp32.cpp b/esphome/components/esp32/hal.cpp
similarity index 57%
rename from esphome/core/hal/hal_esp32.cpp
rename to esphome/components/esp32/hal.cpp
index a881953208..3a0836a507 100644
--- a/esphome/core/hal/hal_esp32.cpp
+++ b/esphome/components/esp32/hal.cpp
@@ -1,13 +1,22 @@
 #ifdef USE_ESP32
 
+#include "crash_handler.h"
+#include "esphome/core/defines.h"
 #include "esphome/core/hal.h"
 
 #include <esp_clk_tree.h>
+#include <esp_ota_ops.h>
 #include <esp_system.h>
+#include <esp_task_wdt.h>
 #include <esp_timer.h>
 #include <freertos/FreeRTOS.h>
 #include <freertos/task.h>
 
+// Empty esp32 namespace block to satisfy ci-custom's lint_namespace check.
+// HAL functions live in namespace esphome (root) — they are not part of the
+// esp32 component's API.
+namespace esphome::esp32 {}  // namespace esphome::esp32
+
 namespace esphome {
 
 // Use xTaskGetTickCount() when tick rate is 1 kHz (ESPHome's default via sdkconfig),
@@ -33,6 +42,22 @@ void arch_restart() {
   }
 }
 
+void arch_init() {
+#ifdef USE_ESP32_CRASH_HANDLER
+  // Read crash data from previous boot before anything else
+  esp32::crash_handler_read_and_clear();
+#endif
+
+  // Enable the task watchdog only on the loop task (from which we're currently running)
+  esp_task_wdt_add(nullptr);
+
+  // Handle OTA rollback: mark partition valid immediately unless USE_OTA_ROLLBACK is enabled,
+  // in which case safe_mode will mark it valid after confirming successful boot.
+#ifndef USE_OTA_ROLLBACK
+  esp_ota_mark_app_valid_cancel_rollback();
+#endif
+}
+
 uint32_t arch_get_cpu_freq_hz() {
   uint32_t freq = 0;
   esp_clk_tree_src_get_freq_hz(SOC_MOD_CLK_CPU, ESP_CLK_TREE_SRC_FREQ_PRECISION_CACHED, &freq);
diff --git a/esphome/core/config.py b/esphome/core/config.py
index ae2a40d036..b4e81ce49f 100644
--- a/esphome/core/config.py
+++ b/esphome/core/config.py
@@ -815,16 +815,6 @@ FILTER_SOURCE_FILES = filter_source_files_from_platform(
         "wake/wake_zephyr.cpp": {
             PlatformFramework.NRF52_ZEPHYR,
         },
-        # Per-platform HAL out-of-line implementations — hal.h dispatches to
-        # exactly one platform header based on USE_*, and the matching .cpp
-        # provides the few HAL functions that stay out-of-line. Other
-        # platforms still keep their out-of-line bodies in
-        # components/<platform>/core.cpp until their per-platform follow-up
-        # PR moves them here.
-        "hal/hal_esp32.cpp": {
-            PlatformFramework.ESP32_ARDUINO,
-            PlatformFramework.ESP32_IDF,
-        },
         # Note: lock_free_queue.h and event_pool.h are header files and don't need to be filtered
         # as they are only included when needed by the preprocessor
     }

From 4009c498d956b17dd742406f1cdabaa7b4dc5700 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@home-assistant.io>
Date: Wed, 29 Apr 2026 06:50:59 -0500
Subject: [PATCH 3/6] [esp32] Fix hal.cpp include order: defines.h before
 crash_handler.h

crash_handler.h is itself guarded by #ifdef USE_ESP32_CRASH_HANDLER, so when
hal.cpp included it before defines.h, the namespace block was empty at parse
time and arch_init()'s USE_ESP32_CRASH_HANDLER branch failed with:

  error: 'crash_handler_read_and_clear' is not a member of 'esphome::esp32'

Pull defines.h first so USE_ESP32_CRASH_HANDLER is defined before
crash_handler.h is parsed.
---
 esphome/components/esp32/hal.cpp | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/esphome/components/esp32/hal.cpp b/esphome/components/esp32/hal.cpp
index 3a0836a507..f6199d557f 100644
--- a/esphome/components/esp32/hal.cpp
+++ b/esphome/components/esp32/hal.cpp
@@ -1,7 +1,9 @@
 #ifdef USE_ESP32
 
-#include "crash_handler.h"
+// defines.h must come before crash_handler.h so USE_ESP32_CRASH_HANDLER is set
+// before crash_handler.h's #ifdef-guarded namespace block is parsed.
 #include "esphome/core/defines.h"
+#include "crash_handler.h"
 #include "esphome/core/hal.h"
 
 #include <esp_clk_tree.h>

From 9dc28556d7999f5f029608af1eb627fe5bc03da8 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@home-assistant.io>
Date: Wed, 29 Apr 2026 07:24:24 -0500
Subject: [PATCH 4/6] [esp8266] Add bare arch_get_cpu_cycle_count() decl in
 hal_esp8266.h
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Followup #16111 dropped the cross-platform arch_get_cpu_cycle_count()
declaration from hal.h dispatcher and added bare decls to libretiny,
rp2040, host, and zephyr per-platform headers — but missed
hal_esp8266.h. ESP8266 callers (spi.h, uart_component_esp8266.cpp) now
fail clang-tidy with 'use of undeclared identifier'.

The body is still out-of-line in components/esp8266/core.cpp on this
PR; the inline def is added on the chained #16112 PR. Add a bare decl
here for now so #16111 builds in isolation.
---
 esphome/core/hal/hal_esp8266.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/esphome/core/hal/hal_esp8266.h b/esphome/core/hal/hal_esp8266.h
index 04326a3579..484118f1f5 100644
--- a/esphome/core/hal/hal_esp8266.h
+++ b/esphome/core/hal/hal_esp8266.h
@@ -60,6 +60,8 @@ __attribute__((always_inline)) inline uint16_t progmem_read_uint16(const uint16_
 __attribute__((always_inline)) inline void delayMicroseconds(uint32_t us) { delay_microseconds_safe(us); }
 __attribute__((always_inline)) inline void arch_feed_wdt() { system_soft_wdt_feed(); }
 
+uint32_t arch_get_cpu_cycle_count();
+
 }  // namespace esphome
 
 #endif  // USE_ESP8266

From ce61dcf3873b7fe7a7e8063cc44168222a3aee4a Mon Sep 17 00:00:00 2001
From: Jonathan Swoboda <154711427+swoboda1337@users.noreply.github.com>
Date: Wed, 29 Apr 2026 12:54:17 -0400
Subject: [PATCH 5/6] [remote_base][core] Drop redundant typename in dependent
 type contexts (#16137)

---
 esphome/components/remote_base/remote_base.h | 8 ++++----
 esphome/core/finite_set_mask.h               | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/esphome/components/remote_base/remote_base.h b/esphome/components/remote_base/remote_base.h
index d73fff2b0a..e5e923d780 100644
--- a/esphome/components/remote_base/remote_base.h
+++ b/esphome/components/remote_base/remote_base.h
@@ -164,7 +164,7 @@ class RemoteTransmitterBase : public RemoteComponentBase {
     return TransmitCall(this);
   }
   template<typename Protocol>
-  void transmit(const typename Protocol::ProtocolData &data, uint32_t send_times = 1, uint32_t send_wait = 0) {
+  void transmit(const Protocol::ProtocolData &data, uint32_t send_times = 1, uint32_t send_wait = 0) {
     auto call = this->transmit();
     Protocol().encode(call.get_data(), data);
     call.set_send_times(send_times);
@@ -250,10 +250,10 @@ template<typename T> class RemoteReceiverBinarySensor : public RemoteReceiverBin
   }
 
  public:
-  void set_data(typename T::ProtocolData data) { data_ = data; }
+  void set_data(T::ProtocolData data) { data_ = data; }
 
  protected:
-  typename T::ProtocolData data_;
+  T::ProtocolData data_;
 };
 
 template<typename T>
@@ -278,7 +278,7 @@ class RemoteTransmittable {
 
  protected:
   template<typename Protocol>
-  void transmit_(const typename Protocol::ProtocolData &data, uint32_t send_times = 1, uint32_t send_wait = 0) {
+  void transmit_(const Protocol::ProtocolData &data, uint32_t send_times = 1, uint32_t send_wait = 0) {
     this->transmitter_->transmit<Protocol>(data, send_times, send_wait);
   }
   RemoteTransmitterBase *transmitter_;
diff --git a/esphome/core/finite_set_mask.h b/esphome/core/finite_set_mask.h
index 616c69353d..272337ff76 100644
--- a/esphome/core/finite_set_mask.h
+++ b/esphome/core/finite_set_mask.h
@@ -55,7 +55,7 @@ template<typename ValueType, int MaxBits> struct DefaultBitPolicy {
 ///
 template<typename ValueType, typename BitPolicy = DefaultBitPolicy<ValueType, 16>> class FiniteSetMask {
  public:
-  using bitmask_t = typename BitPolicy::mask_t;
+  using bitmask_t = BitPolicy::mask_t;
 
   constexpr FiniteSetMask() = default;
 

From 69a33d8ac0c879646923767b7cc2164b69c838c4 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Wed, 29 Apr 2026 12:31:55 -0500
Subject: [PATCH 6/6] [core] Inline HAL clock wrappers and split hal.h into
 per-platform headers (#15977)

---
 esphome/components/esp32/core.cpp     |  11 +--
 esphome/components/esp8266/core.cpp   |  17 +---
 esphome/components/libretiny/core.cpp |  28 +-----
 esphome/components/rp2040/core.cpp    |   6 +-
 esphome/core/hal.h                    | 131 ++++++--------------------
 esphome/core/hal/hal_esp32.h          |  35 +++++++
 esphome/core/hal/hal_esp8266.h        |  65 +++++++++++++
 esphome/core/hal/hal_host.h           |  24 +++++
 esphome/core/hal/hal_libretiny.h      |  93 ++++++++++++++++++
 esphome/core/hal/hal_rp2040.h         |  40 ++++++++
 esphome/core/hal/hal_zephyr.h         |  24 +++++
 esphome/core/helpers.h                |  41 +-------
 esphome/core/time_64.h                |   6 +-
 esphome/core/time_conversion.h        |  46 +++++++++
 14 files changed, 366 insertions(+), 201 deletions(-)
 create mode 100644 esphome/core/hal/hal_esp32.h
 create mode 100644 esphome/core/hal/hal_esp8266.h
 create mode 100644 esphome/core/hal/hal_host.h
 create mode 100644 esphome/core/hal/hal_libretiny.h
 create mode 100644 esphome/core/hal/hal_rp2040.h
 create mode 100644 esphome/core/hal/hal_zephyr.h
 create mode 100644 esphome/core/time_conversion.h

diff --git a/esphome/components/esp32/core.cpp b/esphome/components/esp32/core.cpp
index 1c63137183..4886745c06 100644
--- a/esphome/components/esp32/core.cpp
+++ b/esphome/components/esp32/core.cpp
@@ -22,7 +22,7 @@ extern "C" __attribute__((weak)) void initArduino() {}
 
 namespace esphome {
 
-void HOT yield() { vPortYield(); }
+// yield(), delay(), micros(), millis_64() inlined in hal.h.
 // Use xTaskGetTickCount() when tick rate is 1 kHz (ESPHome's default via sdkconfig),
 // falling back to esp_timer for non-standard rates. IRAM_ATTR is required because
 // Wiegand and ZyAura call millis() from IRAM_ATTR ISR handlers on ESP32.
@@ -37,15 +37,6 @@ uint32_t IRAM_ATTR HOT millis() {
   return micros_to_millis(static_cast<uint64_t>(esp_timer_get_time()));
 #endif
 }
-// millis_64() stays on esp_timer — a different clock from xTaskGetTickCount(). This is
-// safe because the two are never cross-compared: millis() values are only used for
-// millis()-vs-millis() deltas (feed_wdt, warn_blocking, component start time), while
-// millis_64() is used by the Scheduler and uptime sensors. On ESP32 (USE_NATIVE_64BIT_TIME),
-// Scheduler::millis_64_from_(now) discards the 32-bit now and calls millis_64() directly,
-// so the Scheduler is internally consistent on the esp_timer clock.
-uint64_t HOT millis_64() { return micros_to_millis<uint64_t>(static_cast<uint64_t>(esp_timer_get_time())); }
-void HOT delay(uint32_t ms) { vTaskDelay(ms / portTICK_PERIOD_MS); }
-uint32_t IRAM_ATTR HOT micros() { return (uint32_t) esp_timer_get_time(); }
 void IRAM_ATTR HOT delayMicroseconds(uint32_t us) { delay_microseconds_safe(us); }
 void arch_restart() {
   esp_restart();
diff --git a/esphome/components/esp8266/core.cpp b/esphome/components/esp8266/core.cpp
index c9bedb61be..9161ca6aaf 100644
--- a/esphome/components/esp8266/core.cpp
+++ b/esphome/components/esp8266/core.cpp
@@ -15,7 +15,7 @@ extern "C" {
 
 namespace esphome {
 
-void HOT yield() { ::yield(); }
+// yield(), micros(), millis_64() inlined in hal.h.
 // Fast accumulator replacement for Arduino's millis() (~3.3 μs via 4× 64-bit
 // multiplies on the LX106). Tracks a running ms counter from 32-bit
 // system_get_time() deltas using pure 32-bit ops. Installed as __wrap_millis
@@ -66,7 +66,6 @@ uint32_t IRAM_ATTR HOT millis() {
   xt_wsr_ps(ps);
   return result;
 }
-uint64_t millis_64() { return Millis64Impl::compute(millis()); }
 // Poll-based delay that avoids ::delay() — Arduino's __delay has an intra-object
 // call to the original millis() that --wrap can't intercept, so calling ::delay()
 // would keep the slow Arduino millis body alive in IRAM. optimistic_yield still
@@ -85,8 +84,7 @@ void HOT delay(uint32_t ms) {
     optimistic_yield(1000);
   }
 }
-uint32_t IRAM_ATTR HOT micros() { return ::micros(); }
-void IRAM_ATTR HOT delayMicroseconds(uint32_t us) { delay_microseconds_safe(us); }
+// delayMicroseconds(), arch_feed_wdt(), and progmem_read_*() are inlined in hal/hal_esp8266.h.
 void arch_restart() {
   system_restart();
   // restart() doesn't always end execution
@@ -95,17 +93,6 @@ void arch_restart() {
   }
 }
 void arch_init() {}
-void HOT arch_feed_wdt() { system_soft_wdt_feed(); }
-
-uint8_t progmem_read_byte(const uint8_t *addr) {
-  return pgm_read_byte(addr);  // NOLINT
-}
-const char *progmem_read_ptr(const char *const *addr) {
-  return reinterpret_cast<const char *>(pgm_read_ptr(addr));  // NOLINT
-}
-uint16_t progmem_read_uint16(const uint16_t *addr) {
-  return pgm_read_word(addr);  // NOLINT
-}
 uint32_t IRAM_ATTR HOT arch_get_cpu_cycle_count() { return esp_get_cycle_count(); }
 uint32_t arch_get_cpu_freq_hz() { return F_CPU; }
 
diff --git a/esphome/components/libretiny/core.cpp b/esphome/components/libretiny/core.cpp
index ca46bcb899..f46abe3b81 100644
--- a/esphome/components/libretiny/core.cpp
+++ b/esphome/components/libretiny/core.cpp
@@ -3,7 +3,6 @@
 #include "core.h"
 #include "esphome/core/defines.h"
 #include "esphome/core/hal.h"
-#include "esphome/core/time_64.h"
 #include "esphome/core/helpers.h"
 #include "preferences.h"
 
@@ -15,32 +14,7 @@ void loop();
 
 namespace esphome {
 
-void HOT yield() { ::yield(); }
-// Inline the tick read so esphome::millis() matches MillisInternal::get()'s fast
-// path instead of going through the Arduino core's out-of-line ::millis() wrapper.
-//
-// RTL87xx / LN882x (1 kHz): xTaskGetTickCount() is already ms. IRAM_ATTR + ISR
-// dispatch are needed because ISR handlers (e.g. rotary_encoder) call millis().
-//
-// BK72xx (500 Hz): ticks * portTICK_PERIOD_MS (== 2). IRAM_ATTR and ISR dispatch
-// are both unnecessary — the SDK masks FIQ + IRQ during flash writes (see hal.h),
-// so no ISR runs while flash is stalled.
-#if defined(USE_RTL87XX) || defined(USE_LN882X)
-uint32_t IRAM_ATTR HOT millis() {
-  static_assert(configTICK_RATE_HZ == 1000, "millis() fast path requires 1 kHz FreeRTOS tick");
-  return in_isr_context() ? xTaskGetTickCountFromISR() : xTaskGetTickCount();
-}
-#elif defined(USE_BK72XX)
-uint32_t HOT millis() {
-  static_assert(configTICK_RATE_HZ == 500, "BK72xx millis() fast path assumes 500 Hz FreeRTOS tick");
-  return xTaskGetTickCount() * portTICK_PERIOD_MS;
-}
-#else
-uint32_t IRAM_ATTR HOT millis() { return ::millis(); }
-#endif
-uint64_t millis_64() { return Millis64Impl::compute(millis()); }
-uint32_t IRAM_ATTR HOT micros() { return ::micros(); }
-void HOT delay(uint32_t ms) { ::delay(ms); }
+// yield(), delay(), micros(), millis(), millis_64() inlined in hal.h.
 void IRAM_ATTR HOT delayMicroseconds(uint32_t us) { ::delayMicroseconds(us); }
 
 void arch_init() {
diff --git a/esphome/components/rp2040/core.cpp b/esphome/components/rp2040/core.cpp
index b7a9000612..d3dc1cf2bb 100644
--- a/esphome/components/rp2040/core.cpp
+++ b/esphome/components/rp2040/core.cpp
@@ -13,11 +13,7 @@
 
 namespace esphome {
 
-void HOT yield() { ::yield(); }
-uint64_t millis_64() { return micros_to_millis<uint64_t>(time_us_64()); }
-uint32_t HOT millis() { return micros_to_millis(time_us_64()); }
-void HOT delay(uint32_t ms) { ::delay(ms); }
-uint32_t HOT micros() { return ::micros(); }
+// yield(), delay(), micros(), millis(), millis_64() inlined in hal.h.
 void HOT delayMicroseconds(uint32_t us) { delay_microseconds_safe(us); }
 void arch_restart() {
   watchdog_reboot(0, 0, 10);
diff --git a/esphome/core/hal.h b/esphome/core/hal.h
index e4083622b9..e20797cf95 100644
--- a/esphome/core/hal.h
+++ b/esphome/core/hal.h
@@ -2,125 +2,48 @@
 #include <string>
 #include <cstdint>
 #include "gpio.h"
+#include "esphome/core/defines.h"
+#include "esphome/core/time_64.h"
+#include "esphome/core/time_conversion.h"
 
+// Per-platform HAL bits (IRAM_ATTR / PROGMEM macros, in_isr_context(),
+// inline yield/delay/micros/millis/millis_64 wrappers, ESP8266 progmem
+// helpers) live under esphome/core/hal/ and are dispatched here based on
+// the active USE_* platform define. Each header guards its body with the
+// matching #ifdef USE_<platform> and re-enters namespace esphome {} so it
+// is safe to be re-included.
 #if defined(USE_ESP32)
-#include <esp_attr.h>
-#ifndef PROGMEM
-#define PROGMEM
-#endif
-
+#include "esphome/core/hal/hal_esp32.h"
 #elif defined(USE_ESP8266)
-
-#include <c_types.h>
-#ifndef PROGMEM
-#define PROGMEM ICACHE_RODATA_ATTR
-#endif
-
-#elif defined(USE_RP2040)
-
-#define IRAM_ATTR __attribute__((noinline, long_call, section(".time_critical")))
-#define PROGMEM
-
+#include "esphome/core/hal/hal_esp8266.h"
 #elif defined(USE_LIBRETINY)
-
-// IRAM_ATTR places a function in executable RAM so it is callable from an
-// ISR even while flash is busy (XIP stall, OTA, logger flash write).
-// Each family uses a section its stock linker already routes to RAM:
-// RTL8710B → .image2.ram.text, RTL8720C → .sram.text. LN882H is the
-// exception: its stock linker has no matching glob, so patch_linker.py
-// injects KEEP(*(.sram.text*)) into .flash_copysection at pre-link.
-//
-// BK72xx (all variants) are left as a no-op: their SDK wraps flash
-// operations in GLOBAL_INT_DISABLE() which masks FIQ + IRQ at the CPU for
-// the duration of every write, so no ISR fires while flash is stalled and
-// the race IRAM_ATTR guards against cannot occur. The trade-off is that
-// interrupts are delayed (not dropped) by up to ~20 ms during a sector
-// erase, but that is an SDK-level choice and cannot be changed from this
-// layer.
-#if defined(USE_BK72XX)
-#define IRAM_ATTR
-#elif defined(USE_LIBRETINY_VARIANT_RTL8710B)
-// Stock linker consumes *(.image2.ram.text*) into .ram_image2.text (> BD_RAM).
-#define IRAM_ATTR __attribute__((noinline, section(".image2.ram.text")))
+#include "esphome/core/hal/hal_libretiny.h"
+#elif defined(USE_RP2040)
+#include "esphome/core/hal/hal_rp2040.h"
+#elif defined(USE_HOST)
+#include "esphome/core/hal/hal_host.h"
+#elif defined(USE_ZEPHYR)
+#include "esphome/core/hal/hal_zephyr.h"
 #else
-// RTL8720C: stock linker consumes *(.sram.text*) into .ram.code_text.
-// LN882H: patch_linker.py.script injects *(.sram.text*) into
-// .flash_copysection (> RAM0 AT> FLASH).
-#define IRAM_ATTR __attribute__((noinline, section(".sram.text")))
-#endif
-#define PROGMEM
-
-#else
-
-#define IRAM_ATTR
-#define PROGMEM
-
-#endif
-
-#ifdef USE_ESP32
-#include <freertos/FreeRTOS.h>
-#include <freertos/task.h>
-#endif
-
-#ifdef USE_BK72XX
-// Declared in the Beken FreeRTOS port (portmacro.h) and built in ARM mode so
-// it is callable from Thumb code via interworking. The MRS CPSR instruction
-// is ARM-only and user code here may be built in Thumb, so in_isr_context()
-// defers to this port helper on BK72xx instead of reading CPSR inline.
-extern "C" uint32_t platform_is_in_interrupt_context(void);
+#error "hal.h: not implemented for this platform"
 #endif
 
 namespace esphome {
 
-/// Returns true when executing inside an interrupt handler.
-/// always_inline so callers placed in IRAM keep the detection in IRAM.
-__attribute__((always_inline)) inline bool in_isr_context() {
-#if defined(USE_ESP32)
-  return xPortInIsrContext() != 0;
-#elif defined(USE_ESP8266)
-  // ESP8266 has no reliable single-register ISR detection: PS.INTLEVEL is
-  // non-zero both in a real ISR and when user code masks interrupts.  The
-  // ESP8266 wake path is context-agnostic (wake_loop_impl uses esp_schedule
-  // which is ISR-safe) so this helper is unused on this platform.
-  return false;
-#elif defined(USE_RP2040)
-  uint32_t ipsr;
-  __asm__ volatile("mrs %0, ipsr" : "=r"(ipsr));
-  return ipsr != 0;
-#elif defined(USE_BK72XX)
-  // BK72xx is ARM968E-S (ARM9); see extern declaration above.
-  return platform_is_in_interrupt_context() != 0;
-#elif defined(USE_LIBRETINY)
-  // Cortex-M (AmebaZ, AmebaZ2, LN882H). IPSR is the active exception number;
-  // non-zero means we're in a handler.
-  uint32_t ipsr;
-  __asm__ volatile("mrs %0, ipsr" : "=r"(ipsr));
-  return ipsr != 0;
-#else
-  // Host and any future platform without an ISR concept.
-  return false;
-#endif
-}
-
-void yield();
-uint32_t millis();
-uint64_t millis_64();
-uint32_t micros();
-void delay(uint32_t ms);
+// ESP8266 inlines delayMicroseconds() and arch_feed_wdt() in hal/hal_esp8266.h;
+// every other platform keeps them out-of-line in components/<platform>/core.cpp.
+#ifndef USE_ESP8266
 void delayMicroseconds(uint32_t us);  // NOLINT(readability-identifier-naming)
+void arch_feed_wdt();
+#endif
 void __attribute__((noreturn)) arch_restart();
 void arch_init();
-void arch_feed_wdt();
 uint32_t arch_get_cpu_cycle_count();
 uint32_t arch_get_cpu_freq_hz();
 
-#ifdef USE_ESP8266
-// ESP8266: pgm_read_* does real flash reads on Harvard architecture
-uint8_t progmem_read_byte(const uint8_t *addr);
-const char *progmem_read_ptr(const char *const *addr);
-uint16_t progmem_read_uint16(const uint16_t *addr);
-#else
-// All other platforms: PROGMEM is a no-op, so these are direct dereferences
+#ifndef USE_ESP8266
+// All non-ESP8266 platforms: PROGMEM is a no-op, so these are direct dereferences.
+// ESP8266's out-of-line declarations live in hal/hal_esp8266.h.
 inline uint8_t progmem_read_byte(const uint8_t *addr) { return *addr; }
 inline const char *progmem_read_ptr(const char *const *addr) { return *addr; }
 inline uint16_t progmem_read_uint16(const uint16_t *addr) { return *addr; }
diff --git a/esphome/core/hal/hal_esp32.h b/esphome/core/hal/hal_esp32.h
new file mode 100644
index 0000000000..e755337540
--- /dev/null
+++ b/esphome/core/hal/hal_esp32.h
@@ -0,0 +1,35 @@
+#pragma once
+
+#ifdef USE_ESP32
+
+#include <cstdint>
+#include <esp_attr.h>
+#include <freertos/FreeRTOS.h>
+#include <freertos/task.h>
+
+#include "esphome/core/time_conversion.h"
+
+#ifndef PROGMEM
+#define PROGMEM
+#endif
+
+namespace esphome {
+
+/// Returns true when executing inside an interrupt handler.
+__attribute__((always_inline)) inline bool in_isr_context() { return xPortInIsrContext() != 0; }
+
+// Forward decl from <esp_timer.h>.
+// NOLINTNEXTLINE(readability-redundant-declaration)
+extern "C" int64_t esp_timer_get_time(void);
+
+__attribute__((always_inline)) inline void yield() { vPortYield(); }
+__attribute__((always_inline)) inline void delay(uint32_t ms) { vTaskDelay(ms / portTICK_PERIOD_MS); }
+__attribute__((always_inline)) inline uint32_t micros() { return static_cast<uint32_t>(esp_timer_get_time()); }
+uint32_t millis();
+__attribute__((always_inline)) inline uint64_t millis_64() {
+  return micros_to_millis<uint64_t>(static_cast<uint64_t>(esp_timer_get_time()));
+}
+
+}  // namespace esphome
+
+#endif  // USE_ESP32
diff --git a/esphome/core/hal/hal_esp8266.h b/esphome/core/hal/hal_esp8266.h
new file mode 100644
index 0000000000..04326a3579
--- /dev/null
+++ b/esphome/core/hal/hal_esp8266.h
@@ -0,0 +1,65 @@
+#pragma once
+
+#ifdef USE_ESP8266
+
+#include <c_types.h>
+#include <cstdint>
+#include <pgmspace.h>
+
+#include "esphome/core/time_64.h"
+
+#ifndef PROGMEM
+#define PROGMEM ICACHE_RODATA_ATTR
+#endif
+
+// Forward decls from Arduino's <Arduino.h> for the inline wrappers below.
+// NOLINTBEGIN(google-runtime-int,readability-identifier-naming,readability-redundant-declaration)
+extern "C" void yield(void);
+extern "C" void delay(unsigned long ms);
+extern "C" unsigned long micros(void);
+extern "C" unsigned long millis(void);
+// NOLINTEND(google-runtime-int,readability-identifier-naming,readability-redundant-declaration)
+
+// Forward decl from <user_interface.h> for arch_feed_wdt() inline below.
+// NOLINTNEXTLINE(readability-redundant-declaration)
+extern "C" void system_soft_wdt_feed(void);
+
+namespace esphome {
+
+// Forward decl from helpers.h so this header stays cheap.
+// NOLINTNEXTLINE(readability-redundant-declaration)
+void delay_microseconds_safe(uint32_t us);
+
+/// Returns true when executing inside an interrupt handler.
+/// ESP8266 has no reliable single-register ISR detection: PS.INTLEVEL is
+/// non-zero both in a real ISR and when user code masks interrupts.  The
+/// ESP8266 wake path is context-agnostic (wake_loop_impl uses esp_schedule
+/// which is ISR-safe) so this helper is unused on this platform.
+__attribute__((always_inline)) inline bool in_isr_context() { return false; }
+
+__attribute__((always_inline)) inline void yield() { ::yield(); }
+__attribute__((always_inline)) inline uint32_t micros() { return static_cast<uint32_t>(::micros()); }
+void delay(uint32_t ms);
+uint32_t millis();
+__attribute__((always_inline)) inline uint64_t millis_64() { return Millis64Impl::compute(millis()); }
+
+// ESP8266: pgm_read_* does aligned 32-bit flash reads on Harvard architecture.
+// Inline-forward to the platform macros so the wrappers themselves don't
+// occupy IRAM/flash on every call site.
+__attribute__((always_inline)) inline uint8_t progmem_read_byte(const uint8_t *addr) {
+  return pgm_read_byte(addr);  // NOLINT
+}
+__attribute__((always_inline)) inline const char *progmem_read_ptr(const char *const *addr) {
+  return reinterpret_cast<const char *>(pgm_read_ptr(addr));  // NOLINT
+}
+__attribute__((always_inline)) inline uint16_t progmem_read_uint16(const uint16_t *addr) {
+  return pgm_read_word(addr);  // NOLINT
+}
+
+// NOLINTNEXTLINE(readability-identifier-naming)
+__attribute__((always_inline)) inline void delayMicroseconds(uint32_t us) { delay_microseconds_safe(us); }
+__attribute__((always_inline)) inline void arch_feed_wdt() { system_soft_wdt_feed(); }
+
+}  // namespace esphome
+
+#endif  // USE_ESP8266
diff --git a/esphome/core/hal/hal_host.h b/esphome/core/hal/hal_host.h
new file mode 100644
index 0000000000..145fe4ea9c
--- /dev/null
+++ b/esphome/core/hal/hal_host.h
@@ -0,0 +1,24 @@
+#pragma once
+
+#ifdef USE_HOST
+
+#include <cstdint>
+
+#define IRAM_ATTR
+#define PROGMEM
+
+namespace esphome {
+
+/// Returns true when executing inside an interrupt handler.
+/// Host has no ISR concept.
+__attribute__((always_inline)) inline bool in_isr_context() { return false; }
+
+void yield();
+void delay(uint32_t ms);
+uint32_t micros();
+uint32_t millis();
+uint64_t millis_64();
+
+}  // namespace esphome
+
+#endif  // USE_HOST
diff --git a/esphome/core/hal/hal_libretiny.h b/esphome/core/hal/hal_libretiny.h
new file mode 100644
index 0000000000..e0d92735bb
--- /dev/null
+++ b/esphome/core/hal/hal_libretiny.h
@@ -0,0 +1,93 @@
+#pragma once
+
+#ifdef USE_LIBRETINY
+
+#include <cstdint>
+
+// For the inline millis() fast paths (xTaskGetTickCount, portTICK_PERIOD_MS).
+#include <FreeRTOS.h>
+#include <task.h>
+
+#include "esphome/core/time_64.h"
+
+// IRAM_ATTR places a function in executable RAM so it is callable from an
+// ISR even while flash is busy (XIP stall, OTA, logger flash write).
+// Each family uses a section its stock linker already routes to RAM:
+// RTL8710B → .image2.ram.text, RTL8720C → .sram.text. LN882H is the
+// exception: its stock linker has no matching glob, so patch_linker.py
+// injects KEEP(*(.sram.text*)) into .flash_copysection at pre-link.
+//
+// BK72xx (all variants) are left as a no-op: their SDK wraps flash
+// operations in GLOBAL_INT_DISABLE() which masks FIQ + IRQ at the CPU for
+// the duration of every write, so no ISR fires while flash is stalled and
+// the race IRAM_ATTR guards against cannot occur. The trade-off is that
+// interrupts are delayed (not dropped) by up to ~20 ms during a sector
+// erase, but that is an SDK-level choice and cannot be changed from this
+// layer.
+#if defined(USE_BK72XX)
+#define IRAM_ATTR
+#elif defined(USE_LIBRETINY_VARIANT_RTL8710B)
+// Stock linker consumes *(.image2.ram.text*) into .ram_image2.text (> BD_RAM).
+#define IRAM_ATTR __attribute__((noinline, section(".image2.ram.text")))
+#else
+// RTL8720C: stock linker consumes *(.sram.text*) into .ram.code_text.
+// LN882H: patch_linker.py.script injects *(.sram.text*) into
+// .flash_copysection (> RAM0 AT> FLASH).
+#define IRAM_ATTR __attribute__((noinline, section(".sram.text")))
+#endif
+#define PROGMEM
+
+#ifdef USE_BK72XX
+// Declared in the Beken FreeRTOS port (portmacro.h) and built in ARM mode so
+// it is callable from Thumb code via interworking. The MRS CPSR instruction
+// is ARM-only and user code here may be built in Thumb, so in_isr_context()
+// defers to this port helper on BK72xx instead of reading CPSR inline.
+extern "C" uint32_t platform_is_in_interrupt_context(void);
+#endif
+
+// Forward decls from Arduino's <Arduino.h> for the inline wrappers below.
+// NOLINTBEGIN(google-runtime-int,readability-identifier-naming,readability-redundant-declaration)
+extern "C" void yield(void);
+extern "C" void delay(unsigned long ms);
+extern "C" unsigned long micros(void);
+extern "C" unsigned long millis(void);
+// NOLINTEND(google-runtime-int,readability-identifier-naming,readability-redundant-declaration)
+
+namespace esphome {
+
+/// Returns true when executing inside an interrupt handler.
+__attribute__((always_inline)) inline bool in_isr_context() {
+#if defined(USE_BK72XX)
+  // BK72xx is ARM968E-S (ARM9); see extern declaration above.
+  return platform_is_in_interrupt_context() != 0;
+#else
+  // Cortex-M (AmebaZ, AmebaZ2, LN882H). IPSR is the active exception number;
+  // non-zero means we're in a handler.
+  uint32_t ipsr;
+  __asm__ volatile("mrs %0, ipsr" : "=r"(ipsr));
+  return ipsr != 0;
+#endif
+}
+
+__attribute__((always_inline)) inline void yield() { ::yield(); }
+__attribute__((always_inline)) inline void delay(uint32_t ms) { ::delay(ms); }
+__attribute__((always_inline)) inline uint32_t micros() { return static_cast<uint32_t>(::micros()); }
+
+// Per-variant millis() fast path — matches MillisInternal::get().
+#if defined(USE_RTL87XX) || defined(USE_LN882X)
+static_assert(configTICK_RATE_HZ == 1000, "millis() fast path requires 1 kHz FreeRTOS tick");
+__attribute__((always_inline)) inline uint32_t millis() {
+  // xTaskGetTickCountFromISR is mandatory in interrupt context per the FreeRTOS API contract.
+  return in_isr_context() ? xTaskGetTickCountFromISR() : xTaskGetTickCount();
+}
+#elif defined(USE_BK72XX)
+static_assert(configTICK_RATE_HZ == 500, "BK72xx millis() fast path assumes 500 Hz FreeRTOS tick");
+__attribute__((always_inline)) inline uint32_t millis() { return xTaskGetTickCount() * portTICK_PERIOD_MS; }
+#else
+__attribute__((always_inline)) inline uint32_t millis() { return static_cast<uint32_t>(::millis()); }
+#endif
+__attribute__((always_inline)) inline uint64_t millis_64() { return Millis64Impl::compute(millis()); }
+
+}  // namespace esphome
+
+#endif  // USE_LIBRETINY
diff --git a/esphome/core/hal/hal_rp2040.h b/esphome/core/hal/hal_rp2040.h
new file mode 100644
index 0000000000..156ff33b86
--- /dev/null
+++ b/esphome/core/hal/hal_rp2040.h
@@ -0,0 +1,40 @@
+#pragma once
+
+#ifdef USE_RP2040
+
+#include <cstdint>
+
+#include "esphome/core/time_conversion.h"
+
+#define IRAM_ATTR __attribute__((noinline, long_call, section(".time_critical")))
+#define PROGMEM
+
+// Forward decls from Arduino's <Arduino.h> for the inline wrappers below.
+// NOLINTBEGIN(google-runtime-int,readability-identifier-naming,readability-redundant-declaration)
+extern "C" void yield(void);
+extern "C" void delay(unsigned long ms);
+extern "C" unsigned long micros(void);
+extern "C" unsigned long millis(void);
+// NOLINTEND(google-runtime-int,readability-identifier-naming,readability-redundant-declaration)
+
+// Forward decl from <pico/time.h>.
+extern "C" uint64_t time_us_64(void);
+
+namespace esphome {
+
+/// Returns true when executing inside an interrupt handler.
+__attribute__((always_inline)) inline bool in_isr_context() {
+  uint32_t ipsr;
+  __asm__ volatile("mrs %0, ipsr" : "=r"(ipsr));
+  return ipsr != 0;
+}
+
+__attribute__((always_inline)) inline void yield() { ::yield(); }
+__attribute__((always_inline)) inline void delay(uint32_t ms) { ::delay(ms); }
+__attribute__((always_inline)) inline uint32_t micros() { return static_cast<uint32_t>(::micros()); }
+__attribute__((always_inline)) inline uint32_t millis() { return micros_to_millis(::time_us_64()); }
+__attribute__((always_inline)) inline uint64_t millis_64() { return micros_to_millis<uint64_t>(::time_us_64()); }
+
+}  // namespace esphome
+
+#endif  // USE_RP2040
diff --git a/esphome/core/hal/hal_zephyr.h b/esphome/core/hal/hal_zephyr.h
new file mode 100644
index 0000000000..e28be5c775
--- /dev/null
+++ b/esphome/core/hal/hal_zephyr.h
@@ -0,0 +1,24 @@
+#pragma once
+
+#ifdef USE_ZEPHYR
+
+#include <cstdint>
+
+#define IRAM_ATTR
+#define PROGMEM
+
+namespace esphome {
+
+/// Returns true when executing inside an interrupt handler.
+/// Zephyr/nRF52: not currently consulted — wake path is platform-specific.
+__attribute__((always_inline)) inline bool in_isr_context() { return false; }
+
+void yield();
+void delay(uint32_t ms);
+uint32_t micros();
+uint32_t millis();
+uint64_t millis_64();
+
+}  // namespace esphome
+
+#endif  // USE_ZEPHYR
diff --git a/esphome/core/helpers.h b/esphome/core/helpers.h
index b2b07c57a0..355db6c7f4 100644
--- a/esphome/core/helpers.h
+++ b/esphome/core/helpers.h
@@ -20,6 +20,7 @@
 #include <strings.h>
 
 #include "esphome/core/optional.h"
+#include "esphome/core/time_conversion.h"
 
 // Backward compatibility re-export of heap-allocating helpers.
 // These functions have moved to alloc_helpers.h. External components should
@@ -833,43 +834,9 @@ template<std::integral T> constexpr uint32_t fnv1a_hash_extend(uint32_t hash, T
 constexpr uint32_t fnv1a_hash(const char *str) { return fnv1a_hash_extend(FNV1_OFFSET_BASIS, str); }
 inline uint32_t fnv1a_hash(const std::string &str) { return fnv1a_hash(str.c_str()); }
 
-/// Convert a 64-bit microsecond count to milliseconds without calling
-/// __udivdi3 (software 64-bit divide, ~1200 ns on Xtensa @ 240 MHz).
-///
-/// Returns uint32_t by default (for millis()), or uint64_t when requested
-/// (for millis_64()). The only difference is whether hi * Q is truncated
-/// to 32 bits or widened to 64.
-///
-/// On 32-bit targets, GCC does not optimize 64-bit constant division into a
-/// multiply-by-reciprocal. Since 1000 = 8 * 125, we first right-shift by 3
-/// (free divide-by-8), then use the Euclidean division identity to decompose
-/// the remaining 64-bit divide-by-125 into a single 32-bit division:
-///
-///   floor(us / 1000) = floor(floor(us / 8) / 125)    [exact for integers]
-///   2^32 = Q * 125 + R  (34359738 * 125 + 46)
-///   (hi * 2^32 + lo) / 125 = hi * Q + (hi * R + lo) / 125
-///
-/// GCC optimizes the remaining 32-bit "/ 125U" into a multiply-by-reciprocal
-/// (mulhu + shift), so no division instruction is emitted.
-///
-/// Safe for us up to ~3.2e18 (~101,700 years of microseconds).
-///
-/// See: https://en.wikipedia.org/wiki/Euclidean_division
-/// See: https://ridiculousfish.com/blog/posts/labor-of-division-episode-iii.html
-template<typename ReturnT = uint32_t> inline constexpr ESPHOME_ALWAYS_INLINE ReturnT micros_to_millis(uint64_t us) {
-  constexpr uint32_t d = 125U;
-  constexpr uint32_t q = static_cast<uint32_t>((1ULL << 32) / d);  // 34359738
-  constexpr uint32_t r = static_cast<uint32_t>((1ULL << 32) % d);  // 46
-  // 1000 = 8 * 125; divide-by-8 is a free shift
-  uint64_t x = us >> 3;
-  uint32_t lo = static_cast<uint32_t>(x);
-  uint32_t hi = static_cast<uint32_t>(x >> 32);
-  // Combine remainder term: hi * (2^32 % 125) + lo
-  uint32_t adj = hi * r + lo;
-  // If adj overflowed, the true value is 2^32 + adj; apply the identity again
-  // static_cast<ReturnT>(hi) widens to 64-bit when ReturnT=uint64_t, preserving upper bits of hi*q
-  return static_cast<ReturnT>(hi) * q + (adj < lo ? (adj + r) / d + q : adj / d);
-}
+// micros_to_millis<>() lives in its own lightweight header so hal.h can pull it
+// in for inline millis_64() without forcing every TU that includes hal.h to
+// also include the rest of helpers.h.
 
 /// Return a random 32-bit unsigned integer.
 /// Not thread-safe. Must only be called from the main loop.
diff --git a/esphome/core/time_64.h b/esphome/core/time_64.h
index d82373dbfe..f66f9afddb 100644
--- a/esphome/core/time_64.h
+++ b/esphome/core/time_64.h
@@ -6,8 +6,6 @@
 #include <cstdint>
 #include <limits>
 
-#include "esphome/core/helpers.h"
-
 namespace esphome {
 
 class Scheduler;
@@ -24,7 +22,9 @@ class Millis64Impl {
   static uint32_t last_millis;
   static uint16_t millis_major;
 
-  static inline uint64_t ESPHOME_ALWAYS_INLINE compute(uint32_t now) {
+  // Raw __attribute__((always_inline)) (not ESPHOME_ALWAYS_INLINE) so this
+  // header does not need to pull helpers.h.
+  static inline uint64_t __attribute__((always_inline)) compute(uint32_t now) {
     // Half the 32-bit range - used to detect rollovers vs normal time progression
     static constexpr uint32_t HALF_MAX_UINT32 = std::numeric_limits<uint32_t>::max() / 2;
 
diff --git a/esphome/core/time_conversion.h b/esphome/core/time_conversion.h
new file mode 100644
index 0000000000..e9060c0626
--- /dev/null
+++ b/esphome/core/time_conversion.h
@@ -0,0 +1,46 @@
+#pragma once
+
+#include <cstdint>
+
+namespace esphome {
+
+/// Convert a 64-bit microsecond count to milliseconds without calling
+/// __udivdi3 (software 64-bit divide, ~1200 ns on Xtensa @ 240 MHz).
+///
+/// Returns uint32_t by default (for millis()), or uint64_t when requested
+/// (for millis_64()). The only difference is whether hi * Q is truncated
+/// to 32 bits or widened to 64.
+///
+/// On 32-bit targets, GCC does not optimize 64-bit constant division into a
+/// multiply-by-reciprocal. Since 1000 = 8 * 125, we first right-shift by 3
+/// (free divide-by-8), then use the Euclidean division identity to decompose
+/// the remaining 64-bit divide-by-125 into a single 32-bit division:
+///
+///   floor(us / 1000) = floor(floor(us / 8) / 125)    [exact for integers]
+///   2^32 = Q * 125 + R  (34359738 * 125 + 46)
+///   (hi * 2^32 + lo) / 125 = hi * Q + (hi * R + lo) / 125
+///
+/// GCC optimizes the remaining 32-bit "/ 125U" into a multiply-by-reciprocal
+/// (mulhu + shift), so no division instruction is emitted.
+///
+/// Safe for us up to ~3.2e18 (~101,700 years of microseconds).
+///
+/// See: https://en.wikipedia.org/wiki/Euclidean_division
+/// See: https://ridiculousfish.com/blog/posts/labor-of-division-episode-iii.html
+template<typename ReturnT = uint32_t>
+__attribute__((always_inline)) inline constexpr ReturnT micros_to_millis(uint64_t us) {
+  constexpr uint32_t d = 125U;
+  constexpr uint32_t q = static_cast<uint32_t>((1ULL << 32) / d);  // 34359738
+  constexpr uint32_t r = static_cast<uint32_t>((1ULL << 32) % d);  // 46
+  // 1000 = 8 * 125; divide-by-8 is a free shift
+  uint64_t x = us >> 3;
+  uint32_t lo = static_cast<uint32_t>(x);
+  uint32_t hi = static_cast<uint32_t>(x >> 32);
+  // Combine remainder term: hi * (2^32 % 125) + lo
+  uint32_t adj = hi * r + lo;
+  // If adj overflowed, the true value is 2^32 + adj; apply the identity again
+  // static_cast<ReturnT>(hi) widens to 64-bit when ReturnT=uint64_t, preserving upper bits of hi*q
+  return static_cast<ReturnT>(hi) * q + (adj < lo ? (adj + r) / d + q : adj / d);
+}
+
+}  // namespace esphome