# HG changeset patch # User Mychaela Falconia # Date 1493695470 0 # Node ID de8f75783b3b88b9cb92b88a4ff04e896aa1c4a5 # Parent 064d4eedb3a6479965b7c756f55326bde9b4d664 Flash-boot-defect and Flash-boot-modes documentation diff -r 064d4eedb3a6 -r de8f75783b3b doc/Flash-boot-defect --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Flash-boot-defect Tue May 02 03:24:30 2017 +0000 @@ -0,0 +1,49 @@ +As of this writing (2017-05-01), there is an unexplained hardware problem on +some of our FCDEV3B boards in that flashed firmware images which use flash boot +mode 1 (see the Flash-boot-modes article) fail to boot. It is not currently +known how many boards are affected by this problem; it is possible that the +Mother's S/N 001 board is the only one that exhibits this oddity. + +This problem particularly affects our FC Magnetite firmware, as the latter uses +flash boot mode 1 just like TI's TCS211 fw from which it originates. OTOH, our +FC Citrine firmware, which uses flash boot mode 0, boots just fine. A minimal +test case has been created under target-utils/flash-boot-test in this +repository: it is a simple loadagent-like standalone application that is built +to be booted from flash instead of expecting to be loaded serially, and it is +built in two versions, one for mode 0 and another for mode 1. Both versions +work on an Openmoko-made GTA02 (the mode 1 version continuously reboots every +few seconds because it doesn't disable the watchdog timer, but it is still very +clearly alive) as well as on those FCDEV3B boards which aren't affected, but on +FCDEV3B S/N 001 the mode 1 version fails to boot just like the full Magnetite +firmware. + +The Mother of FreeCalypso does not currently have any prognosis as to when or +even if the mysterious hardware problem that causes flash boot mode 1 to fail +can be fixed. Logical reasoning tells us that it must be a hardware problem, +as the flash boot mode in question works without a hitch on every pre-existing +Calypso device known to us, and similar logical reasoning tells us that the +watchdog timer probably has to be involved in some way, as it is the mechanism +underlying flash boot mode 1 (again, see the Flash-boot-modes article), but I +am at a total loss when it comes to what kind of board-level problem could +possibly produce such behaviour. But then if only the S/N 001 board is affected +and no others, it could just be a defective chip. More data points need to be +gathered before we shall know whether or not we have a real problem. + +For those who do have a flash-boot-challenged FCDEV3B board, two workarounds +have been developed, in this chronological order: + +1. One can boot the board in the serial download mode, and download a + teensy-tiny piece of code that disables the boot ROM and jumps to address 0. + If the flash contains a firmware image meant to be booted in mode 1, this + image will get indirectly booted in this manner. Run a command like this: + +fc-iram -h fcfam /dev/ttyXXX /opt/freecalypso/target-bin/flash-boot-wa.srec rvinterf + +(fc-iram has been extended to support second program invokation just like + fc-xram, just for this peculiar use case. The flash-boot-wa.srec helper can + also be booted via fc-xram.) + +2. After doing the above, I found a way to patch the Magnetite firmware image + to boot in mode 0 - see the Flash-boot-mode-hack write-up in the Magnetite + source tree. With this patch applied, FC Magnetite happily boots directly + from flash on my board without needing fc-iram or fc-xram assistance. diff -r 064d4eedb3a6 -r de8f75783b3b doc/Flash-boot-modes --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Flash-boot-modes Tue May 02 03:24:30 2017 +0000 @@ -0,0 +1,52 @@ +The Calypso chip includes an on-die boot ROM that allows the boot process to be +interrupted and diverted by an external host sending some special characters +into either of the two UARTs; this mechanism is what allows us to load code into +RAM and to reload the flash on Calypso GSM devices without having to resort to +JTAG or chip desoldering or other extreme measures. In normal operation, when +the boot path is NOT being diverted by an external serial download, the boot ROM +transfers control to the regular firmware in the flash - but there are two +different modes in which the flash fw image may be booted. + +In order for the flash fw image to be considered bootable by the Calypso boot +ROM, the 32-bit word at flash address 0x2000 must equal either 0 or 1; if it +equals any other value, the boot ROM will consider the flash fw image to be +invalid (e.g., blank flash) and will wait forever for a serial download instead +of proceeding with flash boot. Depending on whether this word at 0x2000 equals +0 or 1, the flash fw image will be booted in one of two very different ways; +we shall call them flash boot mode 0 and flash boot mode 1, respectively. + +In flash boot mode 0 the following 32-bit word at flash address 0x2004 must +contain the address of the flash fw image entry point (ARM/Thumb selection in +the least-significant bit); the boot ROM will simply jump to this address with +a BX instruction. When the flash fw image is booted in this manner, the boot +ROM is still mapped at address 0 and the first 8 KiB of flash are inaccessible +except via the 0x03000000 alternate mapping, unless the firmware later changes +the 0xFFFFFB10 register. This boot mode is intended for flash fw images that +use the interrupt and exception vectors in the ROM (branching to IRAM addresses +0x80001C-0x800034) for their interrupt and exception handling. + +Flash boot mode 1 is different: instead of jumping directly to the flash fw +image, the boot ROM copies a small piece of its code into IRAM and jumps to that +code; the copied code disables the boot ROM via the 0xFFFFFB10 register (puts +the external flash at address 0) and induces a processor reset through the +watchdog timer. It is not clear to us exactly what blocks are affected by the +watchdog reset, but bits 9:8 of the 0xFFFFFB10 register are not reset, hence +the ARM processor now boots from the reset vector in the flash as if the boot +ROM weren't there - and the latter really is not there after having disabled +itself. + +Flash boot mode 0 is only usable on Calypso C035 silicon (the "new" kind); +while all commercial Calypso GSM devices targeted by FreeCalypso feature Calypso +chips of the correct "new" kind, the people at TI who wrote and maintained their +official firmware also had to work with older Calypso C05 chips featured on the +early D-Sample and Leonardo boards. The earlier boot ROM code version in those +early Calypso chips also implements the two boot modes which we call mode 0 and +mode 1, but its implementation of mode 0 is broken and unusable, therefore TI's +firmware people only used flash boot mode 1. On the other hand, newer firmware +designs made for current rather than historical hardware will probably find +mode 0 to be cleaner, more intuitive and more convenient. + +All TI official firmwares use flash boot mode 1, our FreeCalypso Magnetite +firmware does likewise, being a direct derivative of TI's TCS211 fw, but our +FC Citrine firmware uses flash boot mode 0, as that part of the Citrine fw is +our own original design.