Gate every firmware build on runtime RAM and share nRF52 mOTA storage

This commit is contained in:
mikecarper committed 2026-09-08 02:09:26 -07:00
1 parent 1b6a9dcb6a
commit aa20e9278e
22 files changed
+1037 -36

No files matched your search

+8 -7
View File
@@ -12,7 +12,7 @@ A reboot clears it.
| ESP32 with configured PSRAM | 512 |
| ESP32 without PSRAM | 256 |
| nRF52840 | 256 |
| T096 Full Companion with the memory correction | 256 normally; 128 while mOTA owns shared storage |
| nRF52 Full Companion with the memory correction | 256 normally; 128 while mOTA owns shared storage |
| RP2040 | 256 |
| STM32 | 16 |
| Known constrained classic ESP32 target override | 128 |
@@ -26,8 +26,9 @@ Meshadventurer SX1262 and SX1268 Full Companion use 16 frames together with 100
contacts and 30 group channels; their ordinary transport-specific images keep
128 frames and 40 channels.
The [T096 Full memory correction](releases/1.17.1.5.md#t096-full-companion-bluetooth-and-menu-freeze-report)
keeps 256 frames normally, while retaining 350 contacts, 40 channels, and all
The [nRF52 Full memory correction](releases/1.17.1.5.md#t096-full-companion-bluetooth-and-menu-freeze-report)
applies queue sharing to every nRF52 Full Companion. It keeps 256 frames
normally, retaining each board's contacts, channels, and all
Full transports. The upper 128 slots temporarily hold the mOTA context when
a source or TempRadio discovery session starts. Stopping or disconnecting the
USB/Bluetooth source returns all 256 slots; a discovery-only session returns
@@ -37,10 +38,10 @@ fragmentation from resizing.
Existing unread messages retain their order. If more than 128 frames are
pending, mOTA refuses the loan and asks you to sync messages with a Companion
app first. While the loan is active, the overflow policy below applies at 128
frames. The original `26303793` 1.17.1.5 download reserves the queue and mOTA
state separately, leaving too little runtime headroom for its color display
and Bluetooth. The corrected profile recovers about 19 KiB by sharing storage
and requires at least 72 KiB of heap space at link time.
frames. The original `26303793` 1.17.1.5 builds reserve the queue and mOTA state
separately. Sharing recovers about 19 KiB on nRF52 Full. The ST7735 color-display
Full profiles require at least 72 KiB of heap space at link time; OLED and
headless profiles use their own [memory budgets](firmware_memory_budget.md).
Standard, logging, MQTT, and Cascade build overlays retain the selected target
capacity; they do not silently shrink the queue.
+9 -4
View File
@@ -323,6 +323,12 @@ These capacities preserve the required 8 KiB static internal-DRAM reserve
alongside MOTA and all Full transports; their ordinary transport-specific
images retain 160 contacts, 40 channels, and 128 queued frames.
The 1.17.1.5 memory replacements for Generic ESP-NOW, Heltec Wireless Paper,
Wireless Tracker, CT62, V3, Tracker V2, and XIAO C3 Full Companion use **150
contacts** and retain their **256-frame queue** and Full transports. Export
contacts before updating if you have more than 150; entries beyond the new
limit may be unavailable and a later save may omit them.
Full Companions normally retain 256 pending Companion message frames. ESP32
boards with configured PSRAM retain 512 and allocate that queue from PSRAM
before WiFi and BLE start. If PSRAM is unavailable at runtime, allocation falls
@@ -333,11 +339,10 @@ direct messages; it is not flash-backed history. See
[Companion offline message queue](./companion_offline_queue.md) for all platform
defaults and full-queue behavior.
The corrected T096 Full profile keeps **256 offline frames normally** and
Every corrected nRF52 Full profile keeps **256 offline frames normally** and
temporarily lends 128 slots to mOTA to leave room for
its color framebuffer, Bluetooth tasks, and UI allocations. It retains 350
contacts, 40 channels, and USB/Bluetooth mOTA sending. The published 1.17.1.5
`26303793` image predates this [memory correction](releases/1.17.1.5.md#t096-full-companion-bluetooth-and-menu-freeze-report).
Bluetooth tasks, displays and UI allocations. Queue sharing preserves the
board's contacts, channels, and USB/Bluetooth mOTA sending. See the [memory correction](releases/1.17.1.5.md#t096-full-companion-bluetooth-and-menu-freeze-report).
The nRF52 target inherits the board's ordinary USB Companion installation
format and adds BLE plus the serial mOTA source. It does not enable an SD cache
+81
View File
@@ -0,0 +1,81 @@
# Firmware memory checks
Every firmware environment runs `scripts/check_firmware_ram.py` against its
linked ELF before producing or uploading an image. `build.sh`, including
option 3, also requires a passing report before collecting release files.
Native host tests do not use a microcontroller RAM budget.
The check reserves room for enabled runtime allocations as well as static
data. A firmware image fitting its board's reported RAM total is insufficient:
the display, packet pool, USB, Bluetooth workers and WiFi can allocate after
startup. The T096 Full 1.17.1.5 report exposed this distinction.
## What is counted
| Platform | Source of available runtime RAM |
| --- | --- |
| nRF52 | Actual `__HeapBase` and `__HeapLimit`; excludes SoftDevice, retained state, ISR stack and the dedicated 64 KiB mOTA arena where present |
| ESP32, S3, C3, C6 | Linked ESP-IDF memory-region, capability and reservation tables; only internal, byte-addressable heap counts |
| RP2040/RP2350 | `__end__` to `__HeapLimit`, according to the selected linker |
| STM32 | `_end` to `_estack`, minus `_Min_Stack_Size` |
ESP32 PSRAM, instruction-only RAM and RTC RAM never increase the internal
budget. On chips other than classic ESP32, the late-reclaimed ROM stack region
is excluded because its silicon-specific reservations are only known at boot.
Classic ESP32 additionally retains its existing 8 KiB **static DRAM** check.
The policy adds allowances for task stacks, radio packet pools, screen objects
and pixel buffers, filesystem/sensor allocations, enabled wireless stacks,
MQTT connections, OTA scratch and transient allocations. A 160×80 ST7735
framebuffer needs 25,602 bytes; an OLED allowance is 4 KiB. nRF52 Full with that
color framebuffer must have at least 72 KiB available before startup allocations.
Headless and OLED devices use their own smaller totals. The JSON lists each
component and checks the largest available region against the largest planned
single allocation.
These are engineering allowances for supported configurations, not measured
free heap after boot or a guarantee against every future allocation failure.
Unknown platforms, unknown display drivers and missing linker metadata fail
closed. `MESH_MIN_RUNTIME_HEAP` can raise a profile's requirement; it cannot
lower the calculated requirement. Add an allocation allowance when adding a
display, transport or other substantial feature.
## Release evidence and regression tests
Each newly built firmware has a matching `.memory.json` report. It records
the linked ELF SHA-256, available internal RAM, required RAM, largest region,
and SHA-256 hashes for the actual firmware files and capability manifest.
Packaging and resumed builds reject absent reports, failures, stale ELFs,
missing files and changed firmware. Do not reuse a report for another build.
Run PlatformIO commands sequentially in this checkout:
```sh
python3 -B test/test_firmware_ram.py
python3 -B test/test_t096_full_memory.py
python3 -B test/test_nrf52_ble_startup.py
python3 -B test/test_shared_mota_queue.py
python3 -B test/test_cascade_release_package.py
pio test -e native -f test_ota
```
Tests cover all resolved firmware environments' hooks, real ELF parsing,
allocator table formats, excluded memory, allocation failure, package/report
binding and the published T096 failing budget. Shared mOTA tests exercise
complete transfers, queue wraparound, unread-message order, source ownership,
stop/disconnect and repeated reuse. Bluetooth tests inject task and service
startup failures. The manual staging buffer also has allocation-failure and
repeated release tests.
For older releases without saved ELFs, an audit can compare their ESP allocator
tables against a matching pinned SDK ELF and read reservations from the
**published application itself** using `scripts/audit_esp32_image_ram.py`.
Unrecognized layouts require another matching reference or a historical rebuild.
An audit must identify original-log/linker calculations separately from new
ELF checks and verify the published firmware hashes.
Physical validation remains necessary: boot with and without USB, pair and
exchange Bluetooth messages, visit every screen, wake with the button, enable
logging/MQTT, transfer mOTA, and monitor heap during a sustained workload.
See [memory monitoring](https://github.com/mikecarper/MeshCore/blob/keymindCascade/MEMORY_MONITORING.md)
for runtime diagnostics.
+3 -2
View File
@@ -103,7 +103,8 @@ and the sensor menu could write through a failed CayenneLPP allocation. Those
are code paths consistent with this report; a PIN is not proof of a working
Bluetooth radio.
The source correction keeps the T096 **Full** offline queue at **256 frames
The correction applies to **every nRF52 Full Companion**, keeping its offline
queue at **256 frames
during normal use**. mOTA borrows the upper 128 slots for its roughly 19 KiB
session state only when needed, leaving 128 message slots during mOTA use.
Starting a source or a TempRadio discovery session acquires this workspace.
@@ -117,7 +118,7 @@ messages with a Companion app first**; it does not discard them to make room.
OTA configuration and signer keys survive reuse of the workspace. While mOTA
owns it, the normal queue overflow policy applies to the remaining 128 slots.
The profile requires at least 72 KiB of heap space at link time. It retains
The T096 profile requires at least 72 KiB of heap space at link time. It retains
350 contacts, 40 channels, the color display, sensors, USB, Bluetooth,
Bluetooth DFU, and USB/Bluetooth mOTA sending. This reserve is space for
runtime allocations, not a measurement of free heap after boot.