FreeCalypso > hg > freecalypso-tools

annotate doc/Flash-programming @ 820:03457a66d860

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
buzplayer: add basic support for PWT
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 30 May 2021 03:39:58 +0000
parents a7496a1e0df7
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
676
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 Our Calypso device flash programming tool fc-loadtool can be used in several
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 different paradigms; this article is an attempt to clarify the many available
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 modes of usage. You should also read the companion article Binary-file-formats
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 for further background.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 Flashing firmware release images
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 ================================
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 In conventional forward engineering environments where you develop or maintain
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 firmware for hardware made by your own company (meaning no reverse eng, no
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 "illicit" aftermarket tinkering on hw made by some other company aeons ago),
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 you have a firmware build system that produces fw build images (some of which
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 may subsequently be blessed as releases), and you have a tool that flashes
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 these fw build images into your hardware, operating as efficiently as possible,
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 automated as much as possible, requiring minimal user action for the boring
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 repetitive task of flashing a new fw image every time you build one. And if
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 you become lucky enough to produce your hardware in volume, the same objectives
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 of maximal efficiency and automation carry over into the production line
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 environment as well.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 In TI's environment the standardized format for firmware build images which are
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 then flashable into hardware targets was a variant of Motorola SREC written in
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 *.m0 files, a variant which we have named moko-style m0 after its most famous
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 user. The special quirk of this particular SREC variant is its peculiar byte
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 order. TI's firmware build system produces a *.m0 S-record image as its final
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 build product, and TI's official Calypso flash programming tool (FLUID) takes
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 these *.m0 files as its input.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 Since the beginning of FreeCalypso we have had two ways of flashing TI-built
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 firmware images into suitable targets (initially OM GTA02 modem, then many
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 others including our own FCDEV3B):
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 1) Our fc-loadtool has had a flash program-m0 command from the beginning,
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 programming device flash with bits from an m0 file directly and natively.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 However, prior to fc-host-tools-r12 this command was poorly supported: it
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 ran significantly slower than flash program-bin, had poorer progress
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 indication and did not perform CRC-32 verification at the end, which is an
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 important integrity check. Also this original flash program-m0 command (as
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 opposed to flash e-program-m0 added in fc-host-tools-r13) does not include a
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 built-in erase step, thus prior to fc-host-tools-r13 the user had to have
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 outside knowledge of how many sectors to erase first with a separate flash
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 erase command.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 The new flash e-program-m0 command added in fc-host-tools-r13 is m0 image
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 flashing finally done right. It reads in the specified S-record image in
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 moko-style m0 format, builds a map of potentially discontiguous flash
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 regions into which the image deposits bits, erases the set of flash sectors
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 which need to be erased before programming these regions, then programs the
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 new image bits into flash, exactly like TI's own FLUID.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 2) The alternative way is to first convert the *.m0 S-record image produced by
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 TI's hex470 post-linker tool into straight binary (*.bin) with a FreeCalypso
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 tool called mokosrec2bin, then program the binary fw image into flash with
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 fc-loadtool command flash program-bin. This method is the one we've been
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 using since 2017, and our FC Magnetite firmware build system is now set up
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 to produce not only fwimage.m0, but also fwimage.bin (it runs mokosrec2bin),
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 and it also generates an fc-loadtool command script (a text file named
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 flash-script) with two commands in it: a flash erase command with a
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 calculated sector address range and a flash program-bin command to program
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 the accompanying fwimage.bin image.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 As of fc-host-tools-r13 both methods work equally well: if you have an official
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 FreeCalypso firmware release (containing fwimage.m0, fwimage.bin and
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 flash-script files) which you need to flash into a device such as our own
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 FCDEV3B or OM GTA02 (but *not* Mot C1xx!), you can execute either
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 'exec flash-script' or 'flash e-program-m0 fwimage.m0' at the loadtool> prompt,
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 and both ways will produce exactly the same result with equal performance and
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 reliability. And if you need a more special operation such as erasing the
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 entire flash (factory production lines) or erasing and reprogramming only a
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 certain part of the normally affected sector range, that's what custom command
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 scripting ability is for.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 For the sake of symmetry, we also have a flash e-program-bin command that is a
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 binary image format counterpart to flash e-program-m0: it first erases the
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 sectors into which new bits will be programmed, then programs the new bits.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 Thus a third equally good way to flash a new FreeCalypso fw release into a
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 target such as FCDEV3B or GTA02 is to execute
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 'flash e-program-bin 0 fwimage.bin' - but don't *ever* do it on a Mot C1xx
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 phone!
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80
677
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
81 Discontiguous m0 fw images with large gaps
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
82 ==========================================
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
83
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
84 One sometimes-advantage of S-record-based formats over straight binary is that
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
85 they can have discontiguous filled regions with gaps in between them; all m0 fw
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
86 images produced by TI's TCS211 build system have some gaps in them. In our
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
87 current FC Magnetite firmwares these gaps have been reduced to less than 16384
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
88 bytes in total, reducing the wasted disk space and image transfer time to
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
89 sufficiently insignificant if these m0 images are converted to straight binary
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
90 with mokosrec2bin and then flashed as binary as we've been doing. For
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
91 comparison, in Openmoko's classic mokoN firmwares (almost TI's original version
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
92 of the memory map) the first flash sector of 65536 bytes had only 5072 bytes of
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
93 image payload programmed into it, thus indirect programming via mokosrec2bin
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
94 followed by flash program-bin meant sending just over 60k filler 0xFF bytes to
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
95 be flashed - becomes noticeable at 115200 baud.
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
96
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
97 But these gaps were even bigger in TI's classic firmwares (and many vendor
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
98 firmwares) built for 8 MiB or 16 MiB flash chips with TI's classic memory map.
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
99 They have two code regions: one region is exactly 4 MiB in size but is placed
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
100 not quite at the beginning, thus spilling past the chip midpoint, and the other
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
101 region starts where the first 4 MiB region ends, going to the end of the flash
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
102 chip or to the beginning of the area reserved for FFS. The way TI's linker
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
103 works results in the first of these two program regions being not quite full
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
104 before bits start getting thrown into the second one, thus the resulting m0
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
105 image can easily have a gap of a megabyte or more between the two regions.
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
106 TI's own FLUID handles such discontiguous images with no sweat, but our
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
107 fc-loadtool has gained matching capability only as of fc-host-tools-r13 with
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
108 our new e-program-m0 command. And yes, it is smart enough to avoid needlessly
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
109 erasing sectors in the big gap, just like FLUID.
3a41d69e8104 doc/Flash-programming: added section about discontiguous m0 images
Mychaela Falconia <falcon@freecalypso.org>
parents: 676
diff changeset
110
676
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111 Flash backup and restore
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
112 ========================
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
114 A completely different paradigm takes place on alien targets such as Motorola
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115 C1xx and Pirelli DP-L10, made by alien manufacturers, meaning not FreeCalypso,
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
116 not Openmoko and not TI. The most important flash operation on these alien
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
117 targets is making a flash dump; these dumps can then be used for forensics,
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
118 reverse engineering, or simply as a backup. When we subsequently write to
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
119 flash on these alien targets (after having saved a backup first), we are not
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
120 flashing an m0 fw image or a binary image made from one with mokosrec2bin,
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
121 instead the most common operations are:
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
122
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
123 * Flashing a backup image back into the same device it was originally made
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
124 from (flash restore);
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
125
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
126 * Changing a device from one firmware version to a different one by programming
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
127 its flash with firmware bits that were originally read out from some fw-donor
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
128 unit;
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
129
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
130 * Surgical manipulations such as erasing FFS sectors or rewriting one specific
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
131 part of the flash based on reverse-engineered understanding of its structure.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
132
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
133 This different paradigm leads to a different mode of usage for fc-loadtool:
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
134 instead of needing a maximally-automated operation that flashes a firmware
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
135 release image with as little user thought involvement as possible, our flash
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
136 manipulations need to be of a more manual peek-n-poke manner. We provide a
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
137 flash dump2bin command for making and saving flash dumps first and foremost,
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
138 allowing any part of the flash to be dumped and saved selectively if desired,
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
139 including the second flash bank on the Pirelli DP-L10 and likewise on our own
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
140 FCDEV3B. When it comes to flash write operations, we provide a manual flash
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
141 erase command that allows (and requires) the operator to specify exactly which
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
142 sector range should be erased and a manual flash program-bin command that
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
143 allows any range of 16-bit words to be programmed at any flash address, with
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
144 the bits to be programmed coming from a binary file, either the whole file or
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
145 any specified subrange.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
146
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
147 These manual flash erase and flash program-bin commands give full control to
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
148 the operator, allowing every possible flash manipulation which the hardware
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
149 itself allows, at the expense of requiring the operator to think about which
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
150 flash addresses, offsets and lengths need to be operated on, and either enter
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
151 long commands manually or write a command script.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
152
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
153 Given our historical origins (long before we got to the point of producing our
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
154 own hardware, we started out by exploring the forbidden GSM realm of devices
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
155 made by alien manufacturers who were hostile to our cause), our original flash
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
156 manipulation support in fc-loadtool had been centered around the manual
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
157 peek-n-poke paradigm, with elementary flash erase and flash program-bin commands
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
158 as our main staple, and no thought had been given originally to producing
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
159 functionality that would work like FLUID or like our current flash e-program-m0
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
160 and e-program-bin commands. But all actively maintained software evolves, and
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
161 as our FreeCalypso family of projects has matured over the years, we now offer
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
162 richer functionality covering a wider range of use cases.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
163
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
164 Binary vs. S-records
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
165 ====================
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
166
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
167 (Please read the companion article Binary-file-formats for background, then
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
168 come back here.)
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
169
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
170 If you are exploring and manipulating the flash content of a GSM device in an
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
171 aftermarket fashion, as opposed to flashing your own fw builds into your own hw
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
172 design produced by your own company like Openmoko did in the late 2000s and
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
173 like we do currently at FreeCalypso HQ, then binary is the generally preferred
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
174 format: you make dumps with flash dump2bin, and when you selectively program
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
175 these images back into devices, you use flash program-bin with the right offsets
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
176 and length, along with appropriate flash erase commands.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
177
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
178 We also have flash dump2srec and flash program-srec commands in fc-loadtool,
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
179 they were implemented back in the founding stage of FreeCalypso in 2013 for the
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
180 sake of completeness and symmetry (it seemed right to support both binary and
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
181 S-record formats), but they never got any practical use: if you are making a
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
182 flash dump, you would normally want to examine it afterward, and any such
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
183 examination almost always needs a straight binary image, not S-records.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
184 Furthermore, our flash program-bin command allows you to selectively program
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
185 just a particular portion of a binary image file into flash, at any arbitrary
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
186 flash address, but we don't have the same flexibility with flash program-srec -
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
187 the latter command is really just a sibling of program-m0 with the opposite
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
188 byte order.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
189
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
190 Thus the short summary is as follows:
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
191
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
192 * If you are flashing an official firmware release image into your device, you
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
193 need to use flash e-program-bin or flash e-program-m0 depending on whether
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
194 the image is provided in *.bin or *.m0 format, or alternatively our older
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
195 flash program-bin or flash program-m0 commands preceded by a separate flash
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
196 erase command with the right sector range, possibly packaged in a supplied
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
197 fc-loadtool command script.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
198
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
199 * If you are restoring a flash dump made with flash dump2bin or performing
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
200 aftermarket flash manipulations on Mot C1xx or Pirelli DP-L10 phones or other
682
a7496a1e0df7 doc/Flash-programming: typo fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 677
diff changeset
201 such alien devices, you need to use binary-format-based flash manipulation
676
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
202 commands; the specific commands will depend on exactly what you are seeking
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
203 to do.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
204
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
205 * flash program-srec and e-program-srec commands do not currently have a valid
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
206 use case.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
207
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
208 Special considerations for Compal phones
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
209 ========================================
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
210
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
211 Motorola C1xx and Sony Ericsson J100 phones made by Compal have brickable flash:
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
212 the right kind of flash-resident bootloader must always be present at the
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
213 beginning of the flash, or else the phone is unrecoverably bricked. We have
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
214 special support in fc-loadtool for minimizing the bricking vulnerability window
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
215 when operating on these phones, but this special support requires user
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
216 cooperation, meaning that you must limit your flash manipulations on these
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
217 phones to a narrower subset:
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
218
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
219 * flash program-m0, program-srec, e-program-m0 and e-program-srec commands are
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
220 not appropriate for these brickable phones - do not use any of these commands
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
221 on these targets.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
222
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
223 * Flash sector 0 must be manipulated only with the special
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
224 flash erase-program-boot command, not any of the regular erase or program
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
225 commands.
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
226
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
227 * Regular flash erase, flash program-bin and flash e-program-bin commands can
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
228 and should be used for the rest of the flash starting at offset 0x10000 - but
b6b8307d195b doc: new articles Binary-file-formats and Flash-programming
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
229 you still need to understand what you are doing.