--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/C1xx-boot-utils	Mon Jun 12 06:00:57 2023 +0000
@@ -0,0 +1,79 @@
+The present fc-am-toolkit package is mostly shell scripts, automating the
+convoluted workflows for running FreeCalypso firmware on alien targets in
+aftermarket configurations, but it also contains some C programs for working
+with flash images read out of C1xx phones, particularly the bootloader part
+which is absolutely critical on these brickable phones.  The following 3
+utilities are provided - all 3 are used by c1xx-analyze-image script, but they
+may also be useful on their own.
+
+c139-analyze-boot
+=================
+
+This program takes a binary file containing either the complete flash dump from
+a lower-submodel C1xx phone (C139/140 or C11x/12x) or the beginning of one (must
+be at least 0x2064 bytes) and checks it for presence of lower-submodel-C1xx
+bootloader code that must be present in the boot sector on these phones.  The
+program prints a single keyword on stdout, indicating its findings, and exits
+successfully.  The following 4 classifications are emitted by this program:
+
+fc
+
+	compal-flash-boot-for-fc.bin bootloader has been identified, the patched
+	bootloader version we put in sector 0 on these Compal phones when we run
+	FC firmware on these phones.
+
+unlocked
+
+	Found one of the lock-free bootloader versions (either C11x or C139),
+	or found a lockable bootloader version, but the lock word at 0x2060 is
+	set to 0xDDDDDDDD, meaning unlocked.
+
+locked
+
+	Found one of the lockable, but otherwise good bootloader versions
+	(either C11x or C139), and the lock word at 0x2060 contains 0 or some
+	other value than the needed magic.  This status indicates that the flash
+	image in its given state is boot-locked (bad), but it can be transformed
+	into a boot-unlocked image with c139-patch-dmagic - see below.
+
+unknown
+
+	None of the known-good bootloader versions have been identified.  The
+	bootloader you got may be one of the later versions that have been
+	locked down more heavily, and these flash images are EXTREMELY UNSAFE.
+	You should NEVER flash any such images back into a phone: our defenses
+	against bricking don't work with such maliciously modified bootloader
+	versions, and if you try to flash one (even if you are only seeking to
+	restore what you originally read out of the flash) and the process gets
+	interrupted in any way (meaning the full, long process), your phone may
+	be bricked beyond all recovery!
+
+	If you are able to somehow break into a phone with one of these ultra-
+	malicious bootloader versions (and you must have been able to break in
+	somehow, if you got a flash image you are analyzing), the generally
+	recommended course of action is to make a one-way transition to a
+	better, non-malicious official Motorola firmware version.
+
+c139-patch-dmagic
+=================
+
+This program needs to be run if c139-analyze-boot returned "locked" on your
+flash image.  This program opens the given binary file in writable mode and
+patches the unlocking magic word 0xDDDDDDDD at offset 0x2060, thereby turning
+the locked flash image into an unlocked one.  If the image you've read out of
+flash is a locked one, as determined by c139-analyze-boot, and you wish to
+reflash that same fw version back into your phone (or into a different phone),
+you MUST unlock the image with c139-patch-dmagic before flashing it with
+fc-loadtool - if you proceed with flashing a locked image, you will have a very
+high chance of bricking your phone (beyond all recovery!), as our regular
+defenses against bricking don't work with locked bootloaders.
+
+c155-analyze-boot
+=================
+
+This program is a very simplified logical equivalent of c139-analyze-image for
+C155/156 subfamily.  Perhaps it is because these phones are less common, but I
+(Mother Mychaela) have not yet encountered any locked or otherwise modified
+versions of C155/156 bootloader beyond the one known classic version.
+c155-analyze-boot currently checks for this one known bootloader version, and
+prints "ok" if the image matches or "unknown" otherwise.