Qt for MCUs — build, flash, execute, allocate

One file in, one object out

Every QML file produces a matching generated .cpp/.h pair, and every generated .cpp compiles to its own .o exactly like hand-written source. By the time the compiler sees them there is nothing special about the generated files.

QML → C++: the element tree becomes statically constructed C++ objects. Their storage lands in .bss, their construction code in .text.
JS → C++: binding expressions become C++ functors compiled into the same object file. Only the supported subset translates; anything needing runtime evaluation fails the build rather than the device.
Binding dependencies are emitted as a fixed-size node pool, sized at build time. Exhausting it means restructuring QML, not resizing at runtime.

Consequence: QML complexity shows up as flash and static RAM in the map file, not as heap pressure.

Images: format decided on the host

The resource compiler emits bytes in exactly the layout the blitter will consume, so nothing is converted per frame.

An asset stored in a different pixel format than its target layer costs a conversion on every draw. Matching them is usually the cheapest performance win available.
Uncompressed in memory-mapped flash costs no RAM — the blitter reads it scanline by scanline. This is why large artwork belongs in external flash.
Compressed costs RAM, because it must be decoded into a cache before it can be blitted. You are trading flash bytes for cache bytes plus first-use CPU.
Caching policy is global with per-resource overrides, so backgrounds can be cached while one-shot assets are not.

Correction: qulrcc handles images and generic binary resources. Fonts take a completely different path — next stage.

The font path, corrected

Fonts do not go through qulrcc. They have their own build-time step, and what it emits depends entirely on which font engine the project is configured for.

Static engine — rasterisation happens on your build machine. Flash receives finished glyph bitmaps for a known character set at known sizes. The device does no rasterising and needs no glyph cache, but cannot render a size or character you did not declare.
Vector engine — flash receives subsetted outlines. The device rasterises each glyph the first time it is needed and keeps the result in a glyph cache, with a second cache for shaped text layout.
The charset comes from string literals in QML plus translation files, or from an explicit list. Strings built dynamically in C++ are the case that forces a vector engine.

Measured: on a text-heavy screen, glyph retrieval, text layout and text blend together made up roughly 58% of paint time. Font engine choice is a rendering decision, not just an asset decision.

kinematics.cpphand-written C++

float solveIK(const Pose &p) { … 40 lines … }

→.textinternal flash · XIP

static const float kArmLength[6] = { 1.2f, 0.9f, … };

→.rodataread in place

static int calibOffset = 42;

→.data imgcopied to SRAM

static float jointAngle[6];

→.bssno flash cost

MainScreen.qml → MainScreen.cpp → MainScreen.ogenerated

Rectangle { … } — the object instance itself

→.bsspermanent RAM

construction + property-set code for that tree

→.textinternal flash

Text { text: "SPEED" } — the literal

→.rodatainternal flash

text: speed * 1.6 — JS binding, now a C++ functor

→.text+ node in .bss

Image { source: "gauge_bg.png" } — pixel data

→resource blobexternal flash

Assetsfrom stages 02 and 03

gauge_bg.png — large, uncompressed

→resource blobread in place

icon_warn.png — small, boot-critical

→.rodatainternal flash

Roboto — static engine: baked glyph bitmaps

→.rodatainternal flash

Roboto — vector engine: subsetted outlines

→font blobexternal flash

Internal code flash · memory mapped · executable4 MB

vectors

.text — solveIK, MainScreen ctor, binding functors, Qul core, platform port

.rodata — kArmLength, "SPEED", icon_warn, static glyphs

.data img — calibOffset

unused

programmed as app.hex

External flash over SMIF · memory mapped · read-onlyQSPI / HyperFlash

resource blob — gauge_bg.png, needle_seq, atlases

font outline blob

streamed map tiles

unused

programmed separately as resources.bin

Every declaration has a destination

One source file scatters across four different places. The rule is the same for hand-written and generated code, which is why the generated files need no special treatment.

Executable code — flash only, never copied. This includes the code that builds the QML tree and every translated JS binding.
Const data — flash only, read in place. String literals, lookup tables, baked glyph bitmaps.
Initialised globals — pay twice: an image in flash and a live copy in SRAM.
Uninitialised globals and every QML object instance — SRAM only, zero flash cost. This is the largest hidden RAM consumer in a big QML project.
Pixel and outline data — the resource blob in external flash, addressed directly.

Reading it back: if a screen adds flash but no RAM, you added artwork and code. If it adds RAM but little flash, you added QML objects.

moves flash → SRAM at startup stays in flash, read in place stays in external flash claimed, never copied

What moves, what stays

Moves: the .data initialiser image, and any function you placed in RAM or TCM. Two copy loops in startup, and that is all that is ever copied.
Claimed, not copied: .bss is zeroed in place — the whole QML object tree appears in RAM with no flash source. Graphics buffers and caches are claimed the same way at platform init.
Stays put: .text and .rodata in internal flash; the resource and font blobs in external flash. All four are read directly over the memory-mapped bus.

So code executes from internal flash, in place, with cache and prefetch hiding the wait states. Moving a routine to RAM is an explicit, measured exception.

In the map file: a section whose load address differs from its run address is one of the two things that gets copied. Matching addresses mean it never leaves flash.

Where layer buffers actually live

Not on the system heap. On a part with a dedicated VRAM region, the linker script gives VRAM its own memory region and the platform layer engine claims buffers from it statically during init — no malloc, no contention with application allocation.

Buffers are the largest single claim. Double buffering costs two full frames; layer dimensions and bit depth move the number directly.
The front buffer belongs to the display controller for the entire scanout. Writing into it mid-scan is what causes tearing.
Caches are reserved at their configured size whether or not they fill. When a glyph cache thrashes, the symptom is rising paint time — not an allocation failure.

Worked figures: 2 MB VRAM at 96% occupancy with roughly 83 KB spare; glyph layout cache 16,384 of 18,432 bytes; text cache about 63 KB of 196 KB.

On parts with no dedicated VRAM the buffers are carved out of general SRAM instead — and then they do come from the same pool as the heap.

VRAM region — dedicated, does not touch the heap2 MB · 96% occupied

front + back buffers

additional layer buffers

image + glyph + text caches

~83 KB

claimed statically at platform init — never malloc'd

System SRAM — the heap comes from hereheap = the remainder

.data

.bss — Qul object tree · dependency node pool

task + core stacks

.ramfunc / TCM

driver + RTOS buffers

free heap

fixed at link time available for allocation

Consumer	Region	Fixed at	Reduces heap?
Layer / frame buffers	VRAM	platform init	no — separate region
Image / glyph / text caches	VRAM	build config	no — separate region
.data + .bss	SRAM	link time	yes
Task and core stacks	SRAM	link / RTOS config	yes
RAM-resident functions	SRAM / TCM	linker script	yes
Free heap	SRAM	whatever survives	the remainder

Two budgets, not one

This is the distinction worth being precise about: on a part with a dedicated VRAM region, VRAM pressure and heap pressure are separate failures with separate fixes.

VRAM full → layer configuration problem. Reduce layer dimensions, drop bit depth, cut a layer, or shrink cache sizes.
Heap exhausted → static footprint problem. Object tree size, stack depth, RTOS and driver buffers.
Track minimum-ever free heap, not current free. It captures the worst transient, which is where a fault actually lands.

Observed: full-widget configurations bottomed out around 8.9–10.5 KB minimum free heap, against roughly 50 KB with content stripped back — while VRAM stayed pinned near 96% throughout. The two numbers moved independently.

Tuning order: layer size and pixel format first, cache sizes second, QML object tree last — the last needs restructuring, not a config change.