--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Target-boot-control	Mon Feb 03 01:25:31 2020 +0000
@@ -0,0 +1,104 @@
+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