Updated default PSRAM options (ESP-IDF 5.5+) + documentation
This commit is contained in:
1 parent
9ddd618da7
commit
c9162e659e
1 file changed
+215
@@ -0,0 +1,215 @@
|
||||
# YamBMS - PSRAM options
|
||||
|
||||
[](https://www.gnu.org/licenses/gpl-3.0)
|
||||
[](https://github.com/Sleeper85/esphome-yambms/releases/latest)
|
||||

|
||||

|
||||

|
||||
|
||||
Reference for `board_options_PSRAM_options.yaml`, the shared `sdkconfig_options`
|
||||
included by every `board_options_PSRAM_*.yaml` board file.
|
||||
|
||||
|
||||
## Which boards have PSRAM
|
||||
|
||||
PSRAM is a **property of the board or module, not of the chip family**. Two
|
||||
boards built on the same chip may or may not have it.
|
||||
|
||||
| Chip | PSRAM | Modes | Notes |
|
||||
|---|---|---|---|
|
||||
| ESP32 | On some modules (WROVER and similar; WROOM has none) | Quad only | 8 MB chips expose only 4 MB through the cache window at a time |
|
||||
| ESP32-S2 | On some modules | Quad only | |
|
||||
| ESP32-S3 | On some modules (N8R2, N16R8 …) | Quad or octal | The `R` suffix in the module reference indicates PSRAM |
|
||||
| ESP32-C3 / C6 / H2 | None | — | These options are inert |
|
||||
|
||||
**Check your module before choosing a mode.** Declaring `octal` on a board with
|
||||
quad PSRAM — or on a chip that has no octal support at all — makes PSRAM
|
||||
initialisation fail. It does not produce a clear error message; it shows up
|
||||
later as random cache errors and unstable behaviour. The ESP-IDF boot log
|
||||
reports what was actually detected.
|
||||
|
||||
On the original ESP32, 80 MHz PSRAM has additional constraints tied to the flash
|
||||
clock, and early chip revisions require a cache workaround that ESP-IDF enables
|
||||
automatically. If a board misbehaves at 80 MHz, 40 MHz is the safe fallback.
|
||||
|
||||
A board file declares the mode and includes this shared options file:
|
||||
|
||||
```yaml
|
||||
psram:
|
||||
mode: octal
|
||||
speed: 80MHz
|
||||
|
||||
packages:
|
||||
psram_options: !include board_options_PSRAM_options.yaml
|
||||
```
|
||||
|
||||
If a board has no PSRAM, every option below is silently ignored. They are
|
||||
harmless, but they do nothing.
|
||||
|
||||
## Why these options exist
|
||||
|
||||
An ESP32 with PSRAM has two separate pools of RAM:
|
||||
|
||||
| Pool | Size | Speed | Used for |
|
||||
|---|---|---|---|
|
||||
| Internal RAM | A few hundred KB, fixed by the chip | Fast | Everything by default; the only pool usable for DMA |
|
||||
| PSRAM | 2–16 MB depending on the module | Slower | Optional overflow, must be explicitly enabled |
|
||||
|
||||
Internal RAM is the scarce resource. A YamBMS master with 16 BMS creates roughly
|
||||
1,400 entity objects on top of WiFi, the native API and several peripherals, and
|
||||
internal RAM runs out long before PSRAM does.
|
||||
|
||||
Every option below does one thing: **move something out of internal RAM and into
|
||||
PSRAM.**
|
||||
|
||||
> **Reference build.** The figures quoted in this document come from a 16-BMS
|
||||
> master: ESP32-S3, octal PSRAM at 80 MHz, ESPHome 2026.7.3, ESP-IDF 5.5.5.
|
||||
>
|
||||
> ```
|
||||
> DIRAM 202,299 / 341,760 (59.2 %) -> 139,461 B free for the heap
|
||||
> ```
|
||||
>
|
||||
> They are orders of magnitude, not universal constants. The original ESP32 in
|
||||
> particular splits its internal RAM into separate instruction and data regions
|
||||
> instead of the unified DIRAM pool the S3 uses, so its size report looks
|
||||
> different. Compare against your own baseline rather than against these numbers.
|
||||
|
||||
## The options
|
||||
|
||||
### Moving the network stack to PSRAM
|
||||
|
||||
```yaml
|
||||
CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY: y
|
||||
CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP: y
|
||||
```
|
||||
|
||||
**These two must be kept together.** The first turns `EXT_RAM_BSS_ATTR` in
|
||||
ESP-IDF's `esp_attr.h` into a real section directive — without it the macro
|
||||
expands to nothing. The second makes the network stack actually use it.
|
||||
Removing either one cancels the benefit of both.
|
||||
|
||||
**Measured gain on the reference build: 12,308 bytes of internal RAM.** The
|
||||
symbols moved are the socket table, `dns_table`, `dns_requests`, the `tcpip_*`
|
||||
and `sntp_*` globals, and `select_cb_list`. Without these options internal
|
||||
`.bss` would be 133,612 instead of 121,304, pushing DIRAM usage from 59.2 % to
|
||||
62.8 %.
|
||||
|
||||
**Why this is safe.** Data in PSRAM is unreachable while the flash cache is
|
||||
disabled, which is why PSRAM placement is normally risky. That only affects
|
||||
interrupt handlers flagged to run from IRAM. LWIP has none — these globals are
|
||||
touched exclusively from the `tcpip` task, in task context, where the cache is
|
||||
always available.
|
||||
|
||||
**Cost:** marginally slower socket and DNS access. Irrelevant at ESPHome traffic
|
||||
levels.
|
||||
|
||||
> **Reading the size report:** this segment is reported by `esp_idf_size` under
|
||||
> *Flash Data / .bss*, not under internal RAM. That is a tooling artefact —
|
||||
> flash `.rodata` and PSRAM share the same address window. The data really is in
|
||||
> PSRAM.
|
||||
|
||||
### Internal RAM reservation
|
||||
|
||||
```yaml
|
||||
CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL: "65536"
|
||||
```
|
||||
|
||||
Bytes kept exclusively for allocations that cannot live in PSRAM — DMA buffers
|
||||
and internal-only requests. Once free internal RAM drops to this level, generic
|
||||
allocations fall back to PSRAM instead of starving the reserve.
|
||||
|
||||
ESP-IDF's default is 32,768. It is raised here because a YamBMS master runs
|
||||
WiFi, the native API and several UART / SPI / CAN peripherals concurrently, all
|
||||
of which need DMA-capable memory.
|
||||
|
||||
On a chip with less internal RAM than an S3, 65,536 is a large share of the
|
||||
total. If free heap gets tight, this is one of the first values to reconsider.
|
||||
|
||||
### Allocation size threshold
|
||||
|
||||
```yaml
|
||||
CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL: "4096"
|
||||
```
|
||||
|
||||
Allocations up to this size go to internal RAM first; larger ones go straight to
|
||||
PSRAM. ESP-IDF's default is 16,384.
|
||||
|
||||
**Tuning note.** Entity objects are typically 100–400 bytes, so at 4096 they all
|
||||
still land in internal RAM. On a node short on internal memory, lowering this to
|
||||
`"512"` pushes them into PSRAM and gives internal RAM back, at the cost of
|
||||
slower access to every entity. Measure the free heap before and after — this is
|
||||
a trade-off, not a free win.
|
||||
|
||||
DMA buffers request `MALLOC_CAP_DMA` explicitly and stay internal regardless of
|
||||
this value.
|
||||
|
||||
### Bluetooth (BLE BMS only)
|
||||
|
||||
```yaml
|
||||
CONFIG_BT_ALLOCATION_FROM_SPIRAM_FIRST: y
|
||||
CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY: y
|
||||
```
|
||||
|
||||
**These two must also be kept together**, for the same reason as the pair above.
|
||||
`BT_BLE_DYNAMIC_ENV_MEMORY` moves the Bluedroid host environment from static
|
||||
`.bss` to dynamic allocation; `BT_ALLOCATION_FROM_SPIRAM_FIRST` sends those
|
||||
allocations to PSRAM first. Alone, the first only shifts the cost from `.bss` to
|
||||
the internal heap, and the second has nothing to redirect.
|
||||
|
||||
**Inert on RS485 / CAN-only builds.** Both are children of `CONFIG_BT_ENABLED`
|
||||
in ESP-IDF's Kconfig tree, so they are dropped entirely when the Bluetooth
|
||||
component is not compiled. Verified on a 16-BMS RS485 build: zero `CONFIG_BT_`
|
||||
lines in the generated `sdkconfig`, zero Bluedroid symbols in the ELF, zero
|
||||
bytes consumed.
|
||||
|
||||
**Caveat.** `BT_BLE_DYNAMIC_ENV_MEMORY` has a history of reliability reports
|
||||
upstream. If BLE users hit crashes, remove this one first when bisecting;
|
||||
`BT_ALLOCATION_FROM_SPIRAM_FIRST` alone is far less controversial.
|
||||
|
||||
**Note for BLE nodes.** The BLE controller needs internal RAM that PSRAM cannot
|
||||
replace — buffers accessed during radio windows. A BLE node therefore has less
|
||||
free internal RAM than the reference figures above.
|
||||
|
||||
## Verifying what actually applied
|
||||
|
||||
The generated `sdkconfig` is the only source of truth. ESPHome manages some
|
||||
symbols itself, and those cannot be overridden from `sdkconfig_options`.
|
||||
|
||||
```bash
|
||||
grep -E "SPIRAM|COMPILER_OPTIMIZATION" .esphome/build/<node>/sdkconfig.<node>
|
||||
```
|
||||
|
||||
To confirm that data really landed in PSRAM, look for the external RAM section
|
||||
in the linker map. This works on any chip:
|
||||
|
||||
```bash
|
||||
grep -n '\.ext_ram\.bss' .esphome/build/<node>/build/<node>.map | head
|
||||
```
|
||||
|
||||
If you prefer to inspect symbols directly, the address tells you where a symbol
|
||||
lives — but the windows are chip-specific:
|
||||
|
||||
| Chip | Internal RAM | PSRAM |
|
||||
|---|---|---|
|
||||
| ESP32 | `0x3FF…` | `0x3F8…` – `0x3FB…` |
|
||||
| ESP32-S3 | `0x3FC…` | `0x3C…` – `0x3D…` |
|
||||
|
||||
```bash
|
||||
NM=$(find ~/.cache/esphome/idf/tools -name '*-elf-nm' | head -1)
|
||||
$NM -nSC .esphome/build/<node>/build/<node>.elf | awk 'tolower($3)=="b"'
|
||||
```
|
||||
|
||||
The compile size report is the quickest regression check. On the reference
|
||||
build, internal RAM usage was 202,299 bytes (59.19 %). Any unexpected change
|
||||
after editing these options means something behaved differently than documented
|
||||
here — investigate before shipping.
|
||||
|
||||
## Note on `loop_task_stack_size`
|
||||
|
||||
This option is **not** part of this file, and is documented separately.
|
||||
|
||||
It is unrelated to PSRAM: it sizes the stack of the FreeRTOS task that runs
|
||||
`setup()` and the main loop, and the required value depends on entity count, not
|
||||
on available memory. It applies on every ESP32, with or without PSRAM, and
|
||||
raising it consumes internal RAM that a board without PSRAM cannot recover
|
||||
elsewhere.
|
||||
Reference in new issue
Block a user