FreeCalypso > hg > fc-magnetite

annotate doc/Bootloader @ 695:530f71d65c20

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
uartfax.c: pull from Tourmaline (GTM900 RI output) In addition to the primary intent of bringing in GTM900 RI output support, pulling uartfax.c wholesale from Tourmaline also changes the initial_time argument in the two NU_Create_Timer() calls from 0 to 1. This change is required for the new version of Nucleus used in Tourmaline and Selenite (and apparently also used by TI in LoCosto), and it is harmless (no effect) for the original TCS211 version of Nucleus used in Magnetite. The new philosophical model being adopted is that Tourmaline is our new development head firmware, whereas Magnetite will now be maintained similarly to how Linux maintainers treat stable kernels: changes will be backported from Tourmaline if they are deemed appropriate for stable modem firmware.
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 24 Oct 2020 17:33:10 +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.