Add IPDBG JtagHost functionality to OpenOCD

IPDBG are utilities to debug IP-cores. It uses JTAG for
transport to/from the FPGA. The different UIs use TCP/IP
as transport. The JtagHost makes the bridge between these
two.

Comparable to the bridge between GDB and the in-circuit-
debugging-unit of a micro controller.

Change-Id: Ib1bc10dcbd4ea426e492bb7b2d85c1ed1b7a8d5a
Signed-off-by: Daniel Anselmi <danselmi@gmx.ch>
Reviewed-on: http://openocd.zylin.com/5938
Tested-by: jenkins
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

doc/openocd.texi

@@ -10585,6 +10585,49 @@ If @emph{xsvfdump} shows a file is using those opcodes, it
 probably will not be usable with other XSVF tools.
 
 
+@section IPDBG: JTAG-Host server
+@cindex IPDBG JTAG-Host server
+@cindex IPDBG
+
+IPDBG is a set of tools to debug IP-Cores. It comprises, among others, a logic analyzer and an arbitrary
+waveform generator. These are synthesize-able hardware descriptions of
+logic circuits in addition to software for control, visualization and further analysis.
+In a session using JTAG for its transport protocol, OpenOCD supports the function
+of a JTAG-Host. The JTAG-Host is needed to connect the circuit over JTAG to the
+control-software. For more details see @url{http://ipdbg.org}.
+
+@deffn {Command} {ipdbg} [@option{-start|-stop}] @option{-tap @var{tapname}} @option{-hub @var{ir_value} [@var{dr_length}]} [@option{-port @var{number}}] [@option{-tool @var{number}}] [@option{-vir [@var{vir_value} [@var{length} [@var{instr_code}]]]}]
+Starts or stops a IPDBG JTAG-Host server. Arguments can be specified in any order.
+
+Command options:
+@itemize @bullet
+@item @option{-start|-stop} starts or stops a IPDBG JTAG-Host server (default: start).
+@item @option{-tap @var{tapname}} targeting the TAP @var{tapname}.
+@item @option{-hub @var{ir_value}} states that the JTAG hub is
+reachable with dr-scans while the JTAG instruction register has the value @var{ir_value}.
+@item @option{-port @var{number}} tcp port number where the JTAG-Host is listening.
+@item @option{-tool @var{number}} number of the tool/feature. These corresponds to the ports "data_(up/down)_(0..6)" at the JtagHub.
+@item @option{-vir [@var{vir_value} [@var{length} [@var{instr_code}]]]} On some devices, the user data-register is only reachable if there is a
+specific value in a second dr. This second dr is called vir (virtual ir). With this parameter given, the IPDBG satisfies this condition prior an
+access to the IPDBG-Hub. The value shifted into the vir is given by the first parameter @var{vir_value} (default: 0x11). The second
+parameter @var{length} is the length of the vir data register (default: 5). With the @var{instr_code} (default: 0x00e) parameter the ir value to
+shift data through vir can be configured.
+@end itemize
+@end deffn
+
+Examples:
+@example
+ipdbg -start -tap xc6s.tap -hub 0x02 -port 4242 -tool 4
+@end example
+Starts a server listening on tcp-port 4242 which connects to tool 4.
+The connection is through the TAP of a Xilinx Spartan 6 on USER1 instruction (tested with a papillion pro board).
+
+@example
+ipdbg -start -tap 10m50.tap -hub 0x00C -vir -port 60000 -tool 1
+@end example
+Starts a server listening on tcp-port 60000 which connects to tool 1 (data_up_1/data_down_1).
+The connection is through the TAP of a Intel MAX10 virtual jtag component (sld_instance_index is 0; sld_ir_width is smaller than 5).
+
 @node Utility Commands
 @chapter Utility Commands
 @cindex Utility Commands

src/helper/command.h

@@ -426,6 +426,48 @@ DECLARE_PARSE_WRAPPER(_target_addr, target_addr_t);
 #define COMMAND_PARSE_ADDRESS(in, out) \
 	COMMAND_PARSE_NUMBER(target_addr, in, out)
 
+/**
+ * @brief parses the command argument at position @a argn into @a out
+ * as a @a type, or prints a command error referring to @a name_str
+ * and passes the error code to the caller. @a argn will be incremented
+ * if no error occurred. Otherwise the calling function will return
+ * the error code produced by the parsing function.
+ *
+ * This function may cause the calling function to return immediately,
+ * so it should be used carefully to avoid leaking resources.  In most
+ * situations, parsing should be completed in full before proceeding
+ * to allocate resources, and this strategy will most prevents leaks.
+ */
+#define COMMAND_PARSE_ADDITIONAL_NUMBER(type, argn, out, name_str) \
+	do { \
+		if (argn+1 >= CMD_ARGC || CMD_ARGV[argn+1][0] == '-') { \
+			command_print(CMD, "no " name_str " given"); \
+			return ERROR_FAIL; \
+		} \
+		++argn; \
+		COMMAND_PARSE_NUMBER(type, CMD_ARGV[argn], out); \
+	} while (0)
+
+/**
+ * @brief parses the command argument at position @a argn into @a out
+ * as a @a type if the argument @a argn does not start with '-'.
+ * and passes the error code to the caller. @a argn will be incremented
+ * if no error occurred. Otherwise the calling function will return
+ * the error code produced by the parsing function.
+ *
+ * This function may cause the calling function to return immediately,
+ * so it should be used carefully to avoid leaking resources.  In most
+ * situations, parsing should be completed in full before proceeding
+ * to allocate resources, and this strategy will most prevents leaks.
+ */
+#define COMMAND_PARSE_OPTIONAL_NUMBER(type, argn, out) \
+	do { \
+		if (argn+1 < CMD_ARGC && CMD_ARGV[argn+1][0] != '-') { \
+			++argn; \
+			COMMAND_PARSE_NUMBER(type, CMD_ARGV[argn], out); \
+		} \
+	} while (0)
+
 /**
  * Parse the string @c as a binary parameter, storing the boolean value
  * in @c out.  The strings @c on and @c off are used to match different

src/jtag/core.c

@@ -45,6 +45,9 @@
 #include "svf/svf.h"
 #include "xsvf/xsvf.h"
 
+/* ipdbg are utilities to debug IP-cores. It uses JTAG for transport. */
+#include "server/ipdbg.h"
+
 /** The number of JTAG queue flushes (for profiling and debugging purposes). */
 static int jtag_flush_queue_count;
 
@@ -1975,7 +1978,12 @@ static int jtag_select(struct command_context *ctx)
 	if (retval != ERROR_OK)
 		return retval;
 
-	return xsvf_register_commands(ctx);
+	retval = xsvf_register_commands(ctx);
+
+	if (retval != ERROR_OK)
+		return retval;
+
+	return ipdbg_register_commands(ctx);
 }
 
 static struct transport jtag_transport = {

src/server/Makefile.am

@@ -10,7 +10,9 @@ noinst_LTLIBRARIES += %D%/libserver.la
 	%D%/tcl_server.c \
 	%D%/tcl_server.h \
 	%D%/rtt_server.c \
-	%D%/rtt_server.h
+	%D%/rtt_server.h \
+	%D%/ipdbg.c \
+	%D%/ipdbg.h
 
 %C%_libserver_la_CFLAGS = $(AM_CFLAGS)
 if IS_MINGW

src/server/ipdbg.h

@@ -0,0 +1,11 @@
+/* SPDX-License-Identifier: GPL-2.0-or-later */
+/* Copyright (C) 2020 by Daniel Anselmi <danselmi@gmx.ch> */
+
+#ifndef OPENOCD_IPDBG_IPDBG_H
+#define OPENOCD_IPDBG_IPDBG_H
+
+#include <helper/command.h>
+
+int ipdbg_register_commands(struct command_context *cmd_ctx);
+
+#endif /* OPENOCD_IPDBG_IPDBG_H */