Firmware/Recovery
We call a badly programmed laptop "bricked", because the only use it seems to have is to pile upon other bricked laptops.
There are ways to recover, and they are documented according to how general the solution is, and how frequently they happened to us.
Prevention
A better approach is to prevent the situation:
- use rapid prototyping to test changes on the running firmware first; it is very flexible for this, with full access to all features from command prompt,
- restrict changes to non-critical parts of the software stack; so that the early initialisation of Open Firmware is unaffected, and can still be halted using one of several methods,
- review changes before building,
- use the same toolchain that we do, see Firmware/Building,
- ask us to test your build, see @devel mailing list,
- always reflash with battery and external power; this is normally enforced by the flash command,
- never remove power during reflash; this causes a mix of old version and new version, breaking the dictionary.
Design Features
Open Firmware is loaded from an SPI FLASH ROM. Recovery is done by reprogramming or replacing the SPI FLASH ROM, using whatever tools or technologies are available.
Background: It is common with other embedded systems to use a complex connection such as JTAG. Using a JTAG to program the SPI FLASH ROM is a challenge. We've done that only once or twice during the first day of bringup, and never since. To do it, Open Firmware is loaded into memory using JTAG, then Open Firmware is executed and used to write to the SPI FLASH ROM. We do not recommend using JTAG in this way. There are easier ways, which arise from design features.
On XO-1.75 and XO-4:
- CForth is in the SPI FLASH ROM from 0x0 to 0x20000, is rarely changed, and is available first, having been loaded by the SoC,
- Open Firmware is in the SPI FLASH ROM from 0x20000, and is loaded by CForth,
- both CForth and Open Firmware initialise and respond to input from the serial console very early, before completing full initialisation.
- both CForth and Open Firmware are a single thread of execution, so a fault in a device driver has no effect until that device is accessed. Interrupts are used very rarely.
On XO-1 and XO-1.5:
- Open Firmware initialises and respond to input from the serial console very early, before completing full initialisation.
- Open Firmware is a single thread of execution, so a fault in a device driver has no effect until that device is accessed. Interrupts are used very rarely.
Recovery on XO-1.75 and XO-4
The usual methods to recover are:
- press the escape key to get the ok prompt and then reflash to the older version; this feature available to serial console, display, and keyboard, and only these devices have been initialised,
- hold the rotate key down (one of the front panel keys) during power up, manually start Open Firmware from CForth, and then reflash to the older version; this feature available to serial console only.
- interrupt CForth in the same way above, but do not start Open Firmware, instead reflash over the serial port. See SPI_FLASH_Recovery_for_XO-1.75_Using_CForth or SPI_FLASH_Recovery_for_XO-4_Using_CForth.
- tether the SPI FLASH ROM between two main boards, e.g. SPI_FLASH_Recovery/XO-4,
- use an SPI FLASH reprogramming instrument,
- remove and replace the SPI FLASH ROM, e.g. XO_Replacing_SPI_flash,
Recovery on XO-1 and XO-1.5
The usual methods to recover are:
- press the escape key to get the ok prompt and then reflash to the older version; this feature available to serial console, display, and keyboard, and only these devices have been initialised,
- interrupt Open Firmware using the 'i' key on the serial console, correct the problem, then reflash,
- tether the SPI FLASH ROM between two main boards, e.g. SPI_FLASH_Recovery_for_XO-1.5,
- use an SPI FLASH reprogramming instrument,
- remove and replace the SPI FLASH ROM, e.g. XO_Replacing_SPI_flash,