# HG changeset patch # User Mychaela Falconia # Date 1537595978 0 # Node ID fbf0fabc5505f438eabe854b97a63443fb15ff46 # Parent ecdb7aed6d3a5bccd5dca4606a47b68d0c405abf doc/Bootloader written diff -r ecdb7aed6d3a -r fbf0fabc5505 configs/l1reconst-bl --- a/configs/l1reconst-bl Sat Sep 22 03:40:04 2018 +0000 +++ b/configs/l1reconst-bl Sat Sep 22 05:59:38 2018 +0000 @@ -1,5 +1,5 @@ # This configuration is a variant of l1reconst with the old bootloader -# blob re-enabled. +# blob re-enabled - see doc/Bootloader for more information. GPRS=1 MMI=0 diff -r ecdb7aed6d3a -r fbf0fabc5505 doc/Bootloader --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Bootloader Sat Sep 22 05:59:38 2018 +0000 @@ -0,0 +1,90 @@ +As we understand it, TI's earlier DBB (digital baseband processor) chips prior +to our Calypso did not have an on-chip ARM boot ROM: instead they would execute +code directly out of flash immediately out of reset, like our Calypso does when +its boot ROM is disabled with nIBOOT high. To get the firmware code into the +flash initially, one had to either use JTAG or populate preprogrammed chips +onto the board, and if you bricked your flash, you were screwed without JTAG. + +To assist with loading new firmware images during casual development, TI +incorporated a bootloader stage into their firmware architecture. This +bootloader stage is placed at the beginning of the flash at the reset vector, +and the rest of the firmware begins at an erase unit boundary. The bootloader +stage executes first, and before it jumps to the main firmware entry point +(_INT_Initialize) for normal boot, it offers an opportunity for the boot process +to be interrupted and diverted if an external host sends certain magic command +packets into either of the two UARTs during the allotted time window. If the +external host does interrupt and divert the boot process in this manner, it can +feed a code image to the bootloader to be written somewhere in target RAM, and +then command the bootloader to jump to it. It is exactly the same functionality +(though with different serial protocol specifics) as implemented in the Calypso +boot ROM. The ROM version is obviously superior because it is unbrickable, but +the flash-resident, built-with-firmware version is what TI used before they +came up with the idea of the boot ROM for the Calypso. + +When the boot-ROM-equipped Calypso came along, TI kept the flash-resident +bootloader in the firmware: it does no harm aside from adding a little bit of +delay to the boot process, it does not conflict with the ROM bootloader as the +two speak different serial protocols and respond to different interrupt-boot +sequences, and it allowed TI to keep the same firmware architecture for +platforms with and without a boot ROM. (Using flash boot mode 1, TI's firmwares +boot and run exactly the same way whether the Calypso boot ROM is present and +enabled or not.) However, in our FreeCalypso firmwares starting with Magnetite +we have removed this extra bootloader stage for the following reasons: + +* It is not useful to us on any of our hardware targets: on those devices that + have the Calypso boot ROM enabled, we use that boot ROM and get full + unbrickability, whereas on Mot C1xx phones we have to work with Mot/Compal's + own different bootloader and serial protocol at least initially, hence it + makes the most sense to stick with the same after the conversion to + FreeCalypso as well. + +* As delivered by TI with their full production TCS211 fw releases, their + firmware-resident bootloader works as intended only on hw platforms with + 13 MHz VCXOs like the original D-Sample (Clara RF), and is broken on platforms + like Rita RF (the only RF chip for which we have driver code!) with 26 MHz + VCXOs: there is no conditionally-compiled code anywhere in the bootloader + code path to set the VCLKOUT_DIV2 bit in the CNTL_CLK register on 26 MHz + platforms, thus the UARTs are fed with 26 MHz instead of the standard 13 MHz + clock expected in normal operation, and the intended baud rate of 115200 bps + turns into 230400. Because 230400 bps is a baud rate which Calypso UARTs + *cannot* produce in normal GSM operation (when the peripheral clock network + runs at the expected 13 MHz), tools that are designed to talk to Calypso GSM + devices are typically not designed to support this baud rate. In particular + for CP2102 USB-serial adapters, the precedent established by the factory + CP2102 EEPROM programming in the Pirelli DP-L10 phone is that the baud rate + entry for 230400 bps is replaced with 203125 bps, which is a valid baud rate + for Calypso UARTs running at 13 MHz. + +* We have no source for TI's firmware-resident bootloader, only linkable binary + objects that came with our world's last surviving copy of TCS211, which are + incompatible with our goal of blob-free firmware. + +Because this extra bootloader stage is ultimately unnecessary in our +environment, the deblobbing goal was easier accomplished by removing it +altogether instead of expending effort on a blob-free replacement. Because I +wasn't comfortable with modifying TMS470 assembly code and linker script magic, +the removal of the bootloader was accomplished by stubbing out its C body with +an empty function. A 'build_lib bootloader' instruction in a firmware +configuration recipe causes a dummy do-nothing bootloader to be built from this +stubbed-out source. + +We have been removing (stubbing out) the bootloader from our TCS211-based +firmwares since 2015, but in 2018-09 I (Mother Mychaela) finally took the time +to study TI's bootloader code via disassembly and finally figured out what it +does and how it works. Now that it is no longer an unknown, it may be +interesting to build some fw images with this bootloader blob re-enabled for +experimentation purposes, and a new experimental (not for production!) +l1reconst-bl configuration has been created for this purpose. The bootloader +blob has also been re-enabled in the classic configuration, whose only purpose +is to serve as a reference point that preserves almost everything from our +TCS211/Leonardo starting point. + +Finally, it needs to be noted for the sake of completeness that Compal's +bootloader used on Mot C1xx phones is a modified version based on TI's original +bootloader. However, this factoid matters only for historians and genealogists; +for all practical purposes it is an unrelated animal, as Mot/Compal's serial +protocol for interrupting and diverting the boot process is their own and bears +no resemblance to TI's version. And yes, Mot/Compal's version does set the +VCLKOUT_DIV2 bit in the CNTL_CLK register to adjust for the 26 MHz clock input +as its first order of business; it was probably the very first issue they had +to fix.