# HG changeset patch
# User Mychaela Falconia <falcon@freecalypso.org>
# Date 1583708010 0
# Node ID 3a41d69e8104fba9146b00851bb9460d396f54ca
# Parent  b6b8307d195b1ab4647e88a6a514e5b2d5754a9d
doc/Flash-programming: added section about discontiguous m0 images

diff -r b6b8307d195b -r 3a41d69e8104 doc/Flash-programming
--- a/doc/Flash-programming	Sun Mar 08 22:15:57 2020 +0000
+++ b/doc/Flash-programming	Sun Mar 08 22:53:30 2020 +0000
@@ -78,6 +78,36 @@
 'flash e-program-bin 0 fwimage.bin' - but don't *ever* do it on a Mot C1xx
 phone!
 
+Discontiguous m0 fw images with large gaps
+==========================================
+
+One sometimes-advantage of S-record-based formats over straight binary is that
+they can have discontiguous filled regions with gaps in between them; all m0 fw
+images produced by TI's TCS211 build system have some gaps in them.  In our
+current FC Magnetite firmwares these gaps have been reduced to less than 16384
+bytes in total, reducing the wasted disk space and image transfer time to
+sufficiently insignificant if these m0 images are converted to straight binary
+with mokosrec2bin and then flashed as binary as we've been doing.  For
+comparison, in Openmoko's classic mokoN firmwares (almost TI's original version
+of the memory map) the first flash sector of 65536 bytes had only 5072 bytes of
+image payload programmed into it, thus indirect programming via mokosrec2bin
+followed by flash program-bin meant sending just over 60k filler 0xFF bytes to
+be flashed - becomes noticeable at 115200 baud.
+
+But these gaps were even bigger in TI's classic firmwares (and many vendor
+firmwares) built for 8 MiB or 16 MiB flash chips with TI's classic memory map.
+They have two code regions: one region is exactly 4 MiB in size but is placed
+not quite at the beginning, thus spilling past the chip midpoint, and the other
+region starts where the first 4 MiB region ends, going to the end of the flash
+chip or to the beginning of the area reserved for FFS.  The way TI's linker
+works results in the first of these two program regions being not quite full
+before bits start getting thrown into the second one, thus the resulting m0
+image can easily have a gap of a megabyte or more between the two regions.
+TI's own FLUID handles such discontiguous images with no sweat, but our
+fc-loadtool has gained matching capability only as of fc-host-tools-r13 with
+our new e-program-m0 command.  And yes, it is smart enough to avoid needlessly
+erasing sectors in the big gap, just like FLUID.
+
 Flash backup and restore
 ========================