--- /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.

--- /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

--- /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.