remote_bitbang: add use_remote_sleep option to send delays to remote

If the remote_bitbang host does not execute requests immediately,
delays performed inside OpenOCD can be lost. This option allows
the delays to be sent to the remote host so that they can be
queued and executed in order.

Signed-off-by: Jeremy Herbert <jeremy.006@gmail.com>
Signed-off-by: David Ryskalczyk <david.rysk@gmail.com>
Change-Id: Ie1b09e09ea132dd528139618e4305154819cbc9e
Reviewed-on: https://review.openocd.org/c/openocd/+/7472
Tested-by: jenkins
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

doc/manual/jtag/drivers/remote_bitbang.txt

@@ -37,12 +37,16 @@ swdio_read
 swd_write
 	Set the value of swclk (tck) and swdio (tms).
 
+(optional) sleep
+	Instructs the remote host to sleep/idle for some period of time before
+		executing the next request
+
 An additional function, quit, is added to the remote_bitbang interface to
 indicate there will be no more requests and the connection with the remote
 driver should be closed.
 
-These eight functions are encoded in ASCII by assigning a single character to
-each possible request. The assignments are:
+The eight mandatory functions are encoded in ASCII by assigning a single
+character to each possible request. The assignments are:
 
 	B - Blink on
 	b - Blink off
@@ -70,4 +74,10 @@ each possible request. The assignments are:
 
 The read responses are encoded in ASCII as either digit 0 or 1.
 
+If the use_remote_sleep option is set to 'yes', two additional requests may
+be sent:
+
+	D - Sleep for 1 millisecond
+	d - Sleep for 1 microsecond
+
  */

doc/openocd.texi

@@ -2839,6 +2839,15 @@ Specifies the hostname of the remote process to connect to using TCP, or the
 name of the UNIX socket to use if remote_bitbang port is 0.
 @end deffn
 
+@deffn {Config Command} {remote_bitbang use_remote_sleep} (on|off)
+If this option is enabled, delays will not be executed locally but instead
+forwarded to the remote host. This is useful if the remote host performs its
+own request queuing rather than executing requests immediately.
+
+This is disabled by default. This option must only be enabled if the given
+remote_bitbang host supports receiving the delay information.
+@end deffn
+
 For example, to connect remotely via TCP to the host foobar you might have
 something like:
 
@@ -2848,6 +2857,15 @@ remote_bitbang port 3335
 remote_bitbang host foobar
 @end example
 
+And if you also wished to enable remote sleeping:
+
+@example
+adapter driver remote_bitbang
+remote_bitbang port 3335
+remote_bitbang host foobar
+remote_bitbang use_remote_sleep on
+@end example
+
 To connect to another process running locally via UNIX sockets with socket
 named mysocket:
 

src/jtag/drivers/bitbang.c

@@ -278,6 +278,15 @@ static int bitbang_scan(bool ir_scan, enum scan_type type, uint8_t *buffer,
 	return ERROR_OK;
 }
 
+static void bitbang_sleep(unsigned int microseconds)
+{
+	if (bitbang_interface->sleep) {
+		bitbang_interface->sleep(microseconds);
+	} else {
+		jtag_sleep(microseconds);
+	}
+}
+
 int bitbang_execute_queue(void)
 {
 	struct jtag_command *cmd = jtag_command_queue;	/* currently processed command */
@@ -351,7 +360,7 @@ int bitbang_execute_queue(void)
 				break;
 			case JTAG_SLEEP:
 				LOG_DEBUG_IO("sleep %" PRIu32, cmd->cmd.sleep->us);
-				jtag_sleep(cmd->cmd.sleep->us);
+				bitbang_sleep(cmd->cmd.sleep->us);
 				break;
 			case JTAG_TMS:
 				retval = bitbang_execute_tms(cmd);

src/jtag/drivers/bitbang.h

@@ -54,6 +54,9 @@ struct bitbang_interface {
 
 	/** Set SWCLK and SWDIO to the given value. */
 	int (*swd_write)(int swclk, int swdio);
+
+	/** Sleep for some number of microseconds. **/
+	int (*sleep)(unsigned int microseconds);
 };
 
 extern const struct swd_driver bitbang_swd;

src/jtag/drivers/remote_bitbang.c

@@ -31,6 +31,8 @@ static int remote_bitbang_fd;
 static uint8_t remote_bitbang_send_buf[512];
 static unsigned int remote_bitbang_send_buf_used;
 
+static bool use_remote_sleep;
+
 /* Circular buffer. When start == end, the buffer is empty. */
 static char remote_bitbang_recv_buf[256];
 static unsigned int remote_bitbang_recv_buf_start;
@@ -216,6 +218,32 @@ static int remote_bitbang_reset(int trst, int srst)
 	return remote_bitbang_queue(c, FLUSH_SEND_BUF);
 }
 
+static int remote_bitbang_sleep(unsigned int microseconds)
+{
+	if (!use_remote_sleep) {
+		jtag_sleep(microseconds);
+		return ERROR_OK;
+	}
+
+	int tmp;
+	unsigned int ms = microseconds / 1000;
+	unsigned int us = microseconds % 1000;
+
+	for (unsigned int i = 0; i < ms; i++) {
+		tmp = remote_bitbang_queue('D', NO_FLUSH);
+		if (tmp != ERROR_OK)
+			return tmp;
+	}
+
+	for (unsigned int i = 0; i < us; i++) {
+		tmp = remote_bitbang_queue('d', NO_FLUSH);
+		if (tmp != ERROR_OK)
+			return tmp;
+	}
+
+	return remote_bitbang_flush();
+}
+
 static int remote_bitbang_blink(int on)
 {
 	char c = on ? 'B' : 'b';
@@ -252,6 +280,7 @@ static struct bitbang_interface remote_bitbang_bitbang = {
 	.swdio_drive = &remote_bitbang_swdio_drive,
 	.swd_write = &remote_bitbang_swd_write,
 	.blink = &remote_bitbang_blink,
+	.sleep = &remote_bitbang_sleep,
 };
 
 static int remote_bitbang_init_tcp(void)
@@ -377,6 +406,16 @@ COMMAND_HANDLER(remote_bitbang_handle_remote_bitbang_host_command)
 
 static const char * const remote_bitbang_transports[] = { "jtag", "swd", NULL };
 
+COMMAND_HANDLER(remote_bitbang_handle_remote_bitbang_use_remote_sleep_command)
+{
+	if (CMD_ARGC != 1)
+		return ERROR_COMMAND_SYNTAX_ERROR;
+
+	COMMAND_PARSE_ON_OFF(CMD_ARGV[0], use_remote_sleep);
+
+	return ERROR_OK;
+}
+
 static const struct command_registration remote_bitbang_subcommand_handlers[] = {
 	{
 		.name = "port",
@@ -394,7 +433,15 @@ static const struct command_registration remote_bitbang_subcommand_handlers[] =
 			"  if port is 0 or unset, this is the name of the unix socket to use.",
 		.usage = "host_name",
 	},
-	COMMAND_REGISTRATION_DONE,
+	{
+		.name = "use_remote_sleep",
+		.handler = remote_bitbang_handle_remote_bitbang_use_remote_sleep_command,
+		.mode = COMMAND_CONFIG,
+		.help = "Rather than executing sleep locally, include delays in the "
+			"instruction stream for the remote host.",
+		.usage = "(on|off)",
+	},
+	COMMAND_REGISTRATION_DONE
 };
 
 static const struct command_registration remote_bitbang_command_handlers[] = {