--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/C155-target	Sat Oct 13 20:01:28 2018 +0000
@@ -0,0 +1,64 @@
+In the early years of FreeCalypso, when we made our first attempt at FC GSM
+firmware that was eventually retired under the name Citrine, we supported
+running that fw on the Mot C155/156 target in addition to the other two C1xx
+subfamilies.  However, that C155 target support in not available in our current
+Magnetite and Selenite firmwares.  We are not doing any work to support that
+target in our current fw because it does not provide anything of value that is
+not better provided by other targets:
+
+* If your goal is to have a practically usable phone, the simpler C139/140 is a
+  better choice than C155/156: C155 uses a ringtone generator chip for which no
+  docs could be found, thus we may not be able to make it ring (in contrast,
+  C139 uses a piezoelectric buzzer driven by the Calypso itself), and C155's
+  LCD controller is much less obvious than the one in the C139 - the latter
+  already works the way we like.
+
+* If instead you would like a platform for playing with non-UI modem firmware
+  (which is all that our previous Citrine fw provided), then the only platform
+  which we officially support and endorse for that purpose is our own FCDEV3B.
+  It is not reasonable at this point to ask us to expend unpaid volunteer time
+  to support a hardware platform that is not made or sold by us when instead
+  you should be supporting our work by buying the hardware which we do make.
+
+If you wish to strike out on your own and try to resurrect C155 target support
+in FC Selenite or Magnetite, your first difficulty will be that you won't be
+able to run our fw entirely out of RAM without flashing like we did when running
+Citrine on this target.  FC Citrine implemented an FFS-in-RAM hack as an
+alternative to using a real FFS in flash, but this hack is not present in
+Magnetite or Selenite, thus unless you go even further out and resurrect that
+hack as well, you will have to flash your firmware.  If you take the route of
+flashing your fw, you will have to decide between one of two possible
+approaches:
+
+Approach 1: you can keep this target's original bootloader that expects the
+main fw image to begin at 0x20000 with a hand-off interface that is new to the
+C155 (different from the more basic C1xx subfamilies), and build your fw to fit
+this C155 boot interface.  This approach was supported in Citrine (although not
+actually used because it was much easier to run via fc-xram w/o flashing) and
+can be easily resurrected in the gcc build of Selenite.  However, it would be a
+lot more difficult to get this approach to work with TI's original TMS470
+environment: doing so would require major surgery on their assembly code and
+linker script magic, which I am not comfortable with because we have no docs or
+sources for those assembler and linker tools.  You will also face the same
+problem if you resurrect our old FFS-in-RAM hack and try to build a fw image
+that runs entirely out of RAM w/o flashing: it is easy to do in the gcc
+environment, but not in TMS470.
+
+Approach 2: you can replace the bootloader with the one we use on the more
+basic C1xx phones (compal-flash-boot-for-fc.bin), in which case you will have
+complications with loadtools (the ARM vs. Thumb entry point difference for
+serially loaded code), but you can work around that issue by running fc-loadtool
+and fc-xram with -h c155 -c plain instead of just -h c155 after you change the
+bootloader, or you can create yet another patched bootloader version that does
+the Thumb entry point for serially loaded code like C155 original but hands off
+to the main fw in flash in the older C1xx fashion.  Either way you will then be
+able to build flashable fw images for this boot-modified C155 in the same manner
+as how we do it for the more basic C1xx targets, and thus have both TMS470 and
+gcc environments.
+
+As you can see from the above, it will be messy and unpleasant no matter which
+way you lick it, and we (FreeCalypso Central) are not going to do this work for
+free, whereas doing it on a commercial consulting basis would cost a lot more
+than the $500 USD retail price of our own FreeCalypso development board
+(FCDEV3B) that avoids all of these problems and is a much nicer platform for
+Calypso sw/fw development.