FreeCalypso > hg > fc-magnetite

annotate doc/Bootloader @ 688:5806383e2788

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Compiling: update for luna1, luna2 and tangomdm
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 12 Oct 2020 19:17:23 +0000
parents fbf0fabc5505
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
526
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 As we understand it, TI's earlier DBB (digital baseband processor) chips prior
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 to our Calypso did not have an on-chip ARM boot ROM: instead they would execute
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 code directly out of flash immediately out of reset, like our Calypso does when
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 its boot ROM is disabled with nIBOOT high. To get the firmware code into the
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 flash initially, one had to either use JTAG or populate preprogrammed chips
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 onto the board, and if you bricked your flash, you were screwed without JTAG.
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 To assist with loading new firmware images during casual development, TI
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 incorporated a bootloader stage into their firmware architecture. This
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 bootloader stage is placed at the beginning of the flash at the reset vector,
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 and the rest of the firmware begins at an erase unit boundary. The bootloader
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 stage executes first, and before it jumps to the main firmware entry point
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 (_INT_Initialize) for normal boot, it offers an opportunity for the boot process
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 to be interrupted and diverted if an external host sends certain magic command
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 packets into either of the two UARTs during the allotted time window. If the
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 external host does interrupt and divert the boot process in this manner, it can
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 feed a code image to the bootloader to be written somewhere in target RAM, and
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 then command the bootloader to jump to it. It is exactly the same functionality
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 (though with different serial protocol specifics) as implemented in the Calypso
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 boot ROM. The ROM version is obviously superior because it is unbrickable, but
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 the flash-resident, built-with-firmware version is what TI used before they
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 came up with the idea of the boot ROM for the Calypso.
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 When the boot-ROM-equipped Calypso came along, TI kept the flash-resident
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 bootloader in the firmware: it does no harm aside from adding a little bit of
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 delay to the boot process, it does not conflict with the ROM bootloader as the
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 two speak different serial protocols and respond to different interrupt-boot
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 sequences, and it allowed TI to keep the same firmware architecture for
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 platforms with and without a boot ROM. (Using flash boot mode 1, TI's firmwares
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 boot and run exactly the same way whether the Calypso boot ROM is present and
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 enabled or not.) However, in our FreeCalypso firmwares starting with Magnetite
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 we have removed this extra bootloader stage for the following reasons:
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 * It is not useful to us on any of our hardware targets: on those devices that
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 have the Calypso boot ROM enabled, we use that boot ROM and get full
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 unbrickability, whereas on Mot C1xx phones we have to work with Mot/Compal's
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 own different bootloader and serial protocol at least initially, hence it
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 makes the most sense to stick with the same after the conversion to
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 FreeCalypso as well.
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 * As delivered by TI with their full production TCS211 fw releases, their
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 firmware-resident bootloader works as intended only on hw platforms with
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 13 MHz VCXOs like the original D-Sample (Clara RF), and is broken on platforms
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 like Rita RF (the only RF chip for which we have driver code!) with 26 MHz
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 VCXOs: there is no conditionally-compiled code anywhere in the bootloader
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 code path to set the VCLKOUT_DIV2 bit in the CNTL_CLK register on 26 MHz
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 platforms, thus the UARTs are fed with 26 MHz instead of the standard 13 MHz
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 clock expected in normal operation, and the intended baud rate of 115200 bps
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 turns into 230400. Because 230400 bps is a baud rate which Calypso UARTs
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 *cannot* produce in normal GSM operation (when the peripheral clock network
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 runs at the expected 13 MHz), tools that are designed to talk to Calypso GSM
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 devices are typically not designed to support this baud rate. In particular
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 for CP2102 USB-serial adapters, the precedent established by the factory
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 CP2102 EEPROM programming in the Pirelli DP-L10 phone is that the baud rate
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 entry for 230400 bps is replaced with 203125 bps, which is a valid baud rate
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 for Calypso UARTs running at 13 MHz.
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 * We have no source for TI's firmware-resident bootloader, only linkable binary
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 objects that came with our world's last surviving copy of TCS211, which are
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 incompatible with our goal of blob-free firmware.
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 Because this extra bootloader stage is ultimately unnecessary in our
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 environment, the deblobbing goal was easier accomplished by removing it
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 altogether instead of expending effort on a blob-free replacement. Because I
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 wasn't comfortable with modifying TMS470 assembly code and linker script magic,
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 the removal of the bootloader was accomplished by stubbing out its C body with
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 an empty function. A 'build_lib bootloader' instruction in a firmware
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 configuration recipe causes a dummy do-nothing bootloader to be built from this
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 stubbed-out source.
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 We have been removing (stubbing out) the bootloader from our TCS211-based
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 firmwares since 2015, but in 2018-09 I (Mother Mychaela) finally took the time
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 to study TI's bootloader code via disassembly and finally figured out what it
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 does and how it works. Now that it is no longer an unknown, it may be
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 interesting to build some fw images with this bootloader blob re-enabled for
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 experimentation purposes, and a new experimental (not for production!)
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 l1reconst-bl configuration has been created for this purpose. The bootloader
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 blob has also been re-enabled in the classic configuration, whose only purpose
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 is to serve as a reference point that preserves almost everything from our
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 TCS211/Leonardo starting point.
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 Finally, it needs to be noted for the sake of completeness that Compal's
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 bootloader used on Mot C1xx phones is a modified version based on TI's original
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 bootloader. However, this factoid matters only for historians and genealogists;
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 for all practical purposes it is an unrelated animal, as Mot/Compal's serial
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 protocol for interrupting and diverting the boot process is their own and bears
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 no resemblance to TI's version. And yes, Mot/Compal's version does set the
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 VCLKOUT_DIV2 bit in the CNTL_CLK register to adjust for the 26 MHz clock input
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 as its first order of business; it was probably the very first issue they had
fbf0fabc5505 doc/Bootloader written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 to fix.