Where does everyone document their memory maps?

I gave up on drawings years ago after a project where the diagram on the wiki said the app started at 0x08010000 and the bootloader had actually been written to expect 0x0800C000. Spent two days chasing that. Since then the linker script is the only source of truth and I refuse to maintain anything that can disagree with it. What I do instead is keep the partition offsets in one shared header that both the bootloader and the app include, so there is literally one definition of where things live. Then I have a small build step that runs arm-none-eabi-size and greps the map file, and the output gets dumped into the release notes automatically. It is not a pretty diagram but it can never be stale, because it comes from the same build as the binary. For the internal flash plus external storage case, I treat them as two separate tables but both headers live in the same repo and get included by anything that touches either. The bugs you describe almost always come from a magic number typed somewhere else, so my rule is that any offset not coming from that header fails the review.

Honestly the notebook sketches were never the problem, the second copy of the truth was.

We bake the layout into the flash itself. First sector of the external storage holds a small manifest: a magic number, a version, partition name, start, length, and a checksum. The bootloader reads it, the app reads it, and our host-side programming tool reads it. Nothing drifts because everything agrees with what is physically on the chip, and when the layout changes the manifest goes with it. If the checksum fails at boot the device refuses to start rather than guessing where things are, wich beats discovering the disagreement after an OTA image lands in the wrong slot.

For internal flash I still treat the linker script as the truth, same as the poster above, that side never bit us hard enough to need more machinery.

The habit that acutally caught bugs was a build step that pulls the resolved addresses from the map file and diffs them against the manifest. CI fails on any mismatch. It costs nothing to run and it caught a real overlap last spring when someone grew the app image and silently stomped the settings block on an STM32L4 with a W25Q64 hanging off QSPI. One wrinkle worth planning for: the very first boot on a blank board has no manifest, so the factory programming step has to write it before anything else runs. Get that ordering wrong once and you will not forget it.

Disagree with the header-everything approach though. I tried that on a project once and the header drifted from the linker script anyway, becuase someone changed the .ld file and not the header, and the build happily linked app code into the middle of the config region. Two sources of truth, even if you call one a header. What actually fixed it for us was a unit test in CI that parses the map file and asserts the section sizes against the header, so a mismatch fails the build instead of failing in the field. Is anyone else checking this kind of thing automatically, or is it all eyeball and review?

Been doing this since the days when the only documentation was a printout taped to the wall next to the JTAG pod. What saved me was printing the memory map into the binary itself. I stick a versioned struct with the partition table into a fixed spot in flash, and the build tool reads it back after programming. If the layout changes and something forgot, the checksum screams at you on the first boot instead of two weeks later in the field. Only headache is OTA updates, since the table itself needs a migration path when the layout shifts under an allready deployed unit. Anyone handling that mid-air update case?