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>

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 2bfa0deae37c636f688b324e32a94609b65b22f3..f9acedf69cd24ba3953a3caba473619b9743d82e 100644 (file)
--- a/doc/openocd.texi
+++ b/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,

diff --git a/src/target/target.c b/src/target/target.c
index b72dc53e3e4f57f87d811dadaea944cc0a1df2a2..473538ab7747cc9484c91c11a2c72ec5caaed5a7 100644 (file)
--- a/src/target/target.c
+++ b/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,