--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Loadtool-targets	Sat Feb 01 22:17:04 2020 +0000
@@ -0,0 +1,146 @@
+Explanation of -h targets for fc-loadtool and friends
+=====================================================
+
+It is possible to run fc-loadtool without giving it any -h option at all - if
+run in this manner, the tool will still gain access to the target Calypso device
+via its boot ROM and allow some peeking and poking to be done, but it will run
+with some major limitations:
+
+* No PLL multiplier will be set up, thus the Calypso ARM7 core will run at
+  13 MHz rather than the preferred faster frequency of 39 MHz for Calypso C05
+  or 52 MHz for Calypso C035.
+
+* In the absence of a hardware parameter file specifying flash configuration,
+  all high-level flash operations (all commands beginning with flash) will be
+  disabled.  One can still dump the flash manually using the low-level dump2bin
+  command (as opposed to flash dump2bin), but no other flash manipulations are
+  possible.
+
+* With most -h hardware parameter files the default exit mode is set to
+  exit iota-off, but without a hardware parameter file it will be exit bare
+  by default.
+
+fc-xram is not useful at all without -h: one cannot load anything into XRAM
+until Calypso MEMIF is set up properly for XRAM access, and this setup is done
+by the init scripts referenced from hardware parameter files.
+
+Available -h targets
+====================
+
+-h compal and -h c155
+
+	-h compal needs to be used for all of "lower" Compal subfamilies
+	(everything other than Mot C155/156); -h c155 is self-explanatory.
+	Very special loadtools configuration is needed for Compal targets,
+	telling our tools to use a very different way of gaining entry through
+	Compal's bootloader and configuring the special flash erase-program-boot
+	hack.
+
+All following configurations are for more sane, meaning non-Compal targets:
+
+-h c05 and -h c035
+
+	These are the most generic configurations we have, indicating only the
+	use of Calypso C05 or C035, respectively, but no other knowledge about
+	target hardware.  These minimal configs are not usable for flash
+	manipulation or for fc-xram, but they may be useful for fc-iram or
+	low-level (non-flash) fc-loadtool operations.
+
+-h c05i and -h c035i
+
+	These two configurations are the next step up in target-specific
+	knowledge from the more basic c05 and c035: the present c05i and c035i
+	configs additionally indicate the use of a Iota ABB, telling our tools
+	to perform a Iota poweroff when we are done.  They are still not usable
+	for flash manipulation or for fc-xram, but they are ideal for the
+	simpler and more specialized fc-buzplay and fc-dspromdump tools.
+
+-h gen4 and -h gen8
+
+	These two configs are our most generic fc-loadtool targets: they are
+	supersets of c035i (Calypso C035 and Iota ABB required), supporting
+	4 MiB or 8 MiB flash on Calypso nCS0, respectively.  More precisely,
+	our gen4 config supports *up to* 4 MiB of flash, whereas gen8 supports
+	up to 8 MiB.  In the vast majority of cases it is safe and thus easier
+	to use gen8; the more conservative gen4 config is only needed when you
+	DON'T want Calypso multifunction pin CS4/ADD22 to be switched from CS4
+	to ADD22, either because you know for certain that the flash chip is
+	4 MiB or less or because you found a super-exotic board on which this
+	pin is actually used as CS4 - we have never seen one of the latter.
+
+	These gen4 and gen8 configs set up Calypso MEMIF registers for nCS0 and
+	nCS1; the latter is assumed to be connected to XRAM and is set up for
+	fc-xram.  MEMIF configuration registers are set up with WS=4 - please
+	refer to the MEMIF-wait-states article in the freecalypso-docs
+	repository.
+
+-h dsample
+
+	The dsample target is special in two ways:
+
+	* The PLL multiplier is set to 3 rather than 4, resulting in 39 MHz
+	  ARM7 core clock instead of 52 MHz - this slowdown is needed because
+	  early D-Sample boards have Calypso C05 chips on them.
+
+	* Calypso MEMIF setup is done for nCS0 (flash), nCS1 (main XRAM) and
+	  nCS2 (extra XRAM), making all of D-Sample XRAM available to fc-xram.
+
+	For flash manipulation purposes this dsample target is no different
+	from gen8.
+
+-h fcfam
+
+	The only special features of this configuration are:
+
+	* Calypso MEMIF setup is done for nCS0, nCS1 and nCS2 like on D-Sample;
+
+	* Flash support is configured to look for the second 8 MiB flash bank
+	  on Calypso nCS2.
+
+	This configuration is required for flash manipulation on boards like
+	our current FCDEV3B that have S71PL129N or S71PL129J flash chips with
+	the second flash chip select wired to Calypso nCS2.  This config can be
+	considered a special superset of gen8: every target that works with
+	-h gen8 will also work with -h fcfam, but not the other way around.
+
+-h fic
+
+	FIC's board wiring that has made its way into Openmoko GTA01 and GTA02
+	PCBs and was also undoubtedly used on FIC's earlier pre-Openmoko phones
+	or modems allows for up to 16 MiB of flash (4 MiB, 8 MiB or 16 MiB
+	flash chips can be populated on the same PCB footprint) with the second
+	flash chip select wired to Calypso nCS4.
+
+	This -h fic config supports all FIC Calypso devices with 4 MiB, 8 MiB
+	or 16 MiB flash, and like -h fcfam it can be considered a special
+	superset of gen4 and gen8, special for FIC's board wiring where the
+	potential 2nd flash chip select goes to nCS4.
+
+-h gta02
+
+	This narrowly specialized config is deprecated and will be removed in a
+	future release of FC host tools; please use the new generalized -h fic
+	config instead.
+
+-h leonardo
+
+	This config is a Calypso C05 counterpart to -h fcfam, i.e., -h leonardo
+	differs from -h fcfam only in that the Calypso boot ROM is told to
+	program the PLL with a lower multiplier, running the PLL at 78 MHz
+	instead of 104 MHz, with the ARM7 core getting 39 MHz instead of 52 MHz.
+	This slowdown is needed because early Leonardo boards had Calypso C05
+	chips on them.
+
+-h pirelli
+
+	The Pirelli DP-L10 phone has had its own dedicated -h pirelli target
+	config since the beginning of FreeCalypso, and this special config is
+	still needed because these phones have 16 MiB flash chips (either
+	S71PL129J or S71PL129N) with the second flash chip select wired to
+	Calypso nCS3, a wiring arrangement original to this Pirelli DP-L10.
+
+-h w220
+
+	Motorola W220 (made by Chi-Mei, *not* a Compal target!) gets its own
+	special loadtools config because of its XRAM wiring: the XRAM bank sits
+	on Calypso nCS3 instead of the usual nCS1.

--- a/doc/Loadtools-usage	Sat Feb 01 20:30:20 2020 +0000
+++ b/doc/Loadtools-usage	Sat Feb 01 22:17:04 2020 +0000
@@ -85,13 +85,16 @@
    Mot C139/140		-h compal -c 1004
    Mot C155/156		-h c155
    Mot W220		-h w220
-   Openmoko GTA02	-h gta02
+   Openmoko GTA01/02	-h fic
    Pirelli DP-L10	-h pirelli
    Sony Ericsson J100	-h compal -c 1004
    TI D-Sample		-h dsample
    TI Leonardo		-h leonardo
    Tango modem		-h gen8
 
+   Please refer to the Loadtool-targets article for more information about -h
+   targets.
+
 3. Cause the target device to execute its boot path.  TI/Openmoko/FreeCalypso
    and other sensible targets have the Calypso boot ROM enabled, and will
    interrupt and divert their normal boot path when they "hear" the beacons
@@ -203,7 +206,7 @@
 	parameter file.
 
 	The hardware configurations known to the present release of FreeCalypso
-	loadtools are listed in the "Basic usage" section above.
+	loadtools are listed in the Loadtool-targets article.
 
 -H /path/to/hwparam-file