From 707337d27a7a2e9ceebd5404f4afb9e915aca516 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@home-assistant.io>
Date: Mon, 5 Jan 2026 14:33:40 -1000
Subject: [PATCH] tweak

---
 .../components/logger/task_log_buffer_esp32.h    | 16 ++++++++++++++++
 esphome/components/logger/task_log_buffer_host.h | 12 ++++++++----
 2 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/esphome/components/logger/task_log_buffer_esp32.h b/esphome/components/logger/task_log_buffer_esp32.h
index bdf013b0a9..fde9bd60d5 100644
--- a/esphome/components/logger/task_log_buffer_esp32.h
+++ b/esphome/components/logger/task_log_buffer_esp32.h
@@ -15,6 +15,22 @@
 
 namespace esphome::logger {
 
+/**
+ * @brief Task log buffer for ESP32 platform using FreeRTOS ring buffer.
+ *
+ * Threading Model: Multi-Producer Single-Consumer (MPSC)
+ * - Multiple FreeRTOS tasks can safely call send_message_thread_safe() concurrently
+ * - Only the main loop task calls borrow_message_main_loop() and release_message_main_loop()
+ *
+ * This uses the FreeRTOS ring buffer (RINGBUF_TYPE_NOSPLIT) which provides
+ * built-in thread-safety for the MPSC pattern. The ring buffer ensures
+ * message integrity - each message is stored contiguously.
+ *
+ * Design:
+ * - Variable-size messages with header + text stored contiguously
+ * - FreeRTOS ring buffer handles synchronization internally
+ * - Atomic counter for fast has_messages() check without ring buffer lock
+ */
 class TaskLogBuffer {
  public:
   // Structure for a log message header (text data follows immediately after)
diff --git a/esphome/components/logger/task_log_buffer_host.h b/esphome/components/logger/task_log_buffer_host.h
index 4db4a5dbc6..8a9e9a6455 100644
--- a/esphome/components/logger/task_log_buffer_host.h
+++ b/esphome/components/logger/task_log_buffer_host.h
@@ -19,15 +19,19 @@ namespace esphome::logger {
 /**
  * @brief Lock-free task log buffer for host platform.
  *
- * This implements a Multi-Producer Single-Consumer (MPSC) lock-free ring buffer
- * for log messages on the host platform. It uses atomic operations for thread-safety
+ * Threading Model: Multi-Producer Single-Consumer (MPSC)
+ * - Multiple threads can safely call send_message_thread_safe() concurrently
+ * - Only the main loop thread calls get_message_main_loop() and release_message_main_loop()
+ *
+ * This implements a lock-free ring buffer for log messages on the host platform.
+ * It uses atomic compare-and-swap (CAS) operations for thread-safe slot reservation
  * without requiring mutexes in the hot path.
  *
  * Design:
  * - Fixed number of pre-allocated message slots to avoid dynamic allocation
  * - Each slot contains a header and fixed-size text buffer
- * - Atomic indices for lock-free push/pop operations
- * - Thread-safe for multiple producers, single consumer (main loop)
+ * - Atomic CAS for slot reservation allows multiple producers without locks
+ * - Single consumer (main loop) processes messages in order
  *
  * Host platform has much more memory than embedded devices, so we use larger
  * buffer sizes for better log message handling.