Posted May 31st 2012
This note is about two ways to upgrade the firmware on Corelatus hardware. For one-offs, you can use a browser-based upgrade. For large installations, it's easier and much faster to use a program which talks to the GTH's API on port 2089.
All GTH hardware Corelatus has ever shipped (at the time of writing: GTH 1.x, GTH 2.x and the RAN probe) uses the same principles and methods for upgrading the firmware.
GTH has two completely separate firmware images. That way, things like a power failure in the middle of an upgrade, or a corrupt firmware image won't leave you with a 'bricked' system.
The two firmware images on the GTH are called system and failsafe. During everyday operation, the system image is used, it supports the full set of GTH commands. In exceptional circumstances, for instance while upgrading, the failsafe image is used. The failsafe image provides just enough functionality to support upgrading and troubleshooting.
catch-22: You can't use the browser-based upgrade systems running firmware from before May 2010, you need at least gth2_failsafe_10 and gth2_system_34a.
For installations with tens or hundreds of modules, upgrading via a webbrowser is a waste of time. It's better to use the GTH's API on port 2089.
The quickest way to get started with that is to use Corelatus' sample code. We have working examples in
C: install_release.c, included in the C sample code.
Java: gth_upgrade.jar, included in the Java sample code.
The API-driven upgrade checks what firmware version is running, reboots the system to the 'failsafe' firmware, installs the release and checks that the installation succeeded. Breaking that down into steps:
Do that by issuing a query command
<query>
<resource name="system_image"/>
</query>
The GTH replies with something like:
<state>
<resource name="system_image">
<attribute name="version" value="development_release_9"/>
<attribute name="locked" value="false"/>
<attribute name="busy" value="true"/>
</resource>
</state>
You can tell that the GTH is running the system_image because busy=true. There are three circumstances under which the failsafe image may be booted:
Images are not upgraded in-place, so if we want to upgrade the system image, we need to boot failsafe first. Do that by setting the failsafe boot mode
<set name="os">
<attribute name="boot mode" value="failsafe"/>
</set>
and then sending a reset command:
<reset>
<resource name="cpu"/>
</reset>
To make it a bit harder to accidentally upgrade a system, you have to 'unlock' an image before upgrading it:
<set name="system_image"> <attribute name="locked" value="false"/> </set>
Upgrades to the image are standard compressed 'tar' archives.
Install them using the install command:
<install name="system_image"/>
The actual archive is sent immediately following the install command, in a block with content type 'binary/filesystem'.
The GTH sends an ok response after the filesystem has finished transferring. The actual install process continues after the transfer, an event is sent when it completes:
<event><info reason="install_done"/></event>
If you reboot without waiting for the install_done message, you'll probably get a corrupted installation. Start again from the top.
A query of the system image, as shown above, reveals the version number of the installed image. An install which has not completed shows up as empty.
Finally, we reboot again. If the system fails to boot after five attempts, the failsafe system starts.
Upgrading the failsafe image is analogous to upgrading the system image. A special failsafe firmware release file is used.