--- a/loadtools/scripts/compal.init	Wed May 22 22:30:28 2019 +0000
+++ b/loadtools/scripts/compal.init	Fri May 24 06:15:02 2019 +0000
@@ -1,16 +1,31 @@
-# Set WS=3 for both nCS0 and nCS1.  This configuration is used by OsmocomBB
-# for all 3 Compal models (E86/88/99), and is also seen in the IDA disassembly
-# listing of c115-1.0.46.E firmware contributed by Christophe Devine.
+# Set WS=3 for both nCS0 and nCS1.  This configuration is used by all official
+# C11x, C139/140 and SE J100 firmwares that have been examined, i.e., by the
+# official firmwares for all Compal models to which this init script applies.
 
 w16 fffffb00 00A3
 w16 fffffb02 00A3
 
-# We need to set the FFFF:FB10 register to map the flash (not the boot ROM)
-# to address 0.  We need this mapping in order to be able to dump and program
-# the entire flash, as for some reason the alternate nCS0 mapping at 0x03000000
-# does not work on Compal phones.  (That alternate mapping works fine on
-# Openmoko and Pirelli phones, though.  Perhaps the different Calypso chip
-# version is the culprit, or perhaps this alternate mapping works only if the
-# physical nIBOOT pin is low.)
+# On most targets we use the alternate nCS0 mapping at 0x03000000 to access
+# the full flash bank even though the boot ROM is mapped at 0, overlapping
+# the first 8 KiB of flash.  However, the Calypso chip (all versions we work
+# with) has a little design bug in this part of the silicon: the alternate
+# nCS0 mapping at 0x03000000 works only when the debug visibility bit in the
+# API-RHEA control register (bit 6 in the FFFF:FB0E register) is set, and
+# does not work otherwise.  This bit is initially set as the Calypso comes
+# out of reset, and on most platforms we gain loadtool access via the boot ROM,
+# hence the problem does not occur - but on these Compal targets we gain
+# loadtool access either through Compal's bootloader or via tfc139, and in
+# both cases Compal's fw (either the full fw or the bootloader part) has
+# already set the register in question to the runtime operational value of
+# 0x2A (unchanged from TI's TCS211 reference fw), with the debug visibility
+# bit cleared, hence the 0x03000000 flash mapping no longer works.
+#
+# We could write into the FFFF:FB0E register here, restore the Calypso power-up
+# state and use the 0x03000000 mapping like on other platforms, but the problem
+# of the mapping not working as expected was first encountered in 2014 when we
+# started working on Compal targets, whereas the root cause described above was
+# only discovered in 2019.  For now we are keeping the original workaround from
+# 2014: we set the FFFF:FB10 register to map the flash (not the boot ROM)
+# to address 0, and use that "main" mapping instead of the alternate one.
 
 w16 fffffb10 0300