Repository navigation
memory_map
This document is the single canonical reference for hardware memory regions, linker headroom, SDRAM pools, shared scratch partitions, and subsystem capacity limits across Original Polyend Tracker (MK66), Polyend Tracker+ (IMX), and Polyend Tracker Mini (IMX).
Note
-
Live Per-Build Usage: Exact linker byte counts for every commit are printed during
make all(-Xlinker -print-memory-usage) and posted automatically in the GitHub Actions job summary and PR firmware comment (.github/workflows/build.yml). - Single Source of Truth: Other docs link here instead of repeating volatile memory-usage figures or scratch buffer offset diagrams.
- Hardware Memory Regions & Linker Headroom
- External SDRAM Pool & Reclaimable Sample RAM (
EXTERNAL_RAM) - Shared
768 KBScratch Buffer Map (externalRamScratchBuff) - Synthesizer SDRAM Pool (
PSYN_RAM_POOL_SIZE— IMX) - Subsystem & Asset Capacity Reference
- Memory Placement Rules & Developer Gotchas
Linker definitions live in platforms/mk66/3rdparty/teensy_core/mk66fx1m0.ld, platforms/imx/linker/linkerScript.ld, platforms/imx/linker/TrackerPlus/memory.ld, and platforms/imx/linker/TrackerMini/memory.ld.
| Platform & Region | Base Address | Total Capacity | Baseline Used | Baseline Free | What Lives Here & Developer Notes |
|---|---|---|---|---|---|
Original (MK66) — FLASH |
0x00000000 |
1,024 KB |
~938.5 KB (91.7%) |
~85.5 KB |
Code, .rodata, .audio_flash_functions, .audio_ram_functions, compressed fonts & bitmaps, and .data load image. |
Original (MK66) — RAM (Internal SRAM)
|
0x1FFF0000 |
256 KB |
~168.5 KB (65.8%) |
~87.5 KB |
.usbdescriptortable, .dmabuffers, .usbbuffers, .data, .noinit, .bss_sram_l (< 0x20000000), and libTracker.a .bss (>= 0x20000000). Remaining free SRAM (_ebss.._estack) is the entire runtime heap + C stack. mk66fx1m0.ld asserts that .bss_sram_l never crosses 0x20000000 (SRAM_L/SRAM_U boundary). |
Original (MK66) — EXTERNAL_RAM (SDRAM)
|
0x70000000 |
16,384 KB (16 MB) |
~15,287 KB (93.3%) |
~1,097 KB (1.07 MB) |
SAMPLE_MEMORY_SIZE (11.25 MB, overlapping 7.5 MB Sample Editor buffers), 1.5 MB delay, 768 KB externalRamScratchBuff, 32 KB .reverb_memory + 32 KB internalRamReverbBuff, 64 KB g_wtEnvelopeBank, VoiceStreamManager ring buffers, and cold UI/FileManager buffers. (Additional space requires lowering SAMPLE_MEMORY_SIZE alongside EDIT_BUFF_SIZE; see Section 2.)
|
Plus / Mini (IMX) — QSPI_FLASH |
0x60030000 (Plus)0x60020000 (Mini)
|
16,192 KB (Plus)16,256 KB (Mini)
|
~1,429–1,459 KB (8.8–9.0%) |
~14,763–14,797 KB |
XIP Flash above the protected bootloader region (0x60000000–0x6002FFFF on Plus / 0x6001FFFF on Mini). Never modify QSPI_FLASH ORIGIN.
|
Plus / Mini (IMX) — SRAM_ITC (RAM2)
|
0x00000008 |
~128 KB (0x1FFF8) |
~61.0 KB (47.6%) |
~67.0 KB |
Zero-wait-state instruction TCM (.ramfunc.$RAM2 / .audio_ram_functions hot DSP loops + firmware-wide fastmem.S memcpy/memmove/memset/memcmp). First 8 bytes reserved as null-pointer guard. |
Plus / Mini (IMX) — SRAM_DTC (RAM)
|
0x20000000 |
352 KB (0x58000) |
~340.7–341.1 KB (96.8–96.9%) |
~10.9–11.3 KB |
.data, .dmabuffers, .bss, NonCacheable, .noinit, plus statically reserved .heap (135.5 KB, _HeapSize = 0x21E00) and .stack (20 KB, _StackSize = 0x5000). Baseline usage already includes both heap and stack reservations; keep large/non-realtime arrays out of default .bss. |
Plus / Mini (IMX) — SRAM_OC (RAM3)
|
0x20200000 |
32 KB (0x8000) |
~22.7 KB (70.8%) |
~9.3 KB |
Non-cacheable OCRAM for USB/SDMA buffers and audioPlayBuff (platforms/imx/usb/audio_unified.c). |
Plus / Mini (IMX) — EXTERNAL_RAM (RAM4)
|
0x80000000 |
65,536 KB (64 MB) |
~65,516 KB (99.97%) |
~19.9 KB |
~53.84 MB SAMPLE_MEMORY_SIZE + 6 MB PSYN_RAM_POOL_SIZE + 1.5 MB delay + 768 KB externalRamScratchBuff + 32 KB .reverb_memory + 64 KB g_wtEnvelopeBank + display/stream/USB/UI buffers. Up to ~22.84 MB–23 MB reclaimable by lowering SAMPLE_MEMORY_SIZE (see Section 2). |
Core SDRAM constants and buffers are defined in core/source/mtStructs.h and core/source/Tracker.cpp:
| Symbol / Section |
MK66 Size |
IMX Size |
Location / Notes |
|---|---|---|---|
externalRamSampleMemory (.sample_memory, SAMPLE_MEMORY_SIZE) |
11,520 KB (11.25 MB) |
55,136 KB (~53.84 MB) |
Resident sample pool + pre-caches (mtProject.max_memory). IMX formula: ((60 * 1024 - 64 - 96) * 1024) - PSYN_RAM_POOL_SIZE. |
externalRamEffectsBuff (overlaps top of externalRamSampleMemory)
|
7,680 KB (7.50 MB) |
15,360 KB (15.00 MB) |
Starts at EDIT_BUFF_OFFSET = SAMPLE_MEMORY_SIZE - (2 * SAMPLE_CHANNELS * EDIT_BUFF_SIZE). EDIT_BUFF_SIZE is 15 * 256 * 1024 (3,932,160) in int16_t units (EDIT_BUFF_SIZE / 2 = 1,966,080 frames = 3.75 MB per half: confirmed + processed per channel). |
s_psynRamPool (PSYN_RAM_POOL_SIZE) |
— |
6,144 KB (6.00 MB) |
.psyn executable arena, synth SamplePool, and PolySynth Master FX (core/synth/Synth.cpp); see Section 4. |
externalRamDelayBuff (.delay_memory, DELAY_MEMORY_SIZE) |
1,536 KB (1.50 MB) |
1,536 KB (1.50 MB) |
Master Delay audio buffer. |
externalRamScratchBuff (.scratch_memory, SHARED_SCRATCH_MEMORY_SIZE) |
768 KB |
768 KB |
Shared 4-region scratch buffer; see Section 3. |
externalRamReverbBuff (.reverb_memory, REVERB_MEMORY_SIZE) |
32 KB |
32 KB |
Master Reverb buffer (32 KB); on MK66, Polyverb also places internalRamReverbBuff (32 KB) in __NOINIT(EXTERNAL_RAM) (core/libs/Audio/effect_polyverb.cpp). |
g_wtEnvelopeBank |
64 KB |
64 KB |
256 wavetable envelope/LFO shapes × 128 int16_t points (core/source/mtWavetableEnvelopes.cpp). |
Display list buffers (arenaWords, buildWords, frameWords, chipLists) |
— (smaller) | 88 KB |
MCU-built FT812 display-list arena (14,336 + 2,048 + 2,048 + 2×2,048 uint32_t words in core/libs/NewDisplay/display.cpp). |
VoiceStreamManager, FileManager, ThemeManager, audioRecBuff, UI singletons |
Remainder | Remainder | Streaming ring/bounce buffers, decompressedFontsCommonBuffer (22,396 B), ThemeManager tables/read buffer, audioRecBuff (IMX), pattern/project buffers. |
Because Hybrid SD Card Sample Streaming (core/AudioEngine/VoiceStreamManager.cpp) streams eligible samples >= 256 KB (kStreamThresholdBytes) from the microSD card while allocating only kStreamPreCacheFrames = 32,768 frames (64 KB per channel) in externalRamSampleMemory, IMX EXTERNAL_RAM headroom can be expanded significantly by reducing SAMPLE_MEMORY_SIZE in core/source/mtStructs.h:
-
Tracker+ & Tracker Mini (
IMX): LoweringSAMPLE_MEMORY_SIZEfrom~53.84 MB(55,136 KB) down to31 MB(31 * 1024 * 1024) keeps the full15.0 MBSample Editor region plus16.0 MBbelowEDIT_BUFF_OFFSETfor short resident samples, stream pre-caches, and Wavetable/Granular instruments while freeing~22.84 MBofEXTERNAL_RAM. -
Invariants When Adjusting
SAMPLE_MEMORY_SIZEorEDIT_BUFF_SIZE:-
SAMPLE_MEMORY_SIZEmust strictly exceed2 * SAMPLE_CHANNELS * EDIT_BUFF_SIZE(> 15.0 MBonIMX,> 7.5 MBonMK66), otherwise the unsigneduint32_t EDIT_BUFF_OFFSETcalculation underflows. - When
mtEffect::startLoad()loads a resident sample whoseconfirmedbuffer overlaps its source address inexternalRamSampleMemory, it temporarilymemmoves the channel toexternalRamSampleMemoryBegin + EDIT_BUFF_SIZE * idx. KeepingEDIT_BUFF_OFFSET >= 15.0 MBonIMX(SAMPLE_MEMORY_SIZE >= 30.0 MB) and>= 3.75 MBonMK66(SAMPLE_MEMORY_SIZE >= 11.25 MB) guarantees non-overlapping staging for max-length (1,966,080-frame) editable samples without also reducingEDIT_BUFF_SIZE.
-
Defined in core/source/Tracker.cpp (SHARED_SCRATCH_MEMORY_SIZE = 768 * 1024 in core/source/mtStructs.h), externalRamScratchBuff sits in .scratch_memory (EXTERNAL_RAM, 32-byte aligned) and is shared across mutually exclusive or partitioned subsystems.
Offsets are defined in core/effector/ptfx_loader.h and core/interface/fileBrowser/GlobalFileBrowser.cpp:
Offset 0 KB 128 KB 512 KB 744 KB 768 KB
├─────────────────────────┼───────────────────────┼──────────────────────┼───────────────┤
│ .ptfx Code + .bss │ .ptfx Working Scratch │ .ptfx Secondary WAV │ Global File │
│ (128KB IMX / 32KB MK66) │ (384 KB) │ Buffer (232 KB) │ Browser (24KB)│
└─────────────────────────┴───────────────────────┴──────────────────────┴───────────────┘
| Slice | Range | Size | Owner & Purpose |
|---|---|---|---|
.ptfx Executable Buffer |
[0 .. 128 KB] (32 KB cap on MK66)
|
128 KB (IMX)32 KB (MK66) |
Relocated .ptfx plugin binary (.text + .rodata + .data + .bss), capped by PtfxLoader::getMaxCodeSize(). Placed at 0x80000000 base on IMX. |
.ptfx Working Scratch (scratch_mem) |
[128 KB .. 512 KB] |
384 KB (393,216 B) |
Plugin // PTFX_SCRATCH: <bytes> allocation, capped at kPtfxScratchTopOffset (512 KB) by PtfxLoader::getMaxScratchSize(). |
.ptfx Secondary WAV Buffer |
[512 KB .. 744 KB] |
232 KB (237,568 B) |
Pre-decoded secondary .wav input (PTFX_PARAM_FILE / get_secondary_sample(), up to ~118k int16_t samples) at kPtfxSecondarySampleOffset. |
GlobalFileBrowser Scratch |
[744 KB .. 768 KB] |
24 KB (24,576 B) |
cGlobalFileBrowser directory name/pointer lists (kBrowserScratchOffset). Opening the file browser from inside the Sample Editor or an effect parameter never overwrites active .ptfx code, scratch, or secondary WAV data. |
Subsystems that only run outside Sample Editor .ptfx rendering reuse the base of externalRamScratchBuff directly (requiring .ptfx reload on return to Sample Editor if overwritten):
-
sdStreamaudio preview (core/AudioEngine/mtAudioEngine.cpp): uses[0 .. 320 KB](kSdStreamBufferSize = (256 + 64) * 1024), leaving[744 KB .. 768 KB]forGlobalFileBrowseruntouched during preview-enabled browsing. -
mtAudioExportstem render buffer (core/Exporter/mtAudioExport.cpp): reusesexternalRamScratchBuff(static_assert(sizeof(renderBuffer) <= SHARED_SCRATCH_MEMORY_SIZE)). -
PtfxManager::scanEffects()(core/effector/ptfx_manager.cpp) andSynthEditor(core/interface/instrumentEditor/SynthEditor.cpp): temporarily stage file-list strings/pointers during scans.
On PLATFORM_IMX, core/synth/Synth.cpp reserves a single static 6 MB (6,144 KB) SDRAM pool (__NOINIT(EXTERNAL_RAM) alignas(32) uint8_t s_psynRamPool[PSYN_RAM_POOL_SIZE]) managed by a 32-byte-aligned bump allocator (largeBuffersAlloc):
| Sub-Allocation | Capacity | Source & Behavior |
|---|---|---|
.psyn Executable & Heap Arena (PsynLoader::kArenaSize) |
1,920 KB (3 * 640 KB) |
Defined in synth/source/synths/PsynLoader.h. Holds relocated .psyn .text/.rodata/.data/.bss, .init_array, slot_alloc, and load_wav_file allocations (capped at kMaxWavFrames = (kArenaSize / 2) / sizeof(int16_t) = 491,520 frames). Boot preloading caches up to kMaxPreloadBytes = 1,024 KB; additional .psyn engines load lazily with LRU eviction of inactive engines. |
Synth SamplePool |
4,096 KB (4.00 MB) |
Initialized via synth->initSamplePool(4 * 1024 * 1024, sampleStore) in core/synth/Synth.cpp. Reference-counted, content-deduplicated SDRAM pool shared by SampleSlot instruments and patches. |
| PolySynth Master FX Buffers |
128 KB remainder |
Delay, Reverb, and Modulation Master FX buffers allocated via largeBuffersAlloc in SynthImpl (DelayVoice, ReverbVoice, ModulationFxVoice). |
See docs/custom_synth_sdk.md for .psyn authoring guidelines.
| Subsystem | Fixed Limit / Memory Footprint | Source of Truth | Guide |
|---|---|---|---|
| Tracks & Instrument Slots |
16 sequencer tracks (8 sample + 8 MIDI); 48 sample instruments + 16 MIDI instruments + 3 synth parts (8 shared synth voices on IMX). |
core/source/mtStructs.h, core/config/config.h
|
developer_guide.md |
| Hybrid SD Streaming | Streams samples >= 256 KB (kStreamThresholdBytes); allocates 32,768-frame SDRAM pre-cache (64 KB/ch) + 16,384-frame (32 KB/ch) voice ring buffers (4,096-frame / 8 KB read chunks). |
core/source/mtStructs.h, core/AudioEngine/VoiceStreamManager.h
|
developer_guide.md |
Sample Editor & .ptfx Plugins |
Up to 128 .ptfx plugins (kMaxModularPlugins) + 17 built-in effects; max 12 parameters (472 B PtfxHeader); max editable sample 1,966,080 frames (EDIT_BUFF_SIZE / 2); max generator output 88,200 frames (2.0 s @ 44.1 kHz). s_ptfxEntries[128] lives in EXTERNAL_RAM. |
core/effector/ptfx_manager.h, core/effector/ptfx_loader.h, core/effector/mtEffectModular.cpp
|
modular_effects_system.md |
GlobalFileBrowser |
Uses [744 KB .. 768 KB] (24 KB) of externalRamScratchBuff, 10 LRU contexts (kMaxSavedContexts), max 256 entries (kMaxFilesListLength), 255-char paths (kMaxFilePathLen), 80-char filenames (kMaxFileNameLen). |
core/interface/fileBrowser/GlobalFileBrowser.cpp, core/config/config.h
|
global_file_browser.md |
Custom Fonts (.ptfont) |
kMaxFontBufferSize = 22,396 bytes (decompressedFontsCommonBuffer in EXTERNAL_RAM); max 32 font slots (30 custom + 2 built-in). |
core/libs/NewDisplay/display.cpp, core/source/ThemeManager.h
|
custom_themes_and_fonts.md |
Custom Themes (.json) |
Max 8 KB file read buffer (s_fileReadBuffer); ~17 KB static footprint in __NOINIT(EXTERNAL_RAM); max 32 theme slots (29 custom + 3 built-in); 31-char display names. |
core/source/ThemeManager.cpp, core/source/ThemeManager.h
|
custom_themes_and_fonts.md |
| Wavetable Envelopes / LFOs |
256 shapes (128 factory + 128 user) × 128 int16_t samples = 64 KB (g_wtEnvelopeBank in EXTERNAL_RAM). |
core/source/mtWavetableEnvelopes.h |
wavetable_envelopes.md |
| SD Image Viewer | Up to 48 Baseline JPEGs (1.jpg–48.jpg) per folder (/Images/{Reference,Notes,Custom}/), max 800 × 390 px, max 650 KB per file. |
core/interface/imageViewer/fImageViewer.cpp |
image_viewer.md |
USB Dev Console (IMX) |
4 KB (kTxBufferSize = 4096) ring buffer in SRAM_DTC only when compiled with ENABLE_DEV_CONSOLE. |
platforms/imx/source/DevConsole.cpp |
developer_guide.md |
Firmware .ptf Filename |
Must be 15–31 characters (PolyendTrac*, TrackerPlus*, TrackerMini*) so /Firmware/_fwinfo fits the MK66 32-byte bootloader buffer with \0. |
platforms/mk66/source/PlatformImpl.cpp |
developer_guide.md |
-
Default
.bssvs.__NOINIT(EXTERNAL_RAM):- Unannotated globals land in internal
RAM(MK66) orSRAM_DTC(IMX), both of which are tight and hold the runtime C stack and heap. Place large or non-real-time buffers in__NOINIT(EXTERNAL_RAM)(.noinit_RAM4). - Because
.noinit_RAM4isNOLOAD(not zero-initialized by startup code before C++ static constructors run), any struct, array, or C++ singleton placed in__NOINIT(EXTERNAL_RAM)must be explicitly zeroed (memset) or placement-newconstructed during initialization (TrackerImpl::init()) before use.
- Unannotated globals land in internal
-
Reuse
externalRamScratchBuffBefore Adding New RAM:- Modal tools, file scans, and offline exporters should carve temporary memory out of
externalRamScratchBuff(respectingGlobalFileBrowser's[744 KB .. 768 KB]slice if file browsing runs concurrently) instead of growing static.bssorEXTERNAL_RAM.
- Modal tools, file scans, and offline exporters should carve temporary memory out of
-
Real-Time Audio Thread Rules:
- Never allocate/free heap memory (
new,delete,malloc,free,std::vector::push_back,std::string), perform FatFs SD card I/O, or format floats (%finLOGF(), which triggers newlib heap allocation) inside audio-rate ISRs (update(),renderVoiceAudio(),renderPostProcessAudio(),tickIdle(),processBlock()).
- Never allocate/free heap memory (
-
IMXITCMfastmem.SConstraint:-
memcpy,memmove,memset, andmemcmpinplatforms/imx/source/fastmem.Sexecute fromSRAM_ITC(.ramfunc.$RAM2) for arbitrary alignments in Normal memory (SRAM_*,EXTERNAL_RAM,QSPI_FLASH), but must not be called onDeviceperipheral registers (0x40000000+).
-
-
IMXFatFs+USDHCDMA Alignment Pitfall:- On
IMX,f_readbypasses its internal aligned DTCM bounce buffer wheneverbtr >= 512(cc = btr / 512 > 0) and DMAs directly to the caller's pointer. Any destination pointer that is not 4-byte aligned or sits in non-DMA-accessible TCM fails withFR_DISK_ERR. Always use 4-byte aligned buffers inSRAM_DTC/EXTERNAL_RAM, or read in<= 256-byte chunks (ashostReadFile/hostWriteFiledo automatically).
- On
-
Live Heap & Stack Diagnostics (
/.develop):- Placing an empty
/.developfile in the SD card root enables live audio ISR CPU (min/max/avg/last %) andfreeRamBytes()heap telemetry on theConfigscreen across all 3 devices (pressingPlayorStopresetsProfilercounters).Profiler::maxStackBytes()reports the measured stack watermark onIMX(0onMK66).
- Placing an empty