--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Calypso-JTAG-notes	Mon Jun 24 20:01:53 2019 +0000
@@ -0,0 +1,349 @@
+This document describes the quirks of Calypso JTAG in an abstract, tool-
+independent sense, and also covers the little bit of experience we've had with
+TI's original official tools, but does not delve into OpenOCD specifics.
+For OpenOCD-on-Calypso custom config and instructions, please refer to the
+freecalyps-hwlab repository - but the present document should still be read
+first.
+
+Unconventional reset structure
+==============================
+
+The first major way in which the JTAG interface on Calypso development boards
+(or more generally, what is available in the Calypso+Iota chipset) differs from
+"canonical" JTAG is that this chipset does NOT have reset signals that are
+anything like classic TRST or SRST.  Instead there is only one bundled-with-JTAG
+reset signal (we call it XDS_RESET) which is turned into Iota nTESTRESET through
+a transistor circuit - please refer to the Calypso-test-reset article.  Aside
+from its effects on the VRPC state machine described in that article, this test
+reset can be thought of as a simultaneous combination of an equivalent of TRST
+(all JTAG logic is hard-reset), an equivalent of SRST (the Calypso is fully
+reset and proceeds with a cold boot) and more (all hardware is reset at a very
+deep level), but comparisons to classic TRST and SRST aren't really appropriate
+as the latter signals simply don't exist in our chipset.
+
+However, despite its highly unconventional nature, this XDS_RESET signal
+provided along with JTAG on TI's development boards performs a very important
+function: this combination of JTAG and test reset allows a "reset and hold
+still" maneuvre where all hardware is put into its pristine state with a very
+deep reset, but the ARM7 CPU is halted before it gets a chance to execute any
+instructions from the reset vector.  This ability is not particularly important
+on current Calypso hardware with a working and enabled boot ROM, but it was
+vital on earlier platforms without this boot ROM: if the flash is blank or
+contains a bad code image, or if RAM is mapped onto the boot chip select
+instead of flash, allowing the ARM7 core to execute garbage out of reset is
+bad, whereas having a "reset and hold still" ability allows guaranteed reliable
+recovery and bootstrapping from a blank or bricked state.  As explained later
+in this article, this "reset and hold still" maneuvre is executed by first
+giving the target a test reset pulse (which unstoppably blows away all prior hw
+state), then immediately (the timing is critical) performing certain
+manipulations via the JTAG scan chain - thus the bundling of the XDS_RESET
+signal with JTAG is important.
+
+EMU0 and EMU1 signals
+=====================
+
+In addition to the 4 standard JTAG signals TCK, TDI, TDO and TMS, the Calypso
+provides two TI-proprietary signals called EMU0 and EMU1.  (The test reset goes
+to the Iota ABB, not to the Calypso.)  These EMU0 and EMU1 signals are brought
+out to the 14-pin JTAG connector on TI's D-Sample and E-Sample boards, and also
+on our FCDEV3B.
+
+The function of these two signals is completely unknown: all we know is that
+they are listed as "bidirectional in/out" in the cal000.pdf document, and that
+same-named signals also exist on TI's general-purpose DSP chips, both C54x and
+the newer families, where they are also very poorly documented.  We don't know
+what these EMU0/1 signals do on the Calypso, and it is a particular unknown
+whether they are specific to the DSP part or if the ARM7 part can also make use
+of them somehow.
+
+I (Mother Mychaela) previously thought that these signals might facilitate a
+way to halt the ARM7 core without going through the scan chain, or a different
+way to halt directly out of reset than the one we ultimately found, but a
+recent experiment has shown that pulling either or both of these signals low
+(they are pulled up on target boards) has absolutely no visible effect on ARM7
+code execution, whether they are pulled low coming out of test reset or while
+running.  Thus until we recover more understanding of what is going on inside
+the chip, we are going to ignore these two signals and leave them unconnected.
+
+Iota not included in the JTAG scan chain
+========================================
+
+In addition to the Calypso chip itself (the DBB), the Iota ABB chip also has
+JTAG pins and could potentially be included in the scan chain.  However, this
+wiring arrangement is not typically used: both on TI's D-Sample board and on
+our own FCDEV3B (based on Leonardo schematics) the JTAG interface is wired only
+to the Calypso and not to Iota.  The same arrangement has also been found in
+all historical commercial phones and modems that provide a JTAG interface.
+
+We don't have any plans to change this arrangement in any of our future designs:
+in the absence of 100% complete understanding of the internals of both chips,
+there is no telling what unexpected gotcha may occur if the Iota chip is
+included in the same scan chain as the Calypso, hence we are not doing that.
+
+ARM7 and C54x DSP cores
+=======================
+
+The regular JTAG scan chain inside the Calypso goes through two TAPs
+corresponding to the two processor cores.  The ARM7 TAP with a 4-bit IR is
+closer to TDI, and the C54x DSP TAP with an 8-bit IR is closer to TDO.  The
+debug interface to the ARM7 core through its respective TAP is consistent with
+public ARM7TDMI documentation from ARM except for one important quirk described
+below, but we know absolutely nothing about the DSP TAP and its debug protocol
+other than how to put it into BYPASS so we can operate on the ARM.
+
+It appears from passing references in some TI documents that they did intend to
+have an ability to debug the Calypso DSP via JTAG "emulation", and TI's CCS
+software working through TI's XDS510 or XDS560 hardware (the same setup that
+successfully connects to the ARM7 part of the Calypso) supports C54x targets.
+However, we have no idea how any potential JTAG access to the DSP would interact
+with its reset control coming from the ARM or with its power saving modes, and
+it is very likely that there are some security mechanisms restricting debug
+access to the DSP (perhaps needing some secret key to unlock it), thus being
+able to debug the DSP via JTAG is not something we can realistically hope for
+unless we either buy out the complete chip design from TI or physically
+reverse-engineer the chip transistor by transistor, both options being equally
+cost-prohibitive.  At our current level of budgetary means, our ability to use
+the JTAG interface on the Calypso is limited to the ARM7 part, not the DSP.
+
+Non-standard extension to the ARM7TDMI TAP
+==========================================
+
+We know that TI made at least one non-standard extension to the ARM7TDMI TAP in
+the Calypso because it implements at least one additional opcode that does not
+appear in any public documentation from ARM.  When connecting to this ARM7
+target, TI's CCS software working through XDS510 or XDS560 hardware apparently
+scans a 0xB opcode (4'b1011) through the IR, and then apparently scans 2'b10
+through the 2-bit DR selected by this opcode.  (I said "apparently" because so
+far the only people who have actually sniffed the JTAG communications produced
+by the XDS+CCS combo were OsmocomBB people, not anyone from the FreeCalypso
+team, hence we don't have any authentic knowledge currently.)  Experiments with
+OpenOCD show that the just-described sequence of IR and DR scans with an
+unknown instruction and an unknown data register is necessary in order to allow
+halting the ARM7 core: if we try to halt it in the standard ARM7TDMI way (either
+via DBGRQ or via a catch-all breakpoint unit setup) without doing the magic
+sequence first, no halt is effected.
+
+Fortunately though, after we issue the non-understood magic sequence once, all
+subsequent ARM7TDMI halt/resume manipulations done in the standard way appear
+to work just fine, no more quirks.  The only time when the "halt unlock" magic
+sequence needs to be repeated is after a reset, which is expected.
+
+Interaction with the watchdog timer
+===================================
+
+The Calypso chip includes a watchdog timer feature; if this watchdog timer is
+enabled and allowed to expire, it effects a fairly deep reset of the chip.  The
+Calypso boot ROM code and most firmware designs do a step early on to disable
+this watchdog, and it is not subsequently re-enabled except to effect a reboot
+when so desired, but as the ARM7 core first comes out of reset and starts
+executing instructions from the reset vector (whether ROM or external memory),
+the watchdog timer is enabled and ticking.  This watchdog timer interacts with
+JTAG as follows:
+
+1) When the ARM7 core is halted via JTAG, the watchdog timer (if enabled) is
+   NOT stopped or paused, but keeps ticking.
+
+2) If a watchdog reset occurs while the ARM7 core is halted, everything goes
+   out of whack, consistent with the note in standard ARM7TDMI documentation
+   which says that a reset must not be applied to the core while it is in debug
+   halt state.
+
+Therefore, if the ARM7 core is to be halted at a time when the watchdog timer
+is enabled and ticking, the halt operation must be quickly followed by two
+system bus write operations (mwh command in OpenOCD) to the WATCHDOG_TIM_MODE
+register, executing the watchdog disable sequence before the timer is allowed
+to expire while halted.
+
+JTAG clock speed
+================
+
+It is often stated that the JTAG clock speed must be no greater than 1/6 of the
+system clock speed when talking to ARM cores, and that JTAG access is blocked
+when the core goes into a power saving mode with the clock stopped.  Neither of
+these constraints applies to our beloved Calypso though: the stated issues occur
+in chip designs which internally synchronize JTAG signals including TCK to their
+system clock, but Calypso and its predecessors don't do that, they use the hard
+macrocell version of the ARM7TDMI core instead, use TCK directly to clock JTAG-
+specific logic and perform "hard" clock switching for debug mode.
+
+According to the available cal000_a.pdf document, the maximum TCK frequency
+supported by the Calypso is 10 MHz, which also appears to be the only TCK
+frequency which TI's older XDS510 "emulator" pods can produce without hardware
+modifications.  This 10 MHz TCK frequency can be used no matter what frequency
+is fed to Calypso's main CLKTCXO clock input or what frequency the ARM7 core is
+configured to run at, and JTAG keeps working even when the main clock is
+completely stopped.
+
+It is possible to halt the Calypso ARM7 core when it is in a sleep mode, even
+in deep sleep: manipulation of internal scan chain 2 to set DBGRQ is a JTAG-only
+operation, contained entirely in the TCK clock domain, thus it works even with
+the main VCXO stopped, and the actual halt occurs on wakeup when the ARM7 core
+regains its regular clock and sees the internal DBGRQ signal asserted.
+
+Halting immediately out of reset
+================================
+
+To me (Mother Mychaela) it always seemed evident that the Calypso and its
+predecessors had to have some way to perform a "reset and hold still" maneuvre,
+as this capability was absolutely essential for deterministic bootstrapping and
+recovery of boards before the Calypso boot ROM subsumed that function.  However,
+the exact manipulations required to achieve this effect have remained elusive
+for a long time until I found the answer in May-June of 2019.  The trick is NOT
+done through EMU0/1 pins like I once thought, and the method used on many other
+chips involving classic TRST and SRST signals is clearly not applicable to the
+Calypso given its very different reset structure.
+
+The answer lies in the clocking architecture of TI GSM chipsets, involving a
+VCXO that is started and stopped and a 32.768 kHz clock which is always running.
+When the Calypso starts its boot process in response to the ON_nOFF signal
+going from low to high (in the XDS-triggered test reset scenario this event
+immediately follows the release of external reset), the main VCXO is off (i.e.,
+it hasn't been started yet) and only the 32.768 kHz clock is running.  At this
+point the ARM7 core receives no clock at all (the 32.768 kHz clock is never fed
+to the ARM7), and the ULPD block (the same block that handles deep sleep) goes
+through the sequence of first enabling the main VCXO, then waiting for it to
+stabilize.  This sequence takes about 8192 cycles of the slow clock (about
+250 ms), and only at the completion of this sequence the ARM7 core gets its
+first clock.  But during that 250 ms time window the JTAG logic is out of its
+reset and functioning, and it can be operated because Calypso JTAG does not
+depend on the main ARM clock which is stopped.
+
+The following sequence of steps successfully achieves the effect of resetting
+the Calypso+Iota chipset and all board-level peripherals that are subservient
+to it, and halting the Calypso directly at the reset vector before the first
+instruction is executed:
+
+1) Give the chipset a test reset pulse via the XDS_RESET line; the exact
+   required duration is not known, but my OpenOCD-based proof of concept gives
+   a 50 ms pulse.
+
+2) Immediately after releasing the reset or after a short delay (my PoC does a
+   10 ms delay), start exercising the JTAG scan chain, which has been fully
+   reset - it will be responsive at this point.
+
+3) Perform the "magic" IR and DR scans to enable halting ability, just like we
+   do when we wish to halt an already-running Calypso.
+
+4) Going through scan chain 2 inside the ARM7TDMI TAP, set the DBGRQ bit.
+   All steps up to this one must happen before Calypso ULPD enables the
+   VCXO-derived clock to the ARM7.
+
+5) Also going through scan chain 2, poll and wait for DBGACK to get set,
+   indicating that the ARM7TDMI core halted - this event will happen when the
+   core gets its first clocks.
+
+6) Once the ARM7TDMI core is halted, perform the two mwh operations to the
+   0xFFFFF804 register (WATCHDOG_TIM_MODE) to disable the watchdog, otherwise
+   it will generate another internal reset and mess up the system state.
+
+We never found any built-in provision in TI's CCS (see below) or any script for
+CCS that does the above, instead I (Mother Mychaela) found it on my own by
+thinking about how it could possibly be done, and proved the idea working
+with an OpenOCD setup presented in the freecalypso-hwlab repository.
+
+Original official TI tools
+==========================
+
+TI's original and official tool for operating on Calypso JTAG was their Code
+Composer Studio (CCS) software, working through TI's XDS510 and XDS560
+"emulator" hardware.  The original hardware solution was the XDS510, and I mean
+the original XDS510 which was an ISA card made by TI themselves, not any of the
+later "XDS510-class" "emulators" made by companies acting as TI's 3rd-party
+partners.  The next successor to this original XDS510 was the original XDS560,
+also made by TI themselves and distinct from the later "XDS560-class" devices
+by TI's 3rd-party partner companies.  The original XDS560 is a PCI card rather
+than ISA, thus a little easier to get working in 2019, and also more readily
+available on ebay.  Both XDS510 and XDS560 consist of a desktop PC card (ISA or
+PCI) and an active pod, and the pod has a non-detachable target connection cable
+coming out of it, terminating in a female connector mating with the TI-style
+14-pin JTAG header.  The pod connector fits perfectly to TI's original D-Sample
+board, but on our FCDEV3B it fails to fit because the JTAG and dual UART headers
+are too close together.  Therefore, anyone who is interested in connecting TI's
+original XDS510 or XDS560 to an FCDEV3B would need to get some male-to-female
+jumper wires or make a custom-crimped interposer cable.
+
+The version of CCS which we found to work with these "emulator" adapters (both
+XDS510 and XDS560) and with Calypso targets is this one:
+
+ftp://ftp.freecalypso.org/pub/GSM/TI_tools/CCS/CCS_3.3.83.20_win32.zip
+
+In order to get this CCS to work with a Calypso target, you will need to create
+a "custom board" configuration in CCS setup - none of the predefined board
+configs shipped with CCS will work.  To create the needed "custom board" config,
+select your "emulator" (XDS510 or XDS560), then add an ARM7 target and a
+TMS320C5400 target in this order, which is the order from TDI to TDO.  With this
+custom config saved, running CCS brings up what they call the Parallel Debug
+Manager, which supposedly supports coordinated debugging of both ARM and DSP
+cores.  However, I (Mother Mychaela) have not tried connecting to the DSP part,
+only ARM7; another FreeCalypso community member who also got a working XDS510
+setup talking to an FCDEV3B did try it, but saw what appears to be garbage.  As
+discussed earlier in this article, we are completely in the blind here, hence
+this direction is not being seriously explored at the present.
+
+In order to play with just the ARM7 core, leaving the DSP alone, select the
+ARM7 target in the Open menu in Parallel Debug Manager - the main CCS debug
+window will then open, and it will be specific to the ARM7 target.  In my own
+testing all further operations were done from the latter window and its menus.
+
+Reset with TI's tools
+---------------------
+
+Both XDS510 and XDS560 "emulators" have only one reset output; on TI's general-
+purpose DSP development boards outside of the GSM Skunkworks division this one
+reset line was TRST, whereas on D-Sample and Leonardo boards (and on our
+FCDEV3B) this signal is repurposed to drive Iota nTESTRESET through a clever
+transistor circuit.  TI's general-purpose (non-GSM) DSP chips and boards have
+internal pull-downs on TRST rather than pull-ups (JTAG logic permanently held
+down in reset when no "emulator" is connected), hence both XDS510 and XDS560
+pods drive this signal with an active push-pull driver - which is why Calypso
+development boards include the special transistor circuit rather than connect
+the XDS_RESET line (as we call it) directly to internal nTESTRESET.
+
+Prior to initialization, a "cold" XDS560 pod has its reset output held low,
+thus the target board will be held down in test reset and will appear completely
+unresponsive.  To initialize the XDS560 and release it from reset, select
+"Emulator Reset" from the Debug menu.  For this operation to succeed, the LDO
+regulators in the Iota ABB need to be turned on, putting out 2.8 V on the V-IO
+rail which is used as the target voltage reference by the XDS560 pod, so you
+will probably need to press either the PWON button or the RESET button on the
+FCDEV3B initially - and if the green LED stays off after that button press, you
+know that the board is being held down in test reset by the XDS560 pod.  Then
+do the "Emulator Reset" operation, at which point the green LED will turn on
+and the board will boot normally.  From this point onward, doing a repeated
+"Emulator Reset" operation causes a low-then-high pulse to be put out on the
+XDS_RESET line, resetting the board and once again causing it to go through a
+fresh boot.
+
+Connecting to the ARM7 core and halting it
+------------------------------------------
+
+Once the XDS560 has been initialized and the target board has been lifted out
+of test reset with the "Emulator Reset" operation, you can execute the
+"Connect target" operation, also in the Debug menu.  This operation produces a
+successful halt (I can only guess that this step is the point at which the
+mysterious 0xB JTAG instruction and the unknown 2-bit register scan are issued,
+unlocking the halting ability on this modified ARM7TDMI core), but the halt
+happens at whichever point the ARM7 core happens to be in its code execution,
+i.e., the generic, non-GSM-specific CCS has no knowledge of the peculiar timing
+sequence that is required to achieve a halt directly out of reset on the
+Calypso.  It is my (Mychaela's) guess that CCS probably has some scripting
+ability for more advanced users, and that TI's GSM Skunkworks division used
+this custom scripting mechanism to do a sequence of {Emulator reset, then
+connect to target and halt, then execute two register writes to disable the
+watchdog} with machine rather human timing between the steps.  Machine rather
+than human timing is required in order to hit the 250 ms window between the
+release of reset and the beginning of ARM core execution, and also to disable
+the watchdog after the halt via two register writes before it goes off.
+
+Using OpenOCD on Calypso targets
+================================
+
+Building on top of the work that was done almost a decade earlier by some people
+in the OsmocomBB camp (they sniffed the magic "halt unlock" sequence from an
+XDS+CCS setup and gained the ability to halt an already-running Calypso with
+OpenOCD, albeit without the reset magic) and adding the more in-depth
+understanding provided by Mother Mychaela, we now have the ability to use
+OpenOCD with a simple FT2232D adapter (instead of TI's XDS+CCS) to connect to
+JTAG on TI/FC development boards, both D-Sample and FCDEV3B, gaining the power
+of Free Software instead of proprietary tools.  For the details, please refer
+to the freecalypso-hwlab repository.