From c156dbc6d647f367bef02b8a0bdd4b8707a7753d Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@home-assistant.io>
Date: Tue, 18 Nov 2025 14:03:04 -0600
Subject: [PATCH] [core] Document threading model rationale in ThreadModel enum

---
 esphome/const.py | 30 ++++++++++++++++--------------
 1 file changed, 16 insertions(+), 14 deletions(-)

diff --git a/esphome/const.py b/esphome/const.py
index 25cec98bf0..2b6b60d395 100644
--- a/esphome/const.py
+++ b/esphome/const.py
@@ -38,25 +38,27 @@ class Framework(StrEnum):
 class ThreadModel(StrEnum):
     """Threading model identifiers for ESPHome scheduler.
 
-    ESPHome supports three threading models based on platform capabilities:
+    ESPHome currently uses three threading models based on platform capabilities:
 
-    SINGLE: Single-threaded platforms (ESP8266, RP2040)
-        - No FreeRTOS or other RTOS
+    SINGLE:
+        - Single-threaded platforms (ESP8266, RP2040)
+        - No RTOS task switching
         - No concurrent access to scheduler data structures
-        - No atomics or locks needed
+        - No atomics or locks required
         - Minimal overhead
 
-    MULTI_NO_ATOMICS: Multi-threaded platforms without hardware atomic support (LibreTiny)
-        - Uses FreeRTOS or other RTOS with multiple tasks
-        - CPU lacks atomic instructions (e.g., ARM968E-S has no LDREX/STREX)
-        - libatomic is not linked (would add 4-8KB flash overhead)
-        - Uses explicit FreeRTOS mutex locking for synchronization
+    MULTI_NO_ATOMICS:
+        - Multi-threaded platforms without hardware atomic RMW support (e.g. LibreTiny BK7231N)
+        - Uses FreeRTOS or another RTOS with multiple tasks
+        - CPU lacks exclusive load/store instructions (ARM968E-S has no LDREX/STREX)
+        - std::atomic cannot provide lock-free RMW; libatomic is avoided to save flash (4–8 KB)
+        - Scheduler uses explicit FreeRTOS mutexes for synchronization
 
-    MULTI_ATOMICS: Multi-threaded platforms with hardware atomic support (ESP32, Host)
-        - Uses FreeRTOS or other RTOS with multiple tasks
-        - CPU has native atomic instructions (e.g., ESP32 has S32C1I, ARM Cortex has LDREX/STREX)
-        - Uses std::atomic for lock-free synchronization
-        - Better performance through reduced lock contention
+    MULTI_ATOMICS:
+        - Multi-threaded platforms with hardware atomic RMW support (ESP32, Cortex-M, Host)
+        - CPU provides native atomic instructions (ESP32 S32C1I, ARM LDREX/STREX)
+        - std::atomic is used for lock-free synchronization
+        - Reduced contention and better performance
     """
 
     SINGLE = "ESPHOME_THREAD_SINGLE"