--- a/doc/C139-Howto	Sun Jan 14 21:00:21 2018 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,184 +0,0 @@
-Running FreeCalypso firmware on the Motorola C139
-=================================================
-
-Mot C139 phones are brickable - because the Calypso boot ROM is disabled by PCB
-wiring, the ability to reflash a phone with new firmware critically depends on
-there being a particular kind of boot code in flash sector 0 at all times - a
-particular kind of boot code that allows the boot process to be interrupted and
-diverted to external code loaded via the headset jack serial port.
-
-The FreeCalypso project has adopted one specific version of the flash sector 0
-boot code (produced by applying a binary patch to one of Compal/Motorola's
-original versions) for use with all of our firmwares for this target.  No matter
-which FreeCalypso firmware you are running - Citrine, Magnetite or tcs211-c139 -
-you flash your FC fw image at offset 0x10000 while keeping this boilerplate boot
-code at the beginning of the flash:
-
-ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/compal-flash-boot-for-fc.bin
-
-We are currently able to produce two kinds of firmware builds for the C139:
-pseudo-modem or UI demo.  The pseudo-modem configuration is intended for those
-who would really like to play with AT-command-controlled modem firmware on some
-proper Calypso modem hardware like our desired FCDEV3B, but who are using a
-C139 instead out of poverty - a poor man's substitute for proper modem hardware.
-In this configuration the C139 phone's LCD stays dark, the buttons do nothing,
-but the firmware presents TI's RVTMUX interface with FreeCalypso extensions on
-the headset jack serial port.  You connect to this serial interface with
-FreeCalypso host utility rvinterf, and use another FC host utility fc-shell to
-talk AT commands to the pseudo-modem.
-
-If you flash a C139 phone with one of our pseudo-modem firmware builds, it will
-behave in some odd ways which you might not expect:
-
-* Whenever the phone is off but the battery is inserted, even a momentary
-  accidental press of the power button will launch a full power-on and firmware
-  boot - without any visible indication whatsoever as the LCD stays dark!
-
-* Once the firmware has booted from a press of the power button - even a
-  momentary accidental press - there is no way to make it shut down and power
-  off except by sending a power-off command via the headset jack serial port.
-  So it will just keep running until the battery runs down, once again with the
-  LCD dark and no visible indication of any kind that it's on.
-
-In the UI demo configuration (see Handset-configs) the FC-reflashed C139 acts
-*almost* like an end user phone: it can be operated from the keypad without
-being connected to a PC with a serial cable, there is a very rudimentary UI
-presented on the LCD, the phone can be turned on and off with the power button.
-However, battery charging doesn't work, there is not even a working battery
-gauge, and the UI is full of serious bugs.  Thus this fw configuration is
-intended as a DEMO, not something to be inflicted on an actual end user!
-
-Additional considerations are:
-
-* Flashing a given phone back and forth between FreeCalypso and Mot/Compal's
-  official firmware is a royal pita, so if you are going to play with
-  FreeCalypso on a C139, it would be the easiest to dedicate a phone
-  specifically for FC experiments;
-
-* We haven't got firmware-controlled battery charging working yet in any of our
-  fw configurations, so you will need another phone running one of the official
-  fw versions to charge batteries.
-
-Converting a phone to FreeCalypso
-=================================
-
-Start by installing FreeCalypso host tools on your PC/laptop or whatever host
-you will use to talk to C139 phones, if you haven't already.  If you are
-starting with an unhacked C139 phone running one of the official firmware
-versions, the procedure for flashing and bringing up FreeCalypso for the first
-time is as follows:
-
-* Note down your phone's factory IMEI.  After you get FreeCalypso firmware
-  flashed and running, you will need to set your own IMEISV, as our fw doesn't
-  know how to grok Mot/Compal's flash data structures where they store theirs.
-  You can set whatever IMEISV you like, but if you would like to keep the
-  factory one, it would be the easiest to have it noted down on a piece of
-  paper.  If you have a labelmaker, you can print a sticky label with the IMEI
-  and stick it on the side of the phone where you can easily see it later while
-  playing with FreeCalypso.
-
-* Get in with fc-loadtool, preceded with tfc139 if necessary - see FC host tools
-  documentation.
-
-* Once you are in with fc-loadtool, i.e., at the loadtool> prompt, reflash the
-  boot sector with the FreeCalypso version:
-
-  loadtool> flash erase-program-boot compal-flash-boot-for-fc.bin
-
-* Flash whichever FreeCalypso firmware image you would like to play with, e.g.:
-
-  loadtool> flash erase 0x10000 0x230000
-  loadtool> flash program-bin 0x10000 fwimage.bin
-
-  Please note that the image size will be different depending on which
-  configuration of which FC fw project you would like to play with, so adjust
-  the second number in the flash erase command accordingly - it needs to be
-  the fw image size rounded up to a 64 KiB sector boundary.
-
-* Erase the flash sectors to be used for the FFS (flash file system) by
-  FreeCalypso firmwares:
-
-  loadtool> flash erase 0x3C0000 0x30000
-
-* Exiting fc-loadtool cleanly will cause it to power off the phone:
-
-  loadtool> exit
-
-Reflashing between different FreeCalypso firmwares
-==================================================
-
-By the conventions established in the FreeCalypso project, all of our firmwares
-for the C139 target have the following in common:
-
-* They all stay out of the boot sector and expect to receive control from the
-  boot code in the same manner (boot entry point at 0x10058, exception vectors
-  at 0x10000), thus there is no need to reflash the dangerous boot sector when
-  going from one FC firmware to another.
-
-* They all use the same aftermarket FFS configuration of 3 sectors of 64 KiB
-  each (64x3) at 0x3C0000.  This FFS location is deliberately different from
-  the one used by Mot/Compal's firmwares, eliminating the possibility of one fw
-  trying to use the FFS created by the other, and by putting our FFS toward the
-  end of the flash we maximize the amount of flash space available for our
-  firmware code images.  But even though we don't share our FFS with
-  Mot/Compal's official firmwares, we do share the same FFS between all of
-  FreeCalypso firmware projects - thus once you have initialized your FFS (see
-  below) with one FC firmware version, it will work with the others as well.
-
-If you need to reflash your C139 from one FC firmware version to another,
-simply get in with fc-loadtool -h compal (no more need for the inefficient
--c 1003 or -c 1004 options or for tfc139) and reflash just the fw image part:
-
-loadtool> flash erase 0x10000 0x230000
-loadtool> flash program-bin 0x10000 fwimage.bin
-
-First boot of the firmware
-==========================
-
-Connect the serial cable, but instead of running fc-loadtool, run rvinterf.
-Press the red power button on the phone briefly just like you would for
-fc-loadtool entry.  Because there is no fc-loadtool running on the host end of
-the serial cable, the boot path will *not* be diverted in the bootloader, and
-the main fw image will run - and this time it will be the FreeCalypso firmware
-you have compiled and flashed.  If the fw you have flashed is the UI demo
-configuration, the phone must have *NO* SIM in it the first time you boot it.
-UI-enabled fw configuration automatically bring up the GSM radio and try to
-connect to the default network on boot if there is a SIM present, and you don't
-want your firmware trying to connect to a real live GSM network when you haven't
-initialized your FFS yet.  If the fw you have flashed is one of the AT-command-
-controlled pseudo-modem configurations, then you don't need to worry if the SIM
-is there or not on your first boot - just don't command it to connect to a
-network until you have initialized the FFS.
-
-If you have flashed a non-UI firmware version, the phone's LCD will remain dark
-as there is no LCD driver code in this firmware, but you will see trace output
-in the rvinterf window, telling you that the fw is running.
-
-Before you do anything else, you will need to run fc-fsio and initialize the
-aftermarket FFS for our firmware:
-
-fsio> format /
-fsio> mk-std-dirs
-fsio> set-imeisv fc XXXXXXXX-YYYYYY-ZZ (punctuation optional, place anywhere)
-fsio> set-rfcap dual-eu (if you have 900+1800 MHz hardware)
-or
-fsio> set-rfcap dual-us (if you have 850+1900 MHz hardware)
-
-After you've initialized your FFS as above, you should exit fc-fsio, and your
-next steps will depend on which fw configuration you are playing with.  If it's
-the sans-UI pseudo-modem configuration, run fc-shell and try some AT commands:
-
-AT+CMEE=2	-- enable verbose error responses
-AT+CFUN=1	-- enable radio and SIM interfaces
-AT+COPS=0	-- register to the default GSM network
-
-When you are done, you can power the phone off by sending a 'poweroff' command
-through fc-shell.  The only other way is to yank the battery, and doing the
-latter is recommended anyway: when a phone with the present hack-firmware
-flashed into it is powered off but still has the battery inserted, even a
-momentary accidental press of the power button will cause it to power on and
-boot, but there will be absolutely no visual indication, as the LCD stays dark.
-
-If you are playing with the UI demo firmware, after you have initialized your
-FFS, you can power the phone off with the power button, insert a SIM, power it
-back on and play with the primitive UI.