From 471c23a5835a28a35ac698910d1e9248be9ddf49 Mon Sep 17 00:00:00 2001
From: Tim Newsome <tim@sifive.com>
Date: Fri, 28 Oct 2022 11:02:49 -0700
Subject: [PATCH] target: Expose examine as a user command.

Change-Id: I7be9c75727cf78cedd438fec23374f3084c72be4
Signed-off-by: Tim Newsome <tim@sifive.com>
---
 doc/openocd.texi    |  8 ++++++++
 src/target/target.c | 24 ++++++++++++++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/doc/openocd.texi b/doc/openocd.texi
index e671b80b5..0b64f8fba 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -8712,6 +8712,14 @@ The other options will not work on all systems.
 @end itemize
 @end deffn
 
+@deffn {Command} {examine}
+Usually the target is examined during @command{init}, but some targets cannot be
+examined that early. (For instance, a target may be powered down until a
+different target releases it to run.) If this is the case, @command{examine} can
+be used to try to examine the target again after some extra setup has been
+performed.
+@end deffn
+
 @deffn {Command} {soft_reset_halt}
 Requesting target halt and executing a soft reset. This is often used
 when a target cannot be reset and halted. The target, after reset is
diff --git a/src/target/target.c b/src/target/target.c
index 30f2cf068..5c7494abc 100644
--- a/src/target/target.c
+++ b/src/target/target.c
@@ -3328,6 +3328,22 @@ COMMAND_HANDLER(handle_halt_command)
 	return CALL_COMMAND_HANDLER(handle_wait_halt_command);
 }
 
+COMMAND_HANDLER(handle_examine_command)
+{
+	LOG_DEBUG("-");
+
+	if (CMD_ARGC != 0) {
+		LOG_ERROR("The examine command takes no arguments.");
+		return ERROR_FAIL;
+	}
+
+	int retval = target_examine();
+	if (retval != ERROR_OK)
+		return retval;
+
+	return retval;
+}
+
 COMMAND_HANDLER(handle_soft_reset_halt_command)
 {
 	struct target *target = get_current_target(CMD_CTX);
@@ -6937,6 +6953,14 @@ nextw:
 }
 
 static const struct command_registration target_exec_command_handlers[] = {
+	{
+		.name = "examine",
+		.handler = handle_examine_command,
+		.mode = COMMAND_EXEC,
+		.help = "Examine the target, which can be useful if the target could"
+			"not be examined during init.",
+		.usage = "",
+	},
 	{
 		.name = "fast_load_image",
 		.handler = handle_fast_load_image_command,