--- a/doc/Target-utils	Fri Jun 14 08:30:54 2019 +0000
+++ b/doc/Target-utils	Sun Jun 16 05:53:04 2019 +0000
@@ -130,3 +130,112 @@
 -h pirelli, resulting in the correct 52 MHz clock configuration; in all other
 cases running at a frequency below 52 MHz or running out of flash (the
 flash-boot-test special case) produces longer-than-needed delays.
+
+Common interactive commands
+===========================
+
+The exact set of implemented commands is different for each target-utils
+program, including commands specific to each program's unique function, but the
+following basic commands are included in most programs:
+
+abbinit			Initialize ABB communication
+abbpage2		Unlock access to ABB register page 2
+abbr pg reg		Read ABB register <reg> on page <pg>
+abbw pg reg val		Write <val> into register <reg> on page <pg>
+dump hex-start hex-len	Display a human-oriented memory dump in hex and ASCII
+jump addr		Jump to given address with BX
+poweroff		Execute Iota ABB soft poweroff (DEVOFF)
+r8 addr			Read an 8-bit register or memory location
+r16 addr		Read a 16-bit register or memory location
+r32 addr		Read a 32-bit register or memory location
+w8 addr data		Write an 8-bit register or memory location
+w16 addr data		Write a 16-bit register or memory location
+w32 addr data		Write a 32-bit register or memory location
+
+For further details, please refer to the source code - if you are playing with
+such low-level components, you need to put on the hat of a developer rather
+than a mere user.
+
+ABB support in target-utils
+===========================
+
+Our target-utils suite includes code for initializing and executing SPI
+communication with the Iota ABB device (TWL3014 or TWL3025), Calypso's analog
+and power management companion chip.  Only Iota ABB type is supported, not
+Omega/Nausica or Syren.  The primary reason for having this infrastructure is
+to be able to perform a soft poweroff operation, i.e., to return the Calypso
+phone or modem to its switched-off state after flashing or various standalone
+debug operations, but once implemented, this same ABB SPI communication
+infrastructure is also used in model-specific hardware exploration utilities
+for functions like keypad backlight and vibrator control which are implemented
+via the ABB on some models, and it is used in simtest to control the part of
+the SIM interface that resides in the Iota ABB.
+
+Aside from specialized programs like c139explore that are specific to target
+devices known to use the Iota ABB, most target-utils programs do not execute
+any ABB or SPI communication code (not even initialization) until they receive
+one of the ABB commands: abbinit, abbr, abbw or poweroff.  This way if someone
+comes across a Calypso device that has a different ABB type or needs to debug a
+board with broken ABB communication, one can explore other functions without
+touching ABB commands.
+
+The abb_init() function invoked by the abbinit command may be invoked multiple
+times: it maintains an internal flag remembering if the initialization steps
+have already been done or not, and repeated invokations do nothing.  User-
+friendly abbr, abbw and poweroff commands invoke abb_init() internally, but the
+special abbpage2 command does not - if you are interested in exploring the
+undocumented register page 2, you need to execute abbinit manually first, then
+abbpage2, then explore with abbr and abbw.
+
+poweroff operation details: VRPCAUX and VRPCDEV
+===============================================
+
+The abb_power_off() function invoked by the poweroff command performs the
+following sequence of steps:
+
+* Calls abb_init() to establish ABB communication in the case that it hasn't
+  already been done;
+
+* Executes the magic writes to TAPCTRL and TAPREG registers that unlock access
+  to register page 2 - this step is factored out into the abb_unlock_page2()
+  function which is also accessible as the abbpage2 command;
+
+* Writes 0x007 into the undocumented VRPCAUX register to clear the erratic
+  state that will be there if we got booted via nTESTRESET rather than PWON;
+
+* Flushes all UART output, i.e., waits for it to finish going out on the wire;
+
+* Writes 0x001 into the VRPCDEV register, which is the actual DEVOFF command.
+
+The step of writing into VRPCAUX and its prerequisite page 2 unlock steps are a
+recent addition as of fc-host-tools-r11; these steps have been added to fix the
+erratic behaviour that was occurring on TI/FC development boards (D-Sample and
+FCDEV3B) when fc-loadtool (or fc-iram with some specialized target-utils
+program) was entered via the RESET button rather than PWON, followed by the
+soft poweroff operation and another switch-on via PWON.  For more details,
+please refer to the Calypso-test-reset article in the freecalypso-docs
+repository.
+
+If you are interested in doing some experiments of your own with this
+undocumented quirk of the Calypso+Iota chipset and the odd behaviour it can
+cause, you can do the following:
+
+* To see the content of the undocumented VRPCAUX register resulting from
+  different boot modes, execute these commands:
+
+  abbinit
+  abbpage2
+  abbr 2 30
+
+  Our abbr and abbw commands support page 2, but if you don't issue the magic
+  register writes encapsulated in the abbpage2 command, the Iota chip itself
+  disallows access to page 2.
+
+* To perform a DEVOFF operation without cleaning up VRPCAUX first (to see the
+  resulting erratic behaviour with your own eyes), do it manually as follows:
+
+  abbw 0 30 1
+
+flash-boot-test
+===============
+