target/tcl: Add 'read_memory' and 'write_memory'

These functions are meant as replacement for 'mem2array' and
'array2mem'.

The main benefits of these new functions are:

 * They do not use Tcl arrays but lists which makes it easier
   to parse (generate) the data. See the Python Tcl RPC code
   in contrib as a negative example.

 * They do not operate on Tcl variables but instead return (accept)
   the Tcl list directly. This makes the C and Tcl code base
   smaller and cleaner.

 * The code is slightly more performant when reading / writing
   large amount of data. Tested with a simple Python Tcl RPC
   benchmark.

Change-Id: Ibd6ece3360c0d002abaadc37f078b10a8bb606f8
Signed-off-by: Marc Schink <dev@zapb.de>
Reviewed-on: https://review.openocd.org/c/openocd/+/6307
Tested-by: jenkins
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

doc/openocd.texi

@@ -5036,6 +5036,45 @@ get_reg @{pc sp@}
 @end example
 @end deffn
 
+@deffn {Command} {$target_name write_memory} address width data ['phys']
+This function provides an efficient way to write to the target memory from a Tcl
+script.
+
+@itemize
+@item @var{address} ... target memory address
+@item @var{width} ... memory access bit size, can be 8, 16, 32 or 64
+@item @var{data} ... Tcl list with the elements to write
+@item ['phys'] ... treat the memory address as physical instead of virtual address
+@end itemize
+
+For example, the following command writes two 32 bit words into the target
+memory at address 0x20000000:
+
+@example
+write_memory 0x20000000 32 @{0xdeadbeef 0x00230500@}
+@end example
+@end deffn
+
+@deffn {Command} {$target_name read_memory} address width count ['phys']
+This function provides an efficient way to read the target memory from a Tcl
+script.
+A Tcl list containing the requested memory elements is returned by this function.
+
+@itemize
+@item @var{address} ... target memory address
+@item @var{width} ... memory access bit size, can be 8, 16, 32 or 64
+@item @var{count} ... number of elements to read
+@item ['phys'] ... treat the memory address as physical instead of virtual address
+@end itemize
+
+For example, the following command reads two 32 bit words from the target
+memory at address 0x20000000:
+
+@example
+read_memory 0x20000000 32 2
+@end example
+@end deffn
+
 @deffn {Command} {$target_name cget} queryparm
 Each configuration parameter accepted by
 @command{$target_name configure}
@@ -8557,6 +8596,45 @@ get_reg @{pc sp@}
 @end example
 @end deffn
 
+@deffn {Command} {write_memory} address width data ['phys']
+This function provides an efficient way to write to the target memory from a Tcl
+script.
+
+@itemize
+@item @var{address} ... target memory address
+@item @var{width} ... memory access bit size, can be 8, 16, 32 or 64
+@item @var{data} ... Tcl list with the elements to write
+@item ['phys'] ... treat the memory address as physical instead of virtual address
+@end itemize
+
+For example, the following command writes two 32 bit words into the target
+memory at address 0x20000000:
+
+@example
+write_memory 0x20000000 32 @{0xdeadbeef 0x00230500@}
+@end example
+@end deffn
+
+@deffn {Command} {read_memory} address width count ['phys']
+This function provides an efficient way to read the target memory from a Tcl
+script.
+A Tcl list containing the requested memory elements is returned by this function.
+
+@itemize
+@item @var{address} ... target memory address
+@item @var{width} ... memory access bit size, can be 8, 16, 32 or 64
+@item @var{count} ... number of elements to read
+@item ['phys'] ... treat the memory address as physical instead of virtual address
+@end itemize
+
+For example, the following command reads two 32 bit words from the target
+memory at address 0x20000000:
+
+@example
+read_memory 0x20000000 32 2
+@end example
+@end deffn
+
 @deffn {Command} {halt} [ms]
 @deffnx {Command} {wait_halt} [ms]
 The @command{halt} command first sends a halt request to the target,

src/target/target.c

@@ -4604,6 +4604,161 @@ static int target_mem2array(Jim_Interp *interp, struct target *target, int argc,
 	return e;
 }
 
+static int target_jim_read_memory(Jim_Interp *interp, int argc,
+		Jim_Obj * const *argv)
+{
+	/*
+	 * argv[1] = memory address
+	 * argv[2] = desired element width in bits
+	 * argv[3] = number of elements to read
+	 * argv[4] = optional "phys"
+	 */
+
+	if (argc < 4 || argc > 5) {
+		Jim_WrongNumArgs(interp, 1, argv, "address width count ['phys']");
+		return JIM_ERR;
+	}
+
+	/* Arg 1: Memory address. */
+	jim_wide wide_addr;
+	int e;
+	e = Jim_GetWide(interp, argv[1], &wide_addr);
+
+	if (e != JIM_OK)
+		return e;
+
+	target_addr_t addr = (target_addr_t)wide_addr;
+
+	/* Arg 2: Bit width of one element. */
+	long l;
+	e = Jim_GetLong(interp, argv[2], &l);
+
+	if (e != JIM_OK)
+		return e;
+
+	const unsigned int width_bits = l;
+
+	/* Arg 3: Number of elements to read. */
+	e = Jim_GetLong(interp, argv[3], &l);
+
+	if (e != JIM_OK)
+		return e;
+
+	size_t count = l;
+
+	/* Arg 4: Optional 'phys'. */
+	bool is_phys = false;
+
+	if (argc > 4) {
+		const char *phys = Jim_GetString(argv[4], NULL);
+
+		if (strcmp(phys, "phys")) {
+			Jim_SetResultFormatted(interp, "invalid argument '%s', must be 'phys'", phys);
+			return JIM_ERR;
+		}
+
+		is_phys = true;
+	}
+
+	switch (width_bits) {
+	case 8:
+	case 16:
+	case 32:
+	case 64:
+		break;
+	default:
+		Jim_SetResultString(interp, "invalid width, must be 8, 16, 32 or 64", -1);
+		return JIM_ERR;
+	}
+
+	const unsigned int width = width_bits / 8;
+
+	if ((addr + (count * width)) < addr) {
+		Jim_SetResultString(interp, "read_memory: addr + count wraps to zero", -1);
+		return JIM_ERR;
+	}
+
+	if (count > 65536) {
+		Jim_SetResultString(interp, "read_memory: too large read request, exeeds 64K elements", -1);
+		return JIM_ERR;
+	}
+
+	struct command_context *cmd_ctx = current_command_context(interp);
+	assert(cmd_ctx != NULL);
+	struct target *target = get_current_target(cmd_ctx);
+
+	const size_t buffersize = 4096;
+	uint8_t *buffer = malloc(buffersize);
+
+	if (!buffer) {
+		LOG_ERROR("Failed to allocate memory");
+		return JIM_ERR;
+	}
+
+	Jim_Obj *result_list = Jim_NewListObj(interp, NULL, 0);
+	Jim_IncrRefCount(result_list);
+
+	while (count > 0) {
+		const unsigned int max_chunk_len = buffersize / width;
+		const size_t chunk_len = MIN(count, max_chunk_len);
+
+		int retval;
+
+		if (is_phys)
+			retval = target_read_phys_memory(target, addr, width, chunk_len, buffer);
+		else
+			retval = target_read_memory(target, addr, width, chunk_len, buffer);
+
+		if (retval != ERROR_OK) {
+			LOG_ERROR("read_memory: read at " TARGET_ADDR_FMT " with width=%u and count=%zu failed",
+				addr, width_bits, chunk_len);
+			Jim_SetResultString(interp, "read_memory: failed to read memory", -1);
+			e = JIM_ERR;
+			break;
+		}
+
+		for (size_t i = 0; i < chunk_len ; i++) {
+			uint64_t v = 0;
+
+			switch (width) {
+			case 8:
+				v = target_buffer_get_u64(target, &buffer[i * width]);
+				break;
+			case 4:
+				v = target_buffer_get_u32(target, &buffer[i * width]);
+				break;
+			case 2:
+				v = target_buffer_get_u16(target, &buffer[i * width]);
+				break;
+			case 1:
+				v = buffer[i];
+				break;
+			}
+
+			char value_buf[11];
+			snprintf(value_buf, sizeof(value_buf), "0x%" PRIx64, v);
+
+			Jim_ListAppendElement(interp, result_list,
+				Jim_NewStringObj(interp, value_buf, -1));
+		}
+
+		count -= chunk_len;
+		addr += chunk_len * width;
+	}
+
+	free(buffer);
+
+	if (e != JIM_OK) {
+		Jim_DecrRefCount(interp, result_list);
+		return e;
+	}
+
+	Jim_SetResult(interp, result_list);
+	Jim_DecrRefCount(interp, result_list);
+
+	return JIM_OK;
+}
+
 static int get_u64_array_element(Jim_Interp *interp, const char *varname, size_t idx, uint64_t *val)
 {
 	char *namebuf = alloc_printf("%s(%zu)", varname, idx);
@@ -4814,6 +4969,144 @@ static int target_array2mem(Jim_Interp *interp, struct target *target,
 	return e;
 }
 
+static int target_jim_write_memory(Jim_Interp *interp, int argc,
+		Jim_Obj * const *argv)
+{
+	/*
+	 * argv[1] = memory address
+	 * argv[2] = desired element width in bits
+	 * argv[3] = list of data to write
+	 * argv[4] = optional "phys"
+	 */
+
+	if (argc < 4 || argc > 5) {
+		Jim_WrongNumArgs(interp, 1, argv, "address width data ['phys']");
+		return JIM_ERR;
+	}
+
+	/* Arg 1: Memory address. */
+	int e;
+	jim_wide wide_addr;
+	e = Jim_GetWide(interp, argv[1], &wide_addr);
+
+	if (e != JIM_OK)
+		return e;
+
+	target_addr_t addr = (target_addr_t)wide_addr;
+
+	/* Arg 2: Bit width of one element. */
+	long l;
+	e = Jim_GetLong(interp, argv[2], &l);
+
+	if (e != JIM_OK)
+		return e;
+
+	const unsigned int width_bits = l;
+	size_t count = Jim_ListLength(interp, argv[3]);
+
+	/* Arg 4: Optional 'phys'. */
+	bool is_phys = false;
+
+	if (argc > 4) {
+		const char *phys = Jim_GetString(argv[4], NULL);
+
+		if (strcmp(phys, "phys")) {
+			Jim_SetResultFormatted(interp, "invalid argument '%s', must be 'phys'", phys);
+			return JIM_ERR;
+		}
+
+		is_phys = true;
+	}
+
+	switch (width_bits) {
+	case 8:
+	case 16:
+	case 32:
+	case 64:
+		break;
+	default:
+		Jim_SetResultString(interp, "invalid width, must be 8, 16, 32 or 64", -1);
+		return JIM_ERR;
+	}
+
+	const unsigned int width = width_bits / 8;
+
+	if ((addr + (count * width)) < addr) {
+		Jim_SetResultString(interp, "write_memory: addr + len wraps to zero", -1);
+		return JIM_ERR;
+	}
+
+	if (count > 65536) {
+		Jim_SetResultString(interp, "write_memory: too large memory write request, exceeds 64K elements", -1);
+		return JIM_ERR;
+	}
+
+	struct command_context *cmd_ctx = current_command_context(interp);
+	assert(cmd_ctx != NULL);
+	struct target *target = get_current_target(cmd_ctx);
+
+	const size_t buffersize = 4096;
+	uint8_t *buffer = malloc(buffersize);
+
+	if (!buffer) {
+		LOG_ERROR("Failed to allocate memory");
+		return JIM_ERR;
+	}
+
+	size_t j = 0;
+
+	while (count > 0) {
+		const unsigned int max_chunk_len = buffersize / width;
+		const size_t chunk_len = MIN(count, max_chunk_len);
+
+		for (size_t i = 0; i < chunk_len; i++, j++) {
+			Jim_Obj *tmp = Jim_ListGetIndex(interp, argv[3], j);
+			jim_wide element_wide;
+			Jim_GetWide(interp, tmp, &element_wide);
+
+			const uint64_t v = element_wide;
+
+			switch (width) {
+			case 8:
+				target_buffer_set_u64(target, &buffer[i * width], v);
+				break;
+			case 4:
+				target_buffer_set_u32(target, &buffer[i * width], v);
+				break;
+			case 2:
+				target_buffer_set_u16(target, &buffer[i * width], v);
+				break;
+			case 1:
+				buffer[i] = v & 0x0ff;
+				break;
+			}
+		}
+
+		count -= chunk_len;
+
+		int retval;
+
+		if (is_phys)
+			retval = target_write_phys_memory(target, addr, width, chunk_len, buffer);
+		else
+			retval = target_write_memory(target, addr, width, chunk_len, buffer);
+
+		if (retval != ERROR_OK) {
+			LOG_ERROR("write_memory: write at " TARGET_ADDR_FMT " with width=%u and count=%zu failed",
+				addr,  width_bits, chunk_len);
+			Jim_SetResultString(interp, "write_memory: failed to write memory", -1);
+			e = JIM_ERR;
+			break;
+		}
+
+		addr += chunk_len * width;
+	}
+
+	free(buffer);
+
+	return e;
+}
+
 /* FIX? should we propagate errors here rather than printing them
  * and continuing?
  */
@@ -5797,6 +6090,20 @@ static const struct command_registration target_instance_command_handlers[] = {
 		.help = "Set target register values",
 		.usage = "dict",
 	},
+	{
+		.name = "read_memory",
+		.mode = COMMAND_EXEC,
+		.jim_handler = target_jim_read_memory,
+		.help = "Read Tcl list of 8/16/32/64 bit numbers from target memory",
+		.usage = "address width count ['phys']",
+	},
+	{
+		.name = "write_memory",
+		.mode = COMMAND_EXEC,
+		.jim_handler = target_jim_write_memory,
+		.help = "Write Tcl list of 8/16/32/64 bit numbers to target memory",
+		.usage = "address width data ['phys']",
+	},
 	{
 		.name = "eventlist",
 		.handler = handle_target_event_list,
@@ -6893,6 +7200,20 @@ static const struct command_registration target_exec_command_handlers[] = {
 		.help = "Set target register values",
 		.usage = "dict",
 	},
+	{
+		.name = "read_memory",
+		.mode = COMMAND_EXEC,
+		.jim_handler = target_jim_read_memory,
+		.help = "Read Tcl list of 8/16/32/64 bit numbers from target memory",
+		.usage = "address width count ['phys']",
+	},
+	{
+		.name = "write_memory",
+		.mode = COMMAND_EXEC,
+		.jim_handler = target_jim_write_memory,
+		.help = "Write Tcl list of 8/16/32/64 bit numbers to target memory",
+		.usage = "address width data ['phys']",
+	},
 	{
 		.name = "reset_nag",
 		.handler = handle_target_reset_nag,