--- a/doc/Target-boot-control	Wed Sep 16 06:10:39 2020 +0000
+++ b/doc/Target-boot-control	Wed Sep 16 06:49:31 2020 +0000
@@ -1,26 +1,34 @@
 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:
+fc-host-tools-r12, actually functional as of fc-host-tools-r14: 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.
+* Our new FreeCalypso DUART28 adapter available as of 2020-09 has an optional
+  provision (requires additional wire connections and a custom patch to Linux
+  kernel ftdi_sio driver) for controlling Calypso target board PWON and RESET
+  with otherwise unused secondary channel RTS and DTR outputs - see the new
+  DUART28-boot-control article for the details.
+
+* The Mother has a plan to produce another custom FT2232D-based adapter called
+  FC-UJA, standing for FreeCalypso UART+JTAG Adapter.  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
@@ -49,13 +57,20 @@
 
 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:
+configuration file which needs to be manually created if external boot control
+commands are to be used.  There are two target boot control models, built-in
+and external:
 
-* 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!
+* Built-in target boot control integrated into FC host tools themselves is
+  currently available only for the DTR/RTS pulsing method implemented on our
+  DUART28 adapter: -Pdtr means pulse DTR and -Prts means pulse RTS.  Please
+  refer to the DUART28-boot-control article for the details.
+
+* In the other case of external boot control commands, 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.
@@ -64,7 +79,8 @@
   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.
+  configuration file.  (Built-in boot control names 'dtr' and 'rts' are reserved
+  and cannot be used for external boot control commands.)
 
 The configuration file needs to be created in /opt/freecalypso/bootctrl.conf;
 let us illustrate it with some examples.