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.