add documentation about reset customization

We added two overridable procedures; document them, and the
two jtag arp_* operations they necessarily expose.

Update the comment about the jtag_init_reset() routine; it's
been obsolete for as long as it's had SRST support.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>

1 files changed, 19 insertions, 10 deletions

diff --git a/src/jtag/core.c b/src/jtag/core.c
index 1c9d13c9..14c28fb7 100644
--- a/src/jtag/core.c
+++ b/src/jtag/core.c
@@ -1360,22 +1360,31 @@ int jtag_init_reset(struct command_context_s *cmd_ctx)
 	if ((retval = jtag_interface_init(cmd_ctx)) != ERROR_OK)
 		return retval;
 
-	LOG_DEBUG("Trying to bring the JTAG controller to life by asserting TRST / TLR");
+	LOG_DEBUG("Initializing with hard TRST+SRST reset");
 
-	/* Reset can happen after a power cycle.
-	 *
-	 * Ideally we would only assert TRST or run TLR before the target reset.
+	/*
+	 * This procedure is used by default when OpenOCD triggers a reset.
+	 * It's now done through an overridable Tcl "init_reset" wrapper.
 	 *
-	 * However w/srst_pulls_trst, trst is asserted together with the target
-	 * reset whether we want it or not.
+	 * This started out as a more powerful "get JTAG working" reset than
+	 * jtag_init_inner(), applying TRST because some chips won't activate
+	 * JTAG without a TRST cycle (presumed to be async, though some of
+	 * those chips synchronize JTAG activation using TCK).
 	 *
-	 * NB! Some targets have JTAG circuitry disabled until a
-	 * trst & srst has been asserted.
+	 * But some chips only activate JTAG as part of an SRST cycle; SRST
+	 * got mixed in.  So it became a hard reset routine, which got used
+	 * in more places, and which coped with JTAG reset being forced as
+	 * part of SRST (srst_pulls_trst).
 	 *
-	 * NB! here we assume nsrst/ntrst delay are sufficient!
+	 * And even more corner cases started to surface:  TRST and/or SRST
+	 * assertion timings matter; some chips need other JTAG operations;
+	 * TRST/SRST sequences can need to be different from these, etc.
 	 *
-	 * NB! order matters!!!! srst *can* disconnect JTAG circuitry
+	 * Systems should override that wrapper to support system-specific
+	 * requirements that this not-fully-generic code doesn't handle.
 	 *
+	 * REVISIT once Tcl code can read the reset_config modes, this won't
+	 * need to be a C routine at all...
 	 */
 	jtag_add_reset(1, 0); /* TAP_RESET, using TMS+TCK or TRST */
 	if (jtag_reset_config & RESET_HAS_SRST)