Task log buffer for ESP32 platform using FreeRTOS ring buffer. More...

#include <task_log_buffer_esp32.h>

Data Structures
struct	LogMessage

Public Member Functions
	TaskLogBuffer ()

	~TaskLogBuffer ()

bool	borrow_message_main_loop (LogMessage *&message, uint16_t &text_length)

void	release_message_main_loop ()

bool	send_message_thread_safe (uint8_t level, const char tag, uint16_t line, const char thread_name, const char *format, va_list args)

bool HOT	has_messages () const

	TaskLogBuffer ()=default

bool	borrow_message_main_loop (LogMessage *&message, uint16_t &text_length)

void	release_message_main_loop ()

bool	send_message_thread_safe (uint8_t level, const char tag, uint16_t line, const char thread_name, const char *format, va_list args)

bool HOT	has_messages () const

	TaskLogBuffer ()

	~TaskLogBuffer ()

bool	borrow_message_main_loop (LogMessage *&message, uint16_t &text_length)

void	release_message_main_loop ()

bool	send_message_thread_safe (uint8_t level, const char tag, uint16_t line, const char thread_name, const char *format, va_list args)

bool HOT	has_messages () const

	TaskLogBuffer ()

	~TaskLogBuffer ()=default

bool HOT	has_messages ()

bool	borrow_message_main_loop (LogMessage *&message, uint16_t &text_length)

void	release_message_main_loop ()

bool	send_message_thread_safe (uint8_t level, const char tag, uint16_t line, const char thread_name, const char *format, va_list args)

Static Public Member Functions
static constexpr size_t	size ()

static constexpr size_t	size ()

static constexpr size_t	size ()

static constexpr size_t	size ()

Static Public Attributes
static constexpr uint8_t	PADDING_MARKER_LEVEL = 0xFF

Protected Attributes
uint32_t	buf_storage_ [BUF_WORD_COUNT]

mpsc_pbuf_buffer_config	mpsc_config_ {}

mpsc_pbuf_buffer	log_buffer_ {}

const mpsc_pbuf_generic *	current_token_ {}

Static Protected Attributes
static constexpr size_t	BUF_WORD_COUNT = (ESPHOME_TASK_LOG_BUFFER_SIZE + 3) / sizeof(uint32_t)

Detailed Description

Task log buffer for ESP32 platform using FreeRTOS ring buffer.

Task log buffer for LibreTiny platform using mutex-protected circular buffer.

Lock-free task log buffer for host platform.

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

Threading Model: Multi-Producer Single-Consumer (MPSC)

Multiple threads can safely call send_message_thread_safe() concurrently
Only the main loop thread calls borrow_message_main_loop() and release_message_main_loop()

Producers (multiple threads) Consumer (main loop only) │ │ ▼ ▼ acquire_write_slot_() bool borrow_message_main_loop() CAS on reserve_index_ read write_index_ │ check ready flag ▼ │ write to slot (exclusive) ▼ │ read slot data ▼ │ commit_write_slot_() ▼ set ready=true release_message_main_loop() advance write_index_ set ready=false advance read_index_

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 CAS for slot reservation allows multiple producers without locks
Single consumer (main loop) processes messages in order

Why This Is Critical: Without thread-safe logging, when a non-main task logs a message, it would directly call the logger which builds a protobuf message in a shared buffer. If this happens while the main loop is also using that buffer (e.g., sending API responses), the buffer gets corrupted, sending garbage to all connected API clients and breaking their connections. This buffer ensures log messages from other tasks are queued safely and processed only from the main loop.

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 a simple circular buffer protected by a FreeRTOS mutex. Unlike ESP32, LibreTiny lacks hardware atomic support (ARM968E-S has no LDREX/STREX), so we use a volatile counter for fast has_messages() checks instead of atomics.

Design:

Variable-size messages with header + text stored contiguously (NOSPLIT style)
FreeRTOS mutex protects all buffer operations
Volatile counter enables fast has_messages() without lock overhead
If message doesn't fit at end, padding is added and message wraps to start

Definition at line 18 of file task_log_buffer_zephyr.h.

Constructor & Destructor Documentation

◆ TaskLogBuffer() [1/4]

esphome::logger::TaskLogBuffer::TaskLogBuffer ( )

Definition at line 10 of file task_log_buffer_esp32.cpp.

◆ ~TaskLogBuffer() [1/3]

esphome::logger::TaskLogBuffer::~TaskLogBuffer ( )

Definition at line 17 of file task_log_buffer_esp32.cpp.

◆ TaskLogBuffer() [2/4]

esphome::logger::TaskLogBuffer::TaskLogBuffer ( )

default

◆ TaskLogBuffer() [3/4]

esphome::logger::TaskLogBuffer::TaskLogBuffer ( )

◆ ~TaskLogBuffer() [2/3]

esphome::logger::TaskLogBuffer::~TaskLogBuffer ( )

◆ TaskLogBuffer() [4/4]

esphome::logger::TaskLogBuffer::TaskLogBuffer ( )

◆ ~TaskLogBuffer() [3/3]

esphome::logger::TaskLogBuffer::~TaskLogBuffer ( )

default

Member Function Documentation

◆ borrow_message_main_loop() [1/4]

bool esphome::logger::TaskLogBuffer::borrow_message_main_loop	(	LogMessage *&	message,
		uint16_t &	text_length )

Definition at line 24 of file task_log_buffer_esp32.cpp.

◆ borrow_message_main_loop() [2/4]

bool esphome::logger::TaskLogBuffer::borrow_message_main_loop	(	LogMessage *&	message,
		uint16_t &	text_length )

◆ borrow_message_main_loop() [3/4]

bool esphome::logger::TaskLogBuffer::borrow_message_main_loop	(	LogMessage *&	message,
		uint16_t &	text_length )

◆ borrow_message_main_loop() [4/4]

bool esphome::logger::TaskLogBuffer::borrow_message_main_loop	(	LogMessage *&	message,
		uint16_t &	text_length )

◆ has_messages() [1/4]

bool HOT esphome::logger::TaskLogBuffer::has_messages ( )

inline

Definition at line 40 of file task_log_buffer_zephyr.h.

◆ has_messages() [2/4]

bool HOT esphome::logger::TaskLogBuffer::has_messages ( ) const

inline

Definition at line 63 of file task_log_buffer_esp32.h.

◆ has_messages() [3/4]

bool HOT esphome::logger::TaskLogBuffer::has_messages ( ) const

inline

Definition at line 88 of file task_log_buffer_host.h.

◆ has_messages() [4/4]

bool HOT esphome::logger::TaskLogBuffer::has_messages ( ) const

inline

Definition at line 77 of file task_log_buffer_libretiny.h.

◆ release_message_main_loop() [1/4]

void esphome::logger::TaskLogBuffer::release_message_main_loop ( )

Definition at line 43 of file task_log_buffer_esp32.cpp.

◆ release_message_main_loop() [2/4]

void esphome::logger::TaskLogBuffer::release_message_main_loop ( )

◆ release_message_main_loop() [3/4]

void esphome::logger::TaskLogBuffer::release_message_main_loop ( )

◆ release_message_main_loop() [4/4]

void esphome::logger::TaskLogBuffer::release_message_main_loop ( )

◆ send_message_thread_safe() [1/4]

bool esphome::logger::TaskLogBuffer::send_message_thread_safe	(	uint8_t	level,
		const char *	tag,
		uint16_t	line,
		const char *	thread_name,
		const char *	format,
		va_list	args )

Definition at line 53 of file task_log_buffer_esp32.cpp.

◆ send_message_thread_safe() [2/4]

bool esphome::logger::TaskLogBuffer::send_message_thread_safe	(	uint8_t	level,
		const char *	tag,
		uint16_t	line,
		const char *	thread_name,
		const char *	format,
		va_list	args )

◆ send_message_thread_safe() [3/4]

bool esphome::logger::TaskLogBuffer::send_message_thread_safe	(	uint8_t	level,
		const char *	tag,
		uint16_t	line,
		const char *	thread_name,
		const char *	format,
		va_list	args )

◆ send_message_thread_safe() [4/4]

bool esphome::logger::TaskLogBuffer::send_message_thread_safe	(	uint8_t	level,
		const char *	tag,
		uint16_t	line,
		const char *	thread_name,
		const char *	format,
		va_list	args )

◆ size() [1/4]

static constexpr size_t esphome::logger::TaskLogBuffer::size ( )

inlinestaticconstexpr

Definition at line 68 of file task_log_buffer_esp32.h.

◆ size() [2/4]

static constexpr size_t esphome::logger::TaskLogBuffer::size ( )

inlinestaticconstexpr

Definition at line 93 of file task_log_buffer_host.h.

◆ size() [3/4]

static constexpr size_t esphome::logger::TaskLogBuffer::size ( )

inlinestaticconstexpr

Definition at line 80 of file task_log_buffer_libretiny.h.

◆ size() [4/4]

static constexpr size_t esphome::logger::TaskLogBuffer::size ( )

inlinestaticconstexpr

Definition at line 43 of file task_log_buffer_zephyr.h.

Field Documentation

◆ buf_storage_

uint32_t esphome::logger::TaskLogBuffer::buf_storage_[BUF_WORD_COUNT]

protected

Definition at line 58 of file task_log_buffer_zephyr.h.

◆ BUF_WORD_COUNT

size_t esphome::logger::TaskLogBuffer::BUF_WORD_COUNT = (ESPHOME_TASK_LOG_BUFFER_SIZE + 3) / sizeof(uint32_t)

staticconstexprprotected

Definition at line 57 of file task_log_buffer_zephyr.h.

◆ current_token_

const mpsc_pbuf_generic* esphome::logger::TaskLogBuffer::current_token_ {}

protected

Definition at line 61 of file task_log_buffer_zephyr.h.

◆ log_buffer_

mpsc_pbuf_buffer esphome::logger::TaskLogBuffer::log_buffer_ {}

protected

Definition at line 60 of file task_log_buffer_zephyr.h.

◆ mpsc_config_

mpsc_pbuf_buffer_config esphome::logger::TaskLogBuffer::mpsc_config_ {}

protected

Definition at line 59 of file task_log_buffer_zephyr.h.

◆ PADDING_MARKER_LEVEL

uint8_t esphome::logger::TaskLogBuffer::PADDING_MARKER_LEVEL = 0xFF

staticconstexpr

Definition at line 60 of file task_log_buffer_libretiny.h.

The documentation for this class was generated from the following files:

esphome/components/logger/task_log_buffer_esp32.h
esphome/components/logger/task_log_buffer_host.h
esphome/components/logger/task_log_buffer_libretiny.h
esphome/components/logger/task_log_buffer_zephyr.h
esphome/components/logger/task_log_buffer_esp32.cpp
esphome/components/logger/task_log_buffer_host.cpp
esphome/components/logger/task_log_buffer_libretiny.cpp
esphome/components/logger/task_log_buffer_zephyr.cpp

Data Structures

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ TaskLogBuffer() [1/4]

◆ ~TaskLogBuffer() [1/3]

◆ TaskLogBuffer() [2/4]

◆ TaskLogBuffer() [3/4]

◆ ~TaskLogBuffer() [2/3]

◆ TaskLogBuffer() [4/4]

◆ ~TaskLogBuffer() [3/3]

Member Function Documentation

◆ borrow_message_main_loop() [1/4]

◆ borrow_message_main_loop() [2/4]

◆ borrow_message_main_loop() [3/4]

◆ borrow_message_main_loop() [4/4]

◆ has_messages() [1/4]

◆ has_messages() [2/4]

◆ has_messages() [3/4]

◆ has_messages() [4/4]

◆ release_message_main_loop() [1/4]

◆ release_message_main_loop() [2/4]

◆ release_message_main_loop() [3/4]

◆ release_message_main_loop() [4/4]

◆ send_message_thread_safe() [1/4]

◆ send_message_thread_safe() [2/4]

◆ send_message_thread_safe() [3/4]

◆ send_message_thread_safe() [4/4]

◆ size() [1/4]

◆ size() [2/4]

◆ size() [3/4]

◆ size() [4/4]

Field Documentation

◆ buf_storage_

◆ BUF_WORD_COUNT

◆ current_token_

◆ log_buffer_

◆ mpsc_config_

◆ PADDING_MARKER_LEVEL