# HG changeset patch # User Space Falcon # Date 1431286529 0 # Node ID 4fa939eada224361f1264fed1fee3e4b64b7528c # Parent 78c894c7c4716db99ef12e9310c8ecb3bcd4baa1 documentation update: how to compile and flash experimental gsm-fw for gtamodem diff -r 78c894c7c471 -r 4fa939eada22 doc/Compiling --- a/doc/Compiling Sun May 10 05:28:05 2015 +0000 +++ b/doc/Compiling Sun May 10 19:35:29 2015 +0000 @@ -65,3 +65,58 @@ Run 'make all' in target-utils to build some other components that aren't really needed. + +Compiling FreeCalypso GSM firmware +================================== + +The firmware in our gsm-fw tree can be built in many different configurations, +hence there is no singular build for it. The configuration choices consist of: + +* Which target device the firmware should be built for: the target device + selection is made at compile time; do not attempt to take a firmware image + built for one target device and flash or fc-xram it into another! + +* What functionality is to be included. As the FreeCalypso firmware subproject + moves forward, we gradually add chunks of functionality, slowly approaching + what each target device is ultimately capable of. However, each time we add + a new piece of functionality, the ability to build a firmware image that works + like before, without the newly added functionality, still remains. Each + feature to be included needs to be explicitly selected. + +* Miscellaneous configuration: which Calypso UART should be used for what, + should the firmware use a real FFS (flash file system) in flash or a fake one + in RAM, etc. + +The GSM firmware build configuration is set by way of an editable text file +named build.conf; the configuration and build procedure is as follows: + +1. Look at the available repertoire of standard configurations under + gsm-fw/configs and choose which one you would like to use, either as-is or + as a basis for your own; + +2. Copy the configuration you selected to build.conf in the gsm-fw directory; + +3. Optionally edit it to taste - the configuration language is Bourne shell; + +4. Run 'make' in the gsm-fw directory. + +Depending on the configuration, either a flashable or a RAM-loadable image will +be built by default. A flashable image will appear in finlink/flashImage.bin; +these images are meant to be programmed with fc-loadtool's flash program-bin +command; the starting flash address at which the image needs to be programmed +depends on the target device - see target-specific notes. A RAM-loadable image +will appear in finlink/ramImage.srec; these images are meant to be loaded and +run with the fc-xram utility. + +It is possible to build either a flashable or a RAM-loadable image, or both, +without changing build.conf: run 'make flashImage' or 'make ramImage' as +desired. (The compilation of each module from source into a .o and all +intermediate linking steps are agnostic to whether a flashImage or a ramImage +is being built, only the very final link step differs.) Any otherwise working +configuration can be built into a flashImage, even if it makes no logical sense +to do so, but the ability to build a ramImage for a given configuration depends +on the code image size (which in turn depends on the selected feature set) and +the amount of RAM available on the target in question: most Calypso GSM devices +have small RAM, enough to satisfy a GSM firmware's data space requirements, but +not enough to hold the entire firmware code in RAM as well. Please see target- +specific notes for more details. diff -r 78c894c7c471 -r 4fa939eada22 doc/Freerunner-Howto --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Freerunner-Howto Sun May 10 19:35:29 2015 +0000 @@ -0,0 +1,57 @@ +How to play with FreeCalypso GSM firmware on a Neo Freerunner +============================================================= + +Aside from the half-source leo2moko fw we produced back in 2013-10 (you can +read all about that one at www.freecalypso.org/leo2moko/), we don't have a +working free GSM firmware version for the Freerunner yet. What we do have +currently is experimental code that can be built into an image that can be +flashed into a GTA02 modem - but it doesn't really work yet. + +If you would like to play with our experimental code on your Neo FR and maybe +help us make it work, here are the instructions: + +1. Build the firmware in the gtamodem-gsm configuration - see the Compiling + document for more details; + +2. You should get a flashImage.bin image built; now you need to flash it into + your FR's modem. The serial cable method is highly recommended: the only + thing you'll be able to do with our current non-working firmware is help us + debug it, and the serial cable will be needed for the latter part anyway. + +3. Run fc-loadtool the same way you would if you were flashing leo2moko; + +4. The actual flash programming commands are a little different because the + image is smaller and in a different format: + +flash erase 0 0x160000 +flash program-bin 0 finlink/flashImage.bin + +The second number in the flash erase command needs to be the size of +flashImage.bin rounded up to a multiple of 64 KiB (the flash sector size in the +GTA02 modem); 0x160000 is correct for the fw image size as of this writing, but +please double-check it yourself before flashing. The 0 argument in the +flash program-bin command is the flash offset at which the image should be +programmed: it will always be 0 for FreeCalypso flashable fw images for gtamodem +and other targets that have the Calypso boot ROM enabled in the hardware. + +Once you have flashed our experimental fw into your modem, you can power-cycle +the modem and see the new fw boot. You should have the serial cable connected, +the serial channel enabled from the Freerunner's AP side and either rvtdump or +rvinterf running on your PC or other development machine when you first power +your modem up with the experimental fw in it: this way you will see whether the +fw boots successfully or crashes. If it does boot without crashing (whether or +not it does seems to depend on some factors which we have yet to understand), +you will get an AT command interface on the other UART going to the Freerunner's +AP - now go ahead and play from there. :) + +To reflash your modem back to stable and working leo2moko aka moko12, execute +the following fc-loadtool commands: + +flash erase 0 0x230000 +flash program-m0 leo2moko.m0 + +(Whichever firmware image you are flashing, the flash erase command needs to + cover the range of flash sectors this image will occupy. You can erase more + sectors up to 0x300000, the "natural" boundary of the flash area where fw + images live, but I prefer to erase only the needed number of sectors: it is + both faster and imposes less wear on the flash.)