[esp32] Document freertos_in_iram advanced option

content/components/esp32.md

@@ -198,6 +198,19 @@ The following options disable unused VFS features to save flash memory:
   future storage components) automatically enable it regardless of this setting. Disabling this saves approximately 0.5 KB+
   of flash. Defaults to `true` (VFS directory support disabled to save flash).
 
+**FreeRTOS Memory Options:**
+
+- **freertos_in_iram** (*Optional*, boolean): Keep FreeRTOS functions in IRAM instead of moving them to flash. By default,
+  non-ISR FreeRTOS functions are placed in flash to save up to 8 KB of IRAM. ISR-safe functions (`FromISR` variants) always
+  remain in IRAM. Testing on ESP-IDF 5.5 with Bluetooth proxies shows no performance difference thanks to fast XIP (execute
+  in place) from flash. Bluetooth proxies are one of the most IRAM-intensive and timing-sensitive use cases, which is likely
+  why Espressif made this the default in IDF 6.0. This matches
+  the default behavior in ESP-IDF 6.0 where `CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH` is removed and replaced by
+  `CONFIG_FREERTOS_IN_IRAM` to restore the old behavior (see [ESP-IDF 6.0 breaking changes](https://github.com/espressif/esp-idf/issues/17052)
+  and [migration guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/migration-guides/release-6.x/6.0/system.html#memory-placement)).
+  Set to `true` only if you encounter issues with code that incorrectly calls FreeRTOS functions from ISRs with flash cache
+  disabled. Defaults to `false` (FreeRTOS functions in flash to save IRAM).
+
 Some options can be disabled to save flash memory without affecting typical ESPHome functionality. The performance
 options (defaulting to `true`  ) improve socket operation performance but can be disabled if you need better
 multi-threaded scalability (which is uncommon since ESPHome uses an event loop).