FreeCalypso > hg > freecalypso-tools

annotate doc/Flash-programming @ 1011:6d9b10633f10 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
etmsync Pirelli IMEI retrieval: fix poor use of printf() Bug reported by Vadim Yanitskiy <fixeria@osmocom.org>: the construct where a static-allocated string was passed to printf() without any format arguments causes newer compilers to report a security problem. Given that formatted output is not needed here, just fixed string output, change printf() to fputs(), and direct the error message to stderr while at it.
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 23 May 2024 17:29:57 +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.