--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Calypso-chip-versions	Sat Dec 29 06:59:27 2018 +0000
@@ -0,0 +1,68 @@
+There have been many different versions of the Calypso silicon made over the
+years, including hardware differences, at least 3 ARM boot ROM versions and at
+least 3 DSP ROM versions.  New target utility calversion (to be run via fc-iram)
+helps identify unknown Calypso chip versions: it reports the ARM boot ROM
+version, the DSP ROM version and the values read from the few documented ID
+registers.
+
+In order to be able to use our calversion utility to identify an unknown Calypso
+variant, the Calypso device under examination needs to satisfy the following
+two requirements:
+
+* The boot ROM needs to be enabled by nIBOOT pin strapping on the board, in
+order to be able to get in with fc-iram;
+
+* The Calypso chip version to be identified needs to be Calypso C05 rev B or
+later, containing ARM boot ROM version 0200 or 0300.  This limitation exists
+because our target-utils framework on which calversion is based depends on being
+booted by a known Calypso boot ROM version in order to figure out which UART it
+should use for communication.  If anyone encounters a device with a Calypso C05
+rev A chip in it, you will need to somehow read out its boot ROM, send us that
+boot ROM dump, and we will extend our UART detection logic in target-utils to
+support that ancient boot ROM version which is currently unknown to us.
+
+If you have a Calypso boot ROM version which is not currently supported by our
+target-utils, how can you read it out?  The simplest way (assuming that nIBOOT
+is strapped low on the board to enable the boot ROM) would be to edit
+target-utils/libcommon/uartsel.c in your local copy, hard-code whichever UART
+you are using in the uart_select_init() function, removing the boot ROM
+version-dependent autodetection code, rebuild calversion and loadagent with
+this hack, and use the modified loadagent with fc-loadtool to dump the ROM.
+Alternatively, if the boot ROM is disabled with nIBOOT strapped high, you may
+be able to read it out via JTAG, or perhaps via fc-memdump if the device
+already runs some compatible firmware.
+
+Back to our calversion utility, if you have a Calypso device with a not-quite-
+known chip version in it and you are able to get in with fc-loadtool, you can
+run calversion on it as follows:
+
+fc-iram /dev/ttyXXX /opt/freecalypso/target-bin/calversion.srec
+
+You should get output that looks like this:
+
+Calypso version ID program running
+Loaded via boot ROM v0300, UART 0 (MODEM) at baud rate #0
+CLKTCXO input autodetected to be 26 MHz
+Device ID code: 0xB496
+Device version code: 0x0000
+ARM ID code: 0xFFF3
+cDSP ID code: 0x0128
+Releasing DSP core from reset
+Waiting for DSP bootloader READY status
+Loading NDB parameters
+Loading PARAM area
+Booting DSP main code
+DSP reports version 0x3606 0x0000
+
+You should be able to see which of the two supported boot ROM versions (0200 or
+0300) your Calypso chip has, which UART was used to load the code, whether your
+board uses a 13 MHz or a 26 MHz clock (this is a board-level property, not a
+property of the Calypso chip), what values are reported in the device ID
+registers, and the last bit which takes the most work to obtain - the DSP ROM
+version.
+
+The boot ROM version and the CLKTCXO input frequency are also reported when you
+run fc-loadtool, and the device ID registers can be trivially read with the r16
+command once you are in loadtool, but getting the DSP ROM version requires
+putting the DSP through its messy boot process, which is why a special program
+had to be written for the task.