Repository navigation
developer_guide
When extending the Polyend Tracker Community Edition (CE) firmware, adding new synthesizer engines, or writing Sample Editor effects, keep the following hardware constraints and non-obvious architectural details in mind.
Memory Map & Resource Limits: All hardware memory region budgets (
FLASH,RAM,SRAM_DTC,SRAM_ITC,SRAM_OC,EXTERNAL_RAM),SAMPLE_MEMORY_SIZEreclamation rules, the768 KBexternalRamScratchBuffpartition map,PSYN_RAM_POOL_SIZE, and subsystem capacity limits are consolidated indocs/memory_map.md.
- Copy-on-Write
/Workspace/instruments/, Incremental Project Saver & Hybrid SD Streaming - Synthesizer Engine Architecture & Guidelines (
.psynPlugins) - Sample Editor &
.ptfxPlugin Constraints - UI, FT812 Display, Config & Bootloader Gotchas
- Conditional Compilation: Targeting Specific Platforms or Devices
- Development Console & Logging over USB (Tracker+ & Tracker Mini)
- Global File Browser (
GlobalFileBrowser) - Real-Time Audio Graph (
AUDIO_NULL_IS_SILENCE), DSP Sleep & IMXfastmem.S
To avoid copying 13–45 MB of PCM sample payloads from /Projects/<Path>/<Name>/instruments/*.pti to /Workspace/instruments/instrument_%02d.pti on every project open and save, the FileManager uses a Header-Only Copy-on-Write (CoW) model paired with Hybrid SD Card Sample Streaming:
-
Project Open (
ProjectOpen::copyInstruments):- Copies only the 392-byte
strInstrumentFileheader (cFileTransfer::copyInstrumentHeader) from/Projects/<Path>/<Name>/instruments/*.ptiinto/Workspace/instruments/instrument_%02d.pti.
- Copies only the 392-byte
-
Sample Streaming & Reload (
WorkspaceProjectLoad&SampleMemoryReload):- In
cFileManager::startNewInstrumentSampleLoad()andcFileManager::loadSampleData(), if a/Workspace/instruments/instrument_%02d.ptifile hasfileSize <= sizeof(strInstrumentFile)(header-only), the loader resolves its backing.ptifile in/Projects/<Path>/<Name>/instruments/viacFileManager::resolveProjectInstrumentPtiPath()and loads or streams the PCM sample data directly from the project folder (respectingcFileManager::getPtiFileDataOffset()for both current 392-byte headers and legacy firmware< v8smaller headers).
- In
-
Copy-on-Write Promotion (
WorkspaceProjectSave& Sample Edits):- Parameter tweaks (
AutoSave/WorkspaceProjectSave) only rewrite the 392-byte header in/Workspace/instruments/instrument_%02d.ptiwhen!isInstrumentSampleChanged(idx), preserving its header-only status. - Whenever an instrument's audio is newly imported, recorded, rendered, copied (
InstrumentCopy), or modified in the Sample Editor (cFileManager::saveSampleDataToWorkspace), a full.ptifile (header + PCM audio) is written to/Workspace/instruments/instrument_%02d.pti.
- Parameter tweaks (
-
Incremental
Save Projectvs. FullSave As(ProjectSave::copyInstruments):-
Same-Project Save (
isSavingToSameProject == true): Deletes deactivated slots, copies full.ptifiles from/Workspace/only for slots whose audio was modified, and for unmodified header-only slots updates the 392-bytestrInstrumentFileheader in-place (skipping the write entirely if all 392 bytes are identical) and renames the file in-place ifsample.file_namechanged. -
Save Asto a New Project (isSavingToSameProject == false): Copies full.ptifiles from/Workspace/where present, and writes the updatedstrInstrumentFileheader plus the raw PCM sample payload directly fromexternalRamSampleMemory(or streams it in chunks from the backing.ptifile for SD-streamed instruments) for header-only slots so the new project folder is completely self-contained.
-
Same-Project Save (
-
Hybrid SD Card Sample Streaming Architecture (
VoiceStreamManager&isPlayModeStreamable):-
Threshold & SDRAM Pre-Cache: Instruments whose PCM payload is
>= 256 KB(kStreamThresholdBytesincore/source/mtStructs.h) and whose play mode satisfiesisPlayModeStreamable(playMode)allocate onlykStreamPreCacheFrames = 32768frames (~743 msat44.1 kHz) per channel (64 KBmono /128 KBstereo) inexternalRamSampleMemory. -
Zero-Latency Trigger & Background Ring Buffers: When a note is triggered, the audio ISR (
AudioPlayMemory::update()incore/libs/Audio/play_memory.cpp) immediately plays from the SDRAM pre-cache whileVoiceStreamManager::update()(core/AudioEngine/VoiceStreamManager.cpp) refills the active voice's16,384-frame (kRingFrames) ring buffer in4,096-frame (kChunkFrames) chunks on the main thread using FatFs FastSeek cluster link maps (CLMT) and direct LBA sector reads. -
Loop Wrap & Direction Support: Supports forward, backward, and ping-pong looping (
VoiceStreamManager::prepareLoopWrappre-fetches the loop boundary before the playhead reaches the wrap point) as well asR(Reverse) andP(Position) pattern step FX. -
Platform Differences (
PLATFORM_IMXvs.MK66):-
Tracker+ & Tracker Mini (
PLATFORM_IMX):isPlayModeStreamable()returnstrueforOne-Shot,Forward Loop,Backward Loop,Ping-Pong Loop,Slice, andBeat Slice, andfalseonly forWavetableandGranular. ForSliceandBeat Sliceinstruments, the32,768-frame SDRAM pre-cache is partitioned into a16,384-frame linear attack region ([0 .. 16383]) plus per-slice SDRAM pre-cache windows across the upper16,384frames (VoiceStreamManager::refreshInstrumentSliceCache/refreshInstrumentSingleSliceCache), allowing any slice to start immediately from SDRAM while the600 MHzCortex-M7 refills the voice ring buffer. -
Original Tracker (
MK66):isPlayModeStreamable()returnstrueforOne-Shot,Forward Loop,Backward Loop, andPing-Pong Loop, andfalseforSlice,Beat Slice,Wavetable, andGranular. Because partitioning16,384frames across10–48slices yields smaller per-slice pre-cache windows (~7.6–37 ms), and the180 MHzCortex-M4 spends~20–35 msper step on FT812 SPI pattern redraws and Song Mode pattern reads, keepingSliceandBeat Sliceinstruments 100% resident in SDRAM onMK66guarantees dropout-free multi-track slice playback while non-sliced instruments enjoy the full743 mslinear pre-cache.
-
Tracker+ & Tracker Mini (
-
Automatic Promotion & Demotion (
Sample Editor&Play ModeSwitching):- Entering the Sample Editor (
cSampleEditor) or switching an instrument to a non-streamable play mode (!isPlayModeStreamable(newPlayMode)infSamplePlay.cpp) callscFileManager::promoteStreamedInstrumentToRam(idx), loading the full PCM payload intoexternalRamSampleMemory. - Applying an offline Sample Editor effect or saving sample edits (
cFileManager::saveSampleDataToWorkspace) writes the updated full.ptito/Workspace/instruments/instrument_%02d.pti, recomputes the600-point waveform peak cache (WaveformPeakPoint), and callscFileManager::demoteRamInstrumentToStream(idx)to return the instrument to hybrid SD streaming.
- Entering the Sample Editor (
-
Threshold & SDRAM Pre-Cache: Instruments whose PCM payload is
-
Binary
.ptiHeader Compatibility (sizeof(strInstrument) == 372) & SharedenvWtPos/envGranLenAutomation Slot:- Because
strInstrumentFile(392bytes) is serialized directly into.ptifiles and Copy-on-Write/Workspace/instruments/headers,sizeof(strInstrument)incore/source/mtStructs.his enforced at372bytes viastatic_assert(sizeof(strInstrument) == 372). - Instrument structure versions
1–7may use the legacy368-byte metadata layout; versions8–9use372bytes. The 4-byte CRC field immediately follows the serialized metadata (though metadata-only legacy files may omit it). Loaders validate the header magic, version bounds, and metadata/file sizes before version translation, rejecting truncated, oversized, malformed, or newer-version metadata. -
Wavetable (
playModeWavetable) and Granular (playModeGranular) are mutually exclusive playback modes on an instrument. Therefore, Granular Length automation (envGranLen) shares envelope/LFO hardware storage slot3(envWtPos = 3,envGranLen = envWtPos) with Wavetable Position:- In the UI (
Instrument Automation 2/2), the 7 destinations are indexed byenAutomationDest(autoDestVolume,autoDestPanning,autoDestCutoff,autoDestWtPos,autoDestGranPos,autoDestGranLen,autoDestFinetune,autoDestCount = 7) and mapped to the 6 underlyingenvelope[6]/lfo[6]storage slots viaautomationDestToEnvSlot(uint8_t destIdx). - Enable state in
envelope[3].enableuses separate bitmask flags (kEnvEnableWtPosBit = 0x01forWavetable Position,kEnvEnableGranLenBit = 0x02forGranular Length) viastrInstrument::isWtPosEnvEnabled(),strInstrument::isGranLenEnvEnabled(),strInstrument::isEnvEnabled(envIdx),strInstrument::isAutomationDestEnabled(destIdx), andstrInstrument::setAutomationDestEnabled(destIdx, enabled). - Because all legacy
.ptifiles only ever wrote0or1(0x01) toenvelope[3].enable, existing.ptifiles load withisGranLenEnvEnabled() == false(Off) while preserving legacy Wavetable Position automation 100%. Always use theenvGranLenalias andisGranLenEnvEnabled()helper in granular code paths rather than rawenvWtPosor.enablechecks.
- In the UI (
- Because
Full details in docs/custom_synth_sdk.md, synth-plugin-sdk/README.md, and docs/memory_map.md.
-
Loadable SD-Card
.psynArchitecture (PsynLoader):- All synth engines (built-in and community) are distributed as standalone ARMv7E-M Thumb-2 relocatable
.psynplugins in/Synths/*.psynon the microSD card and loaded dynamically byPsynLoaderinside the dedicatedPSYN_RAM_POOL_SIZESDRAM pool (seedocs/memory_map.mdfor arena, boot-preload, and sharedSamplePoolcapacities). -
PsynLoaderpreloads built-in/initial engines up tokMaxPreloadBytesat boot, lazily loads additional engines on demand, and applies LRU eviction of inactive engines when headroom is needed, alongside the sharedSamplePoolfor sample-based engines (WAVS,GRAIN,DWA, and third-partyPSYN_FLAG_HAS_SAMPLE_SLOTSplugins). -
Zero firmware recompilation or bitmap edits required:
SynthEditorpopulates the Synth model list dynamically fromsynth->getSynthTypes(), and third-party engines receive deterministic non-colliding IDs (0x100+) when packed with--type-id-wave 0 --type-id-play-tracker 0.
- All synth engines (built-in and community) are distributed as standalone ARMv7E-M Thumb-2 relocatable
-
Auto-Created Sample Folders & Read Fallback Chain:
- On boot,
PsynLoadercreates/SynthSamples/<CODE_NAME>/for every sample-based engine (avoiding clutter in user/Samples/folders), whilecore/synth/FileSystemAdapter.cppresolves sample reads across/SynthSamples/,/Samples/,/, and/Patches/.
- On boot,
-
Keep Voice State & Arena Usage Compact (
CustomSynthVoice/ParamHelper):- Inherit from
polysynth::sdk::CustomSynthVoice<VoiceClass, ParamIdEnum>(synth/include/PolySynth/sdk/SynthVoiceSDK.h) bridged viaPSYN_REGISTER_CPP_VOICE(synth-plugin-sdk/include/psyn/psyn_cpp_bridge.h) or write a Pure Cpsyn_plugin_entryplugin (synth-plugin-sdk/include/psyn/psyn_plugin.h). - Never perform blocking
PsynHostApiSD/WAV calls (read_file,write_file,load_wav_file,free_wav_file) or heap allocations inside real-time audio callbacks (renderVoiceAudio/voice_render_audio).
- Inherit from
Full details in docs/modular_effects_system.md.
-
Plugin, Parameter, File & Preset Limits:
- External
.ptfxplugins under/Effects/(including subfolders) are browsed and loaded on demand viaLoad Effect...inGlobalFileBrowser(with no plugin-count cap); the currently loaded plugin (s_activeEntry) is listed immediately aboveLoad Effect...alongside thekBuiltInEffectsCountbuilt-in Sample Editor effects ins_effectDisplayNames(core/effector/ptfx_manager.h). - Each
.ptfxplugin supports up to 12 parameters (PtfxHeader::params[12]incore/effector/tracker_plugin.handeditor-fx-sdk/tracker_plugin.h), including continuous float, stepped integer, pipe-separated string lists, and SD file pickers/savers (PTFX_PARAM_FILE/PTFX_PARAM_SAVE_FILE). - Any
.ptfxplugin with>= 1parameter automatically gains a Presets page via theMorescreen button (Load/Save.ptppresets in/Effects/Presets/<SanitizedPluginName>/viaGlobalFileBrowser, plusReset).
- External
-
.ptfxCode, Scratch & Secondary WAV Regions (externalRamScratchBuff):- Both platforms execute
.ptfxplugin code from the base ofexternalRamScratchBuff(on Original TrackerMK66,PtfxLoader::syncInstructionCache()disables the Kinetis System MPU viaMPU_CESR = 0; on Tracker+ / Tracker MiniIMX, it cleans L1 D-Cache and invalidates I-Cache). - Working scratch memory (
scratch_mem, capped bykPtfxScratchTopOffsetincore/effector/ptfx_loader.h), the pre-decoded secondary.wavinput (get_secondary_sample()), andGlobalFileBrowseroccupy non-overlapping slices ofexternalRamScratchBuff— seedocs/memory_map.mdfor exact byte offsets and platform limits. Plugins can also read/write non-WAV assets viahost->read_file()andhost->write_file(). - Plugins exceeding the
MK66executable limit (PtfxLoader::getMaxCodeSize(),32 KB) or requiring600 MHzCortex-M7 speeds should declarePTFX_FLAG_IMX_ONLY.
- Both platforms execute
-
SD Card DMA Alignment Pitfall on IMX (
FatFs+USDHC):- On IMX (
platforms/imx/),FatFs(f_read) bypasses its internal aligned DTCM sector buffer whenever a read request is>= 512bytes (cc = btr / 512 > 0) and passes the caller's destination pointer directly to the USDHC DMA controller. - If the destination buffer is not 4-byte aligned or lies in a non-DMA-accessible TCM region,
f_readfails withFR_DISK_ERR. Always use 4-byte aligned buffers inSRAM_DTC/EXTERNAL_RAM, or read in<= 256-byte chunks to forceFatFsthrough its internal bounce buffer (hostReadFileandhostWriteFileuse256-byte chunking automatically).
- On IMX (
-
Do Not Shift
Interface::modules[]Indices (core/interface/core/interface.cpp):- UI navigation references
mtInterface.modules[]by hardcoded index (modules[9]=performanceMode,modules[10]=imageViewer,modules[12]=masterParams). Slotmodules[11](formerly the NES emulatorgameModule) is intentionally kept asnullptrso higher indices never shift.
- UI navigation references
-
FT812 Font Buffer Cap (
22,396Bytes) & Embedded Hardware Icons:-
kMaxFontBufferSizeincore/libs/NewDisplay/display.cppis22,396bytes (decompressedFontsCommonBuffer). Every individual font slot (both built-in RLE-compressed fonts and.ptfontslots on SD) must decompress to<= 22,396bytes. -
Font Slot 4 (
17px Bold, FT812 Handle 4) embeds 8 custom hardware icons at ASCII0x18..0x1F(24..31:Pause,Stop,Play,Rec,Folder,Up-dir,Loop,Arrow). If these are missing from a font, transport bar and file browser icons will appear blank. -
Font Slot 5 (
12px Regular, FT812 Handle 5) embeds Polish diacritics at ASCII0x11..0x1F(17..31).
-
-
Bootloader
.ptfFilename Filter & 31-Character Limit:- The firmware updater (
enListFileFilter_firmwareinplatforms/mk66/3rdparty/SD/SD.cppandplatforms/imx/sdmmc/sd/SD.cpp) only lists files in/Firmware/that end with.ptf, have total length>= 15, and start with:-
PolyendTrac(Original Tracker) -
TrackerPlus(Tracker+) -
TrackerMini(Tracker Mini)
-
-
31-Character Maximum on Original Tracker:
PlatformImpl::runBootloader()(platforms/mk66/source/PlatformImpl.cpp/platforms/imx/source/PlatformImpl.cpp) writes the selected.ptffilename to/Firmware/_fwinfo. The Original Tracker's on-chip bootloader reads/Firmware/_fwinfointo a 32-bytechar[32]buffer. Filenames of 32+ characters overwrite the trailing\0byte and cause garbage symbols on the bootloader flashing screen. Always keep.ptffilenames<= 31characters.
- The firmware updater (
All three devices share the same core/ codebase and are differentiated at compile time by preprocessor defines set in core/makefile, platforms/mk66/makefile, and platforms/imx/makefile.
| Target Scope | Preprocessor Condition | Matching Hardware & Typical Use Case |
|---|---|---|
| IMX Only (Tracker+ & Mini) | #ifdef PLATFORM_IMX |
600 MHz Cortex-M7, 64 MB SDRAM, stereo samples (SAMPLE_CHANNELS == 2), 16 tracks. |
| MK66 Only (Original Tracker) | #ifndef PLATFORM_IMX |
180 MHz Cortex-M4F, 16 MB SDRAM, stereo samples (SAMPLE_CHANNELS == 2), 16 tracks. |
| Tracker Mini Only | #ifdef TRACKER_MINI |
Handheld controls (interfaceButtonMiniMiddle, D-pad, battery gauge, internal mic, no pad grid). |
| Desktop Form Factor (Original & Plus) | #ifndef TRACKER_MINI |
Shared desktop hardware: 48 RGB silicone pads, rotary jog-wheel, FM radio, line/mic inputs. |
| Tracker+ Exclusively | #if defined(PLATFORM_IMX) && !defined(TRACKER_MINI) |
Features requiring both the IMX CPU/RAM and the 48-pad desktop interface. |
| Synth Audio Engine | #ifdef FEATURE_SYNTH |
Defined when PLATFORM=IMX; enables PolySynth and sets kSynthParts = 3 in core/config/config.h. |
| Synth UI Screens | #if GUI_HANDLE_SYNTH |
Defined as 1 (on PLATFORM_IMX) or 0 (on MK66) in core/interface/core/interfaceDefs.h. |
#if defined(PLATFORM_IMX)
// Runs on Tracker+ and Tracker Mini (600 MHz Cortex-M7)
#if defined(TRACKER_MINI)
// Tracker Mini only
#else
// Tracker+ only
#endif
#else
// Runs exclusively on Original Tracker (180 MHz Kinetis MK66)
#endif-
Gotchas with Preprocessor Guards:
-
Never use
#ifdef __MK66FX1M0__insidecore/: For legacy Teensy Audio library compatibility,core/makefiledefines-D__MK66FX1M0__in its baseDEFINESfor bothMK66andIMXbuilds. Always use#ifndef PLATFORM_IMX(or#if !defined(PLATFORM_IMX)) when writing code exclusively for the Original Tracker. -
Use
#if GUI_HANDLE_SYNTH(not#ifdef GUI_HANDLE_SYNTH): Incore/interface/core/interfaceDefs.h,GUI_HANDLE_SYNTHis always defined (1onPLATFORM_IMX,0onMK66), so#ifdef GUI_HANDLE_SYNTHwill mistakenly evaluate to true on the Original Tracker. -
Custom Build Flags (
CUSTOM_DEFINES): You can pass ad-hoc feature flags from the command line without editing makefiles viamake all CUSTOM_DEFINES="-DMY_EXPERIMENTAL_FEATURE". -
Platform-Specific
.ptfxPlugins:.ptfxSample Editor plugins are compiled once for all devices, but can restrict themselves to Tracker+ / Tracker Mini by settingPTFX_FLAG_IMX_ONLYin theirPtfxHeader::flags(editor-fx-sdk/tracker_plugin.h), or adapt dynamically at runtime by checkingchannels(1vs2) inplugin_process_block().
-
Never use
Tracker+ and Tracker Mini (PLATFORM_IMX) can expose a USB serial port that carries the firmware's log output and a small command console. Together with the existing USB storage mode, it lets a host script copy a new .ptf to the SD card and start the firmware update without touching the device or removing the card.
It is off unless you ask for it twice: the code is only compiled in with a build flag, and the port is only enumerated when the SD card is marked for development. A normal build on a normal card is unaffected.
| Switch | Where | Effect |
|---|---|---|
ENABLE_DEV_CONSOLE |
Build flag | Compiles the console (platforms/imx/source/DevConsole.cpp) and its SRAM_DTC ring buffer (docs/memory_map.md). Without it the console is replaced by empty inline stubs. |
ENABLE_LOG |
Build flag | Compiles the LOG() / LOGF() call sites (core/source/log.h) at the normal -O2 optimization level. DEBUG=1 also enables them, but additionally switches to -Og and changes boot behavior. |
/.develop |
Empty file in the SD card root | Develop mode (interfaceGlobals.devMode). With ENABLE_DEV_CONSOLE, the firmware adds the serial port to its USB configuration shortly after boot. Also shows the diagnostics on the Config screen. |
# Build a Tracker Mini image with the console and logging:
make mini CUSTOM_DEFINES="-DENABLE_DEV_CONSOLE -DENABLE_LOG"The makefiles do not track compiler flags, so run make clean when switching CUSTOM_DEFINES.
#include "log.h"
LOG("sequencer stop"); // appends a newline
LOGF("sequencer play from step %d\n", fromPos); // printf-style, no newline added- Output is queued in a ring buffer and sent from the main loop, so
LOG()/LOGF()may be called from the audio interrupt. If the buffer overflows, the excess is dropped and reported as@log dropped N bytes. -
Do not format floats (
%f) from interrupt context: newlib allocates from the heap to format them. Log scaled integers there instead. - Messages logged before the host opens the port are kept (up to the buffer size) and delivered when it does, so the boot log is not lost.
The port is a plain CDC-ACM serial port (baud rate is irrelevant). The host sends one command per line, terminated by \n or \r. Every reply is a single line that starts with @; anything else on the port is log output. A reply always begins on a fresh line, even if a log message was mid-line.
| Command | Reply | Action |
|---|---|---|
ping |
@tracker-dev <mini|plus> <build id> |
Identifies the device and the running build (BUILD_ID, see make version). |
storage on / storage off
|
@ok storage on|off, or @err storage is still on|off
|
Enters or leaves Config > USB > Storage mode. Refused while the interface is not in its normal run state (for example during project load). |
flash <name> |
@ok flash pending, then the device resets; or @err ...
|
Remounts the SD card, checks that /Firmware/<name> exists, then starts the same bootloader hand-off as Config > Firmware > Firmware update. <name> is a bare filename of at most 31 characters. |
reboot |
@ok reboot pending |
Resets the MCU (and makes a Tracker Mini start again without the power button). |
help |
@ok commands: ... |
Lists the commands. |
Anything else answers @err unknown command: ...; an over-long line answers @err line too long.
A scripted deployment is therefore:
-
ping, to find the device and note the running build. -
storage on, then close the serial port. The device waits for the port to close before it re-enumerates with the storage class. - Copy the
.ptfinto/Firmware/on the mounted volume and eject it. - Reopen the port and send
flash <name>. The device resets into the bootloader, which flashes the file. - When the port reappears,
pingagain and compare the build id.
Keep the port closed when using USB storage mode from the device's own menu. While a host holds the serial port open (for example to follow the log), the device postpones the USB re-enumeration that entering or leaving storage mode needs.
Recovery: a build that fails to boot has no console. Keep a known-good
.ptfin/Firmware/and use the recessed reset button as described in the README.
With ENABLE_DEV_CONSOLE, a CPU fault is reported on the console instead of freezing the device silently. This covers the hard fault and the memory-management, bus and usage faults: an invalid pointer, a jump to a bad address, an undefined instruction, a __builtin_trap().
@fault pc=6008d28c lr=6008d283 xpsr=61000000 cfsr=00000082 hfsr=00000000 mmfar=f0000000 bfar=f0000000 sp=20057f28 handler=4 build=dbfa648
@fault stack 600920cb 600c385d 60093125 600976fd 60090d35 60090d3d 6008f885 6007dde9 6010e789 600203a9
| Field | Meaning |
|---|---|
pc |
The instruction that faulted. After a jump to a bad address this is that address, and lr is where the jump came from. |
lr |
The return address of the function that faulted. |
xpsr |
Its low 9 bits are the exception that was running when the fault came: 0 is the main loop, 16 and up are interrupts (16 + IRQ number). |
cfsr, hfsr, mmfar, bfar
|
The Cortex-M fault status and fault address registers (SCB->CFSR and so on). |
sp |
The stack pointer at the fault. |
handler |
The exception that caught the fault: 3 hard fault, 4 memory management, 5 bus fault, 6 usage fault. |
build |
The build id of the running firmware, as in the ping reply. The addresses only mean something in the image of that build. |
@fault stack |
The words on the stack above the fault that look like return addresses, nearest first: a rough call chain. Addresses left over from earlier calls can appear in it. |
Turn the addresses into functions and source lines with the image the build left next to the .ptf:
arm-none-eabi-addr2line -f -C -e platforms/imx/build-MINI/TrackerMini.axf 0x6008d28c 0x6008d283- The firmware does not continue after a fault. It keeps the USB serial port alive from inside the fault handler, repeats the report every few seconds, and answers every console command with it, so a host that opens the port later still gets it. Power-cycle the device afterwards.
- Log lines queued before the fault are delivered before the report.
- If the stack pointer itself is invalid, a shorter
@fault cfsr=... no usable stackline is sent. - The report needs the serial port, so it needs develop mode (
/.develop). WithoutENABLE_DEV_CONSOLEthe fault handlers are the stock ones. - A semihosting breakpoint (
BKPT 0xAB) is still stepped over, as the stock hard fault handler does.
Full developer reference and C++ examples live in docs/global_file_browser.md (core/interface/fileBrowser/GlobalFileBrowser.h, GlobalFileBrowser.cpp).
-
One Shared Module Across Subsystems: Covers 6 modes (
kLoadWav,kSaveWav,kLoadGenericFile,kSaveGenericFile,kLoadFolderPackage,kSaveFolderPackage), used by Project Open / Save As / MOD & IT import, Synth Patch Load / Save As & Sample Slots, Sample Editor.ptfxfile parameters, and.ptpeffect presets. The multi-selection Sample Loader intentionally remains separate. -
Shared Scratch Partition: Runs inside a dedicated non-overlapping slice at the top of
externalRamScratchBuffabove.ptfxcode, working scratch, and secondary WAV buffers (docs/memory_map.md), preserving up to10LRU directory/cursor contexts (kMaxSavedContexts = 10) keyed bycontextKey. -
Navigation & FatFs Hygiene: Supports
Left-arrow jump-to-top in the Explorer pane, protected system folders (kProtectedFolders), inline metadata (onDescribeItem), and pad auditioning (onPadEvent). Callbacks inspecting files on cursor highlight must close FatFs handles immediately (closeFile(fh)withdeleteOnClose = true) and silence preview voices (silencePart/onPreviewStop) before loading the next asset.
-
AUDIO_NULL_IS_SILENCEStream Contract (core/libs/Audio/AudioStream.h,core/makefile):- Defined in
AudioStream.h(#ifndef AUDIO_NULL_IS_SILENCE, defaulting to1, alongside-DAUDIO_NULL_IS_SILENCE=1incore/makefile) and tested via#ifdef AUDIO_NULL_IS_SILENCE.receiveReadOnly()/receiveWritable()returningnullptrrepresents128samples of digital silence (0). Idle voices, idlePolySynthparts (isIdle()), muted mixers/muxes, and decayed effects omittransmit()rather than allocating and zero-fillingaudio_block_tblocks.AudioAmplifierandAudioEffectMonoToStereoskip work onnullptr, but still zero-fill andtransmit()when passed a non-null block at gain0; activePolySynthparts continue rendering pre-FX sends while active and omittransmit()onceisIdle(). -
Stateful DSP Rule: Stateful
AudioStreamnodes must drain acrossnullptrinputs before sleeping and wake on the next non-null block. Specifically,AudioFilterStateVariablesleeps once|state_lowpass|, |state_bandpass| < (1 << 12)(1output LSB,kSubLsbStateLimit) and|passSum| < (1 << 13)onnullptrinput;AudioEffectLimitersleeps viarelaxed(cleared after writing threshold/gain settings);AudioEffectPolyverbtracks16,384quiet feedback samples and releases right-channel blocks if the left input isnullptr;AudioEffectDynamicsreturns immediately onnullptrwithout continuing across silence (latent while line input transmits continuously). -
Feedback Order & Send Silence Queries:
AudioStream::hasLaterSourceis set inAudioConnection::connect()when a source lies after its destination inAudioStream::update_all()order (monotonic, never cleared), andAudioMixerBase::isInputSilenced(channel)lets upstream producers (AudioInputgates,PolySynthpre-FX sends) skip work when downstream send gains are0.
- Defined in
-
IMXITCM Memory Routines (platforms/imx/source/fastmem.S):- Places Thumb-2 32-byte burst (
ldmia/stmia,ldmdb/stmdb) and unaligned-safe wordmemcpy,memmove,memset, andmemcmpin.ramfunc.$RAM2(SRAM_ITC, landing near__end_data_RAM2) firmware-wide (replacingnewlib-nano's flashmemmove,memset, andmemcmp;memcpywas already placed in ITCM onmain). Safe for arbitrary alignments in Normal memory (SRAM_*,EXTERNAL_RAM,QSPI_FLASH); do not callmemcpy/memsetonDeviceperipheral registers (0x40000000+).
- Places Thumb-2 32-byte burst (
-
MK66ReverbEXTERNAL_RAM,.bssSplit &Q38.26Tick Clock:- On Original Tracker (
MK66),core/libs/Audio/effect_polyverb.cppplaces the32 KBinternalRamReverbBuffinEXTERNAL_RAM(.reverb_memory) to preserve internal SRAM heap/stack headroom, andplatforms/mk66/3rdparty/teensy_core/mk66fx1m0.ldsplits.bss_sram_l(< 0x20000000) and.bss(>= 0x20000000) so no symbol straddles theSRAM_L/SRAM_Uboundary (0x20000000). -
core/source/internalTickClock.h(InternalTickClock) drivesSequencer::tick()inQ38.26(2^-26µs) fixed-point integers instead of softwaredouble(softfp) math on Cortex-M4F/M7, and treats non-positive or non-finite tempo periods askNever(never advancing or accumulating catch-up ticks).
- On Original Tracker (
-
Live Audio CPU & Heap/Stack Diagnostics (
/.develop):- Placing an empty
/.developfile on the SD card enables live audio ISR CPU (min/max/avg/last %) andfreeRamBytes()heap telemetry on theConfigscreen across all 3 devices (pressingPlayorStopwhile onConfigresetsProfilercounters).Profiler::maxStackBytes()reports the measured stack watermark onIMXand returns0onMK66.
- Placing an empty