--- a/doc/Target-utils	Sun Jun 16 05:53:04 2019 +0000
+++ b/doc/Target-utils	Sun Jun 16 18:42:44 2019 +0000
@@ -239,3 +239,40 @@
 flash-boot-test
 ===============
 
+In addition to the repertoire of run-from-IRAM (loadable via fc-iram) programs
+that form the main course of target-utils, we have a flashable program called
+flash-boot-test - it will be called FBT for short in this article.  FBT is a
+test case for the "main application" in flash, and it can be flashed in the
+place of a regular firmware image for certain very low-level tests.  Because it
+runs via the flash boot path and does not get loaded serially, FBT is quite
+hardware-specific by necessity: it assumes a platform with 26 MHz Calypso clock
+input and always uses the IrDA UART for communication (hard-coded).  FBT was
+written with FCDEV3B and Openmoko GTA02 boards in mind; it won't work on a
+D-Sample board because of the 13 MHz vs. 26 MHz clock difference.
+
+FBT is built in two versions: fbt-mode0.bin and fbt-mode1.bin, differing in the
+magic words at location 0x2000 which tell the Calypso boot ROM how the main
+application in flash should be booted - please refer to the Flash-boot-modes
+article in the freecalypso-docs repository.  Only the magic words differ between
+fbt-mode0.bin and fbt-mode1.bin versions; the main body of the code is exactly
+the same.  Once it receives control from the boot ROM in whichever mode it was
+booted in, FBT's own code in main.c does the absolute minimum initialization to
+allow serial communication (sets the VCLKOUT_DIV2 bit in the FFFF:FD02 register
+and initializes the IrDA UART) and falls into the same interactive mode of
+operation (listening for text-based commands) as our various run-from-IRAM
+programs, allowing the operator to explore system state as closely out of boot
+as possible.
+
+When a main application in flash is booted in mode 1 (with the boot ROM moved
+out of the way), the Calypso watchdog timer is running, and our FBT program
+does not a perform a watchdog disable step on its own.  Therefore, if you flash
+fbt-mode1.bin and boot it, you will see it keep endlessly rebooting about every
+9 s.  To stop this endless reboot cycle, issue a wd (watchdog disable) command:
+it is short enough to be easily typed in the available 9 s window.  The same
+issue does not occur in flash boot mode 0, as the Calypso boot ROM does disable
+the watchdog and leaves it disabled when booting mode 0 flash images or serially
+downloaded code.
+
+FBT also has a few other commands that have been added to facilitate further
+experimentation with the watchdog timer feature of the Calypso chip - please
+refer to the source code.