There is a new feature in loadtools (fc-loadtool & friends) and rvinterf as of
fc-host-tools-r12: target boot control.  In a typical development environment
where FC host tools run on a general-purpose PC or laptop and communicate with
various Calypso targets via general-purpose serial or USB-serial ports, adapters
and cables, there is generally no way for the host computer running FC host
tools to directly command the Calypso target to power on and/or reboot - instead
such control must be performed "out of band" by the operator pressing the PWON
or RESET button on the target device; some targets may even require complex
battery manipulations.  However, there may be more elaborate (less casual)
setups where FC host tools run on a special kind of host system which does have
some means to directly control power and reset to an associated Calypso target:

* The Mother has a plan to produce a special FreeCalypso UART+JTAG Adapter, or
  FC-UJA.  This FC-UJA will be a special FT2232D adapter whose Channel A will
  operate in MPSSE mode, connecting to the Calypso target's JTAG and nTESTRESET
  signals, whereas Channel B will act as a standard UART, i.e., a ttyUSB device.
  This FC-UJA needs to be built as a prerequisite before embarking on the
  ambitious HSMBP (Handset Motherboard Prototype) project, as the special
  adapter will be required for working with the HSMBP in development.  When
  FC-UJA becomes a reality, FC host tools running on a development host with
  this adapter will need to be given the ability to issue nTESTRESET pulses to
  the target through the adapter's MPSSE+GPIO channel; this nTESTRESET pulse
  will cause the Calypso target to deep-reset, power on and boot.

* FC host tools (particularly fc-loadtool) may run on the application processor
  of a smartphone such as Openmoko GTA02.  In such environments the AP will have
  special ad hoc control signals (typically GPIOs) to the modem, at the minimum
  controlling the modem's PWON line.  OM GTA02 added an overriding control of
  overall power to the modem; other designs may reasonably add control of the
  modem's RESET line.

* There may be special commercial applications in which one or more Calypso
  modems are subservient to a control processor that acts similarly to the AP
  of a smartphone, with that control processor not only communicating with its
  slave modems via UARTs, but also controlling their power and reset.

Where does the desire for target boot control in loadtools and rvinterf come
from?  Consider the conventional usage model where no target boot control
exists: you first run fc-loadtool or fc-iram or fc-xram or rvinterf on your
target /dev/ttyXXX, then press the PWON or RESET button on the target.  Now
suppose that the finger-actuated button has been replaced with some magic
command that can be executed on the host system to produce the same effect -
now what?  If the usage model stays the same, then you have to first run your
fc-loadtool or fc-iram or fc-xram or rvinterf command same as before, then as
it sits there waiting for the target to boot, you have to open another terminal
window, get another ssh session into the system or whatever, and run the magic
command that replaces the manual button press.  Very cumbersome, hence the
desire for a better way.

Support for target boot control in FC host tools consists of a new -P option
implemented in all of loadtools programs and in rvinterf, as well as a special
configuration file which needs to be manually created.  The working model is as
follows:

* There exist one or more "magic commands": a magic command is any shell command
  (anything that can be passed to /bin/sh -c) whose execution causes a connected
  Calypso target device to power on and boot.  Naturally these commands will be
  very specific to your custom system; they are NOT part of FC host tools!

* These magic commands may be long, and requiring the user to include each magic
  command in full on fc-loadtool, rvinterf etc invokation lines is undesirable.
  To save typing, we associate a short name (which you choose yourself as you
  see fit) with each magic command, and we have a configuration file (which you
  need to create) that defines the mapping.

* The argument to the new -P option is the short name to be looked up in the
  configuration file.

The configuration file needs to be created in /opt/freecalypso/bootctrl.conf;
let us illustrate it with some examples.

Example 1: FC-UJA
=================

When FC-UJA becomes a reality, there will be a program called fc-testreset that
will locate the attached FC-UJA by its USB ID, connect to FT2232D Channel A and
generate the desired reset pulse on its output.  The configuration in
/opt/freecalypso/bootctrl.conf may look as follows:

uja	fc-testreset

This configuration associates boot control name 'uja' with shell command
fc-testreset.  A developer would then run fc-loadtool like this:

fc-loadtool -h fcfam -Puja /dev/ttyUSB0

if ttyUSB0 is where FC-UJA's UART channel ended up.  fc-loadtool would run
normally, sending beacons to /dev/ttyUSB0 and waiting for a Calypso boot ROM
response, but it would also execute the fc-testreset command listed in the
configuration file, and if everything is connected correctly, the resulting
nTESTRESET pulse will cause the target to boot.

The possibility of a single host talking to multiple Calypso targets is fully
supported: if you have multiple FC-UJA adapters with different USB descriptor
serial numbers programmed in their EEPROMs connected to respective Calypso
targets, you could have a /opt/freecalypso/bootctrl.conf setup like this:

uja1	fc-testreset -d serial1
uja2	fc-testreset -d serial2

and then run fc-loadtool accordingly:

fc-loadtool -h fcfam -Puja1 /dev/ttyUSB3
fc-loadtool -h fcfam -Puja2 /dev/ttyUSB4

Example 2: Openmoko GTA02
=========================

There is a modem-power-ctrl.sh script provided in the openmoko directory of this
FC host tools package; if you are going to run fc-loadtool on the application
processor of your GTA02 smartphone, you should install this script in some
sensible location such as /usr/local/sbin/modem-power-ctrl.  Then fill in your
/opt/freecalypso/bootctrl.conf file as follows:

lm	/usr/local/sbin/modem-power-ctrl boot

The name 'lm' stands for "local modem"; you can then run fc-loadtool as follows:

fc-loadtool -h fic -Plm /dev/ttySAC0

Change from the past
====================

Back in 2013 the predecessor to our current FC host tools package was just
loadtools, and we had a special configuration for building our loadtools to run
on the GTA02 AP.  But it worked backwards relative to our current arrangement:
the current sensible arrangement is that a tool like fc-loadtool run without
any special options simply operates on the specified serial port without any
special magic, and if special magic is desired, it needs to be requested
explicitly with the new -P option; the old loadtools-on-GTA02-AP arrangement
was the opposite: you needed to specify -n to get "regular" operation, otherwise
the tools would automatically operate the modem power control.

Now that we support many more different Calypso hardware targets than we even
knew about in 2013-2014, a cleanup has been long overdue.  The new arrangement
as of fc-host-tools-r12 cleans up the mess in several ways:

* Our FC host tools package has grown so much that making special code
  configurations for special environments like the AP of some particular
  smartphone is no longer scalable; now we just have one standard FC host tools
  package without platform-specific hacks.

* Openmoko platform was certainly very special to us once, but it is not so
  special any more - now we just treat it the same as any other.  Our target
  boot control mechanism has now been generalized from just OM GTA02 to any
  arbitrary platform with similar needs.

* No more reversal of the standard tool paradigm: we have standard operation by
  default, magic on request with an option.