# HG changeset patch # User Michael Spacefalcon # Date 1378040082 0 # Node ID a2e793f6b8c4c57f2ee0bf884c8675b415e458e8 # Parent 57b8dbb029c20bb21794e2c72d878a94742a1aee some README files added diff -r 57b8dbb029c2 -r a2e793f6b8c4 README --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/README Sun Sep 01 12:54:42 2013 +0000 @@ -0,0 +1,32 @@ +You are looking at the top level of the freecalypso-sw source code tree. +The subtrees of this source tree are as follows: + +loadtools The suite of tools which run on a development host machine + (normally PC/Linux desktop or laptop) and communicate with + Calypso targets. Starting from the Calypso ROM bootloader, + these tools allow you to peek and poke registers, read and + program flash, and load and execute experimental code in IRAM + or XRAM. + +nuc-fw Nucleus-based firmware. This tree contains the early beginnings + of my (Michael Spacefalcon's) attempt to recreate TI's GSM + firmware suite running under Nucleus RTOS. The current code is + in the earliest embryonic stages of development, and does not + do anything useful yet. The RTOS code is FreeNucleus, based on + the Nucleus PLUS sources liberated by comrade XVilka and ported + to build with gcc and run on the Calypso by Spacefalcon the + Outlaw. + +target-utils These are utilities which run on Calypso targets, but which are + independent of Nucleus, of any other RTOS, and of any larger + firmware suite, i.e., totally standalone. The two current + utilities are loadagent, which is common for all currently + supported Calypso targets and is required in order to use + fc-loadtool or fc-xram (see loadtools), and pirexplore - the + latter is a hardware exploration utility specific to the + Pirelli DP-L10 target. + +toolchain Scripts and patches for building the gcc+binutils toolchain + targeting ARM7, the CPU core of the Calypso GSM/GPRS baseband + processor. You'll need to build and install this toolchain + first before you can build nuc-fw or target-utils. diff -r 57b8dbb029c2 -r a2e793f6b8c4 loadtools/README --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/loadtools/README Sun Sep 01 12:54:42 2013 +0000 @@ -0,0 +1,121 @@ +You are looking at the source for the FreeCalypso loadtools package. You may +have downloaded it either as a separate package or as part of the larger +freecalypso-sw suite. + +The tools in this package are written to run on some Unix/Linux machine +(normally a PC/Linux desktop or laptop) that acts as a host for operating on +Calypso target devices. All of these tools communicate with the Calypso target +through a serial port; each tool begins its operation by sending special byte +sequences to this serial port which are designed to interrupt the Calypso +device boot process in the ROM bootloader. + +Three utilities are currently built as part of FreeCalypso loadtools: + +fc-iram & fc-xram These utilities are intended for FreeCalypso developers + only. They load an S-record code image into IRAM or + XRAM, respectively, induce a transfer of control to the + loaded code, and then drop into a serial line pass-thru + mode for the operator to interact with the thus loaded + target code. + +fc-loadtool This utility is intended for both developers and end + users. After establishing communication with the + target, fc-loadtool drops into interactive operation. + Once at the loadtool> prompt, you can peek and poke + registers, and most importantly, dump (read) and load + (program) the flash memory of the target device. + +Loadagent + +Both fc-loadtool and fc-xram work by first feeding a FreeCalypso-developed +program called loadagent to the Calypso ROM bootloader; all further operations +(loading code into XRAM or flash) are done via this loadagent. An S-record +image of the loadagent program is required for fc-loadtool and fc-xram to work. +That program is in turn built with the ARM7 toolchain. + +If you are working with the full freecalypso-sw suite, you presumably already +have the proper ARM7 toolchain built and installed. To build loadagent, simply +run 'make' in the ../target-utils tree. + +If you have downloaded a separately-packaged version of FreeCalypso loadtools, +the package should have a prebuilt loadagent.srec image included, sparing +non-developer users the nontrivial hurdle of having to build and install a +special cross-compilation toolchain. The same loadagent binary is designed to +work on all supported Calypso targets. + +Building and installing loadtools + +Normally the machine on which you build and install fc-loadtools would be your +PC/Linux desktop or laptop, the system you would use to program or otherwise +interact with Calypso phones by way of appropriate USB-to-phone cables. Just +like loadagent, the host utilities you are going to build and install aren't +specific to a particular target device; instead you will select the target +device at run time via a command line option. Hence you can build and install +the host utilities (usual 'make' and 'make install') without limiting your +setup to just one target phone type. + +However, if your intended target device is an Openmoko GTA02 (or GTA01) +smartphone, there is one additional complication: one cannot directly access +the Calypso part of these phones from the outside without going through the +phone's application processor first. If you would like to use fc-loadtool to +read or write the GSM flash memory of your GTA0x (load a different firmware +image, dump the flash file system for backup or examination, restore a previous +backup etc), there are two ways to do it: + +1. The recommended way for FreeCalypso developers is to get a special serial + cable (low voltage, as in 3.3V or lower - *NOT* RS-232 levels - please don't + fry your precious phone!) that would plug into the 2.5mm jack on the left + side of the phone that is normally intended for a wired headset. This way + you can use your regular build of fc-loadtool (and fc-iram & fc-xram) on + your PC/Linux (or other) development host, no need to build anything for + GTA0x AP, and all communication happens directly between your development + host and the Calypso part of your target phone - not going through the AP + at all. You still need working software on the GTA0x AP to do battery + management, to power the Calypso block on and off, and to enable the headset + jack "download" path, but it is much less burdensome than having to do the + actual FreeCalypso work from the AP. + +2. If you are an end user who simply wishes to reflash a different GSM firmware + image, it can be done from inside the phone (from the AP) without having to + acquire special hardware (as in the cable described above). However, the + trade-off is that in return for saving on the special hardware, you have to + do more work on the software. You will have to use a cross-compiler + targeting the ARM/Linux AP environment (*not* the ARM7 cross-compiler used + for the GSM firmware itself!) to build fc-loadtools to run on the GTA0x AP. + +Building loadtools for GTA0x AP + +If you've decided to build loadtools for the GTA0x AP, you'll need to make the +following modifications to the Makefile: + +* Change the CC= line to point to the appropriate cross-compiler (which you'll + need to provide yourself); + +* Change the CFLAGS= line: add the right options to target the ARM920T core in + the GTA0x AP (e.g., -march=armv4t -mtune=arm920t), and add -DGTA0x_AP_BUILD + to enable some code that makes sense only when running on the GTA0x AP. + +* Change EXTRA_OBJ= to EXTRA_OBJ=gtapower.o, i.e., add gtapower.c (compiling + into gtapower.o) to the build. + +See gta-ap-build.sed for an example. + +Running fc-loadtool + +Once you've got loadtools built and installed, you can run fc-loadtool +as follows: + +To operate on a Pirelli DP-L10 that appears as /dev/ttyUSB0: + +fc-loadtool -h pirelli /dev/ttyUSB0 + +To operate on the Calypso block of a GTA02, accessing it from an external +PC/Linux host via a USB-to-headset-jack serial cable that appears as +/dev/ttyUSB0: + +fc-loadtool -h gta02 /dev/ttyUSB0 + +To operate on the Calypso block of a GTA02, running fc-loadtool from inside the +phone, i.e., from the AP of the same GTA02: + +fc-loadtool -h gta02 /dev/ttySAC0 diff -r 57b8dbb029c2 -r a2e793f6b8c4 target-utils/README --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/target-utils/README Sun Sep 01 12:54:42 2013 +0000 @@ -0,0 +1,16 @@ +Two programs are currently buildable in this target-utils tree: loadagent and +pirexplore. Loadagent is built to be loaded and run out of the Calypso internal +(on-chip) RAM, and does not depend on any hardware outside of the Calypso chip +itself - thus it should run unchanged on all Calypso targets. It expects to be +loaded by the Calypso ROM bootloader in the UART download mode, and it reads a +RAM variable left behind by the ROM code that indicates which UART has been used +to perform that download - it then uses that same UART to communicate with the +host, presenting an interactive command prompt. You can run loadagent "raw" by +loading loadagent.srec with fc-iram, but normally it is used "behind the scenes" +by fc-loadtool and fc-xram. + +Pirexplore is built in the same manner as loadagent (also runs out of IRAM, +expects to be loaded with fc-iram, and presents an interactive command prompt +on the autodetected UART), but it automatically performs some hardware (board +level) initialization specific to the Pirelli, and offers additional commands +for exploring the hardware features of this device.