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.