Memory Budgeting
Make memory a measured budget, not a nominal board label. The implementation is
embedded C/C++; scripts may parse build or runtime logs when that is the useful
deterministic tool.
Intake
Record exact board/module, flash/RAM/EEPROM/PSRAM, bootloader and partition
layout, framework, compiler flags, libraries, static buffers, task stacks,
filesystem/OTA needs, peak protocol sizes, and available measurement output.
Process
- Separate static data, code/flash, heap, task stacks, interrupt state,
filesystem, bootloader, and OTA/update slots.
- Establish a numeric budget and minimum margin for every category. Use board
references rather than copying a family-level number into a project claim.
- Capture compiler size output and map changes to a feature or dependency.
- Measure runtime free heap, largest block, stack high-water marks, and reset/
allocation failures under representative load where the framework exposes
them.
- On AVR, keep literals in flash with
F() where appropriate, prefer bounded buffers and fixed-size storage, and avoid unbounded dynamic String use. On ESP32/RP2040,
still bound buffers and distinguish heap, stack, flash, and filesystem.
- Re-run the stress case after each memory-affecting change and record the
tradeoff.
Anti-rationalization
| Shortcut |
Response |
| "The datasheet says 520 KB, so memory is fine." |
Separate usable heap, stacks, reserved regions, and radio/RTOS use. |
| "It compiled." |
Inspect size output and exercise runtime allocation paths. |
| "Make the buffer bigger." |
Bound the protocol and prove the required maximum. |
| "Use String everywhere." |
Check fragmentation and lifetime; use bounded alternatives where needed. |
| "OTA only needs the application image." |
Budget both update slots, bootloader, metadata, and rollback image. |
Verification
- Build-size output and runtime memory evidence name the exact target/version.
- Each budget has a margin and a failure response.
- Stress tests cover peak message, sensor, logging, radio, and task load as
applicable.
- Optimization does not remove bounds, safety checks, or recovery behavior.
Shared output contract
Use the shared Arduino skill contract:
state assumptions, required tools and versions, implementation steps,
tests/evidence by proof stage, known limitations, and recovery/security notes.
1---
2name: memory-budgeting
3description: Use when Arduino or embedded projects hit SRAM, flash, heap, stack, partition, JSON-buffer, or performance limits, or when reviewing String use, F() placement, OTA slots, FreeRTOS stacks, or memory margin.
4metadata:
5 triggers: "memory budget, SRAM, flash, heap, stack, fragmentation, F macro, String, partition"
6 attribution: "Adapted from embedded memory-safety practice and the shared Arduino board-profile contract."
7---
8
9# Memory Budgeting
10
11Make memory a measured budget, not a nominal board label. The implementation is
12embedded C/C++; scripts may parse build or runtime logs when that is the useful
13deterministic tool.
14
15## Intake
16
17Record exact board/module, flash/RAM/EEPROM/PSRAM, bootloader and partition
18layout, framework, compiler flags, libraries, static buffers, task stacks,
19filesystem/OTA needs, peak protocol sizes, and available measurement output.
20
21## Process
22
231. Separate static data, code/flash, heap, task stacks, interrupt state,
24 filesystem, bootloader, and OTA/update slots.
252. Establish a numeric budget and minimum margin for every category. Use board
26 references rather than copying a family-level number into a project claim.
273. Capture compiler size output and map changes to a feature or dependency.
284. Measure runtime free heap, largest block, stack high-water marks, and reset/
29 allocation failures under representative load where the framework exposes
30 them.
315. On AVR, keep literals in flash with `F()` where appropriate, prefer bounded buffers and fixed-size storage, and avoid unbounded dynamic `String` use. On ESP32/RP2040,
32 still bound buffers and distinguish heap, stack, flash, and filesystem.
336. Re-run the stress case after each memory-affecting change and record the
34 tradeoff.
35
36## Anti-rationalization
37
38| Shortcut | Response |
39|---|---|
40| "The datasheet says 520 KB, so memory is fine." | Separate usable heap, stacks, reserved regions, and radio/RTOS use. |
41| "It compiled." | Inspect size output and exercise runtime allocation paths. |
42| "Make the buffer bigger." | Bound the protocol and prove the required maximum. |
43| "Use String everywhere." | Check fragmentation and lifetime; use bounded alternatives where needed. |
44| "OTA only needs the application image." | Budget both update slots, bootloader, metadata, and rollback image. |
45
46## Verification
47
48- Build-size output and runtime memory evidence name the exact target/version.
49- Each budget has a margin and a failure response.
50- Stress tests cover peak message, sensor, logging, radio, and task load as
51 applicable.
52- Optimization does not remove bounds, safety checks, or recovery behavior.
53
54## Shared output contract
55
56Use [the shared Arduino skill contract](../../docs/arduino-skill-contract.md):
57state assumptions, required tools and versions, implementation steps,
58tests/evidence by proof stage, known limitations, and recovery/security notes.
wedsamuel1230